نوشتن افزونهی اختصاصی وردپرس برای پاتریس یار
اگر افزونهی آمادهی «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-Key | string | بله | کلید ppk_ حساب پاتریس که پشتیبانی پایاوا میسازد. همان کلیدی که در پاتریس یار وارد میشود. |
Content-Type | string | برای POST | application/json; charset=utf-8، بدون فشردهسازی. |
اعتبار کلید، اشتراک و امکانات حساب را پاتریس یار خودش با سرور پاتریس بررسی میکند. افزونه فقط برابری کلید را میسنجد.
اسکلت افزونه
<?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 پذیرفته نشد. |
403 | payava_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) هم کار کند.