پرش به مطلب اصلی

نوشتن افزونه‌ی اختصاصی وردپرس برای پاتریس یار

اگر افزونه‌ی آماده‌ی «Payava Patris Connector» نیازتان را برآورده نمی‌کند، می‌توانید افزونه‌ی وردپرس خودتان را بنویسید و در پاتریس یار همان اتصال «WordPress (افزونه‌ی پاتریس یار)» را به کار ببرید. کافی است افزونه‌ی شما مسیرهای این بخش را با همان قالب JSON ثبت کند.

این روش کی مناسب است؟​

  • منطق سفارش، قیمت یا موجودی فروشگاه شما خاص است (مثلاً چند انبار، قیمت‌گذاری اختصاصی یا افزونه‌ی فروشگاه دیگری کنار ووکامرس).
  • می‌خواهید داده‌ها در جدول‌ها یا سیستم خودتان ذخیره شوند.

اگر سایت وردپرسی نیست، راهنمای اتصال سایت اختصاصی به پاتریس یار را ببینید.

مسیرها کجا قرار می‌گیرند؟​

پاتریس یار در اتصال WordPress، مسیر ثابت /wp-json/payava-patris/v1 را به آدرس سایت اضافه می‌کند. پس افزونه‌ی شما باید مسیرها را در namespace دقیقاً payava-patris/v1 ثبت کند:

نامنوعالزامیتوضیح
GET /pingفروشگاه و مای پاتریسبلهتست اتصال و کلید.
GET /ordersفروشگاهبرای دریافت سفارشسفارش‌های تحویل‌نشده.
GET /orders/:idفروشگاهبرای دریافت سفارشخواندن دوباره‌ی یک سفارش.
POST /orders/deliveredفروشگاهبرای دریافت سفارشعلامت تحویل سفارش‌ها.
POST /orders/:id/ackفروشگاهبرای دریافت سفارشوضعیت سفارش در پاتریس.
POST /productsفروشگاه و مای پاتریسبرای قیمت و موجودیکالاها، قیمت و موجودی.
GET /mypatris/summaryمای پاتریسبرای مای پاتریستست مای پاتریس.
POST /mypatris/personsمای پاتریسبرای مای پاتریساشخاص و مانده‌حساب.
POST /mypatris/statementsمای پاتریسبرای مای پاتریسصورت‌حساب اشخاص.

مسیرهای جدول نسبت به /wp-json/payava-patris/v1 هستند. مثلاً GET /ping یعنی GET https://shop.example.com/wp-json/payava-patris/v1/ping.

دو فراخوانی هم از سایت به سرور پاتریس است: ارسال سفارش به سرور پاتریس و بررسی کلید با سرور پاتریس.

کلید را چطور بررسی کنم؟​

هر درخواست پاتریس یار کلید API را در هدر X-Payava-Key می‌فرستد. همه‌ی مسیرها باید یک permission_callback داشته باشند که این هدر را با کلید ذخیره‌شده مقایسه کند:

نامنوعالزامیتوضیح
X-Payava-Keystringبلهکلید ppk_ حساب پاتریس که پشتیبانی پایاوا می‌سازد. همان کلیدی که در پاتریس یار وارد می‌شود.
Content-Typestringبرای POSTapplication/json; charset=utf-8، بدون فشرده‌سازی.

اعتبار کلید، اشتراک و امکانات حساب را پاتریس یار خودش با سرور پاتریس بررسی می‌کند. افزونه فقط برابری کلید را می‌سنجد.

اسکلت افزونه​

wp-content/plugins/my-patris-connector/my-patris-connector.php
<?php
/**
* Plugin Name: My Patris Connector
* Description: Custom connection between WooCommerce and Patris Yar.
* Version: 1.0.0
* Requires PHP: 7.4
*/
if (!defined('ABSPATH')) {
exit;
}

const MY_PATRIS_NS = 'payava-patris/v1'; // fixed: Patris Yar calls /wp-json/payava-patris/v1/...
const PATRIS_CLOUD_URL = 'https://PATRIS_CLOUD_URL'; // only for sending orders to the Patris server

function my_patris_authorize(WP_REST_Request $request)
{
$expected = trim((string) get_option('my_patris_api_key', ''));
$given = (string) $request->get_header('X-Payava-Key');
if ($expected === '' || $given === '' || !hash_equals($expected, $given)) {
return new WP_Error('payava_patris_unauthorized', 'Invalid API key', ['status' => 401]);
}
return true;
}

add_action('rest_api_init', function () {
$routes = [
['GET', '/ping', 'my_patris_ping'],
['GET', '/orders', 'my_patris_orders'],
['POST', '/orders/delivered', 'my_patris_delivered'],
['GET', '/orders/(?P<id>\d+)', 'my_patris_order'],
['POST', '/orders/(?P<id>\d+)/ack', 'my_patris_ack'],
['POST', '/products', 'my_patris_products'],
['GET', '/mypatris/summary', 'my_patris_mypatris_summary'],
['POST', '/mypatris/persons', 'my_patris_mypatris_persons'],
['POST', '/mypatris/statements', 'my_patris_mypatris_statements'],
];
foreach ($routes as [$method, $route, $callback]) {
register_rest_route(MY_PATRIS_NS, $route, [
'methods' => $method,
'callback' => $callback,
'permission_callback' => 'my_patris_authorize',
]);
}
});

// my_patris_ping(), my_patris_orders(), ... : see the next pages

تابع هر مسیر در صفحه‌ی همان مسیر آمده است. مسیرهای مای پاتریس را فقط اگر مای پاتریس لازم است ثبت کنید.

خطاها را چطور برگردانم؟​

WP_Error را برگردانید. وردپرس آن را به JSON با code، message و data تبدیل می‌کند و پاتریس یار code و message را می‌خواند:

پاسخ خطا
return new WP_Error('payava_patris_license', 'اشتراک این فروشگاه تمام شده است.', ['status' => 403]);
نامنوعالزامیتوضیح
401 یا 403هر code—پاتریس یار می‌گوید کلید API پذیرفته نشد.
403payava_patris_license—پاتریس یار می‌گوید «سایت اتصال را نپذیرفت» و message را کنارش نشان می‌دهد. برای ردِ آگاهانه با پیام دلخواه.
404هر code—پاتریس یار می‌گوید مسیر اتصال روی سایت پیدا نشد. استثنا: GET /orders/:id که 404 آن یعنی سفارش وجود ندارد.
429هر code—پاتریس یار دور بعد دوباره تلاش می‌کند.
سایر کدهاهر code—پاتریس یار کد HTTP و code (یا message) را نشان می‌دهد و دور بعد دوباره تلاش می‌کند.

نکته‌ها​

همراه افزونه‌ی آماده فعال نکنید

افزونه‌ی اختصاصی و «Payava Patris Connector» هر دو namespace payava-patris/v1 را ثبت می‌کنند. فقط یکی از آن‌ها باید فعال باشد.

  • «پیوندهای یکتا» نباید روی «ساده» باشد؛ در غیر این صورت /wp-json/ پاسخ نمی‌دهد.
  • افزونه‌های امنیتی که REST API را برای کاربران واردنشده می‌بندند، باید مسیر /wp-json/payava-patris/ را مجاز کنند. جزئیات در اتصال در پاتریس یار و رفع مشکل.
  • درخواست‌ها از رایانه‌ی فروشگاه می‌آیند و مهلت هر درخواست ۱۲۰ ثانیه است.
  • برای سفارش‌ها از wc_get_orders و WC_Order استفاده کنید تا افزونه با جدول‌های سفارش جدید ووکامرس (HPOS) هم کار کند.