ارسال سفارش به سرور پاتریس
در روش «دریافت از طریق سرور پاتریس»، سایت هر سفارش جدید یا تغییرکرده را با POST /api/site/v1/orders به سرور پاتریس میفرستد. سرور سفارش را نگه میدارد و پاتریس یار را فوراً خبر میکند، پس سایت دیگر درخواست دورهای GET /wp-json/payava-patris/v1/orders دریافت نمیکند.
این روش کی مناسب است؟
- وقتی هاست سایت ضعیف است و درخواستهای دورهای پاتریس یار بار ایجاد میکنند.
- وقتی میخواهید سفارش بلافاصله پس از ثبت به پاتریس برسد.
این روش فقط وقتی کار میکند که پاتریس یار روی ویندوز ۱۰ یا ۱۱ اجرا شود و به حساب پاتریس وصل باشد.
پیشنیازها
- همهی endpointهای سایت، از جمله
GET /wp-json/payava-patris/v1/orders،POST /wp-json/payava-patris/v1/orders/delivered،POST /wp-json/payava-patris/v1/orders/:id/ackوPOST /wp-json/payava-patris/v1/products، پیادهسازی شده باشند. - امکان «ارسال سفارشها از طریق سرور پاتریس» برای حساب پاتریس فعال باشد. این امکان بدون «فروشگاه اینترنتی» فعال نمیشود.
GET /wp-json/payava-patris/v1/pingمقدارorder_modeراcloudبرگرداند.- در پاتریس یار برای این اتصال «دریافت از طریق سرور پاتریس» انتخاب شده باشد.
Endpoint
POST https://patrisyar.payava.com/api/site/v1/orders
هدرها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
X-Payava-Key | string | بله | کلید API حساب پاتریس؛ همان کلید سایت. |
Content-Type | string | بله | application/json; charset=utf-8 |
پارامترها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
siteUrl | string | بله | آدرس اصلی سایت. دامنهی (host) آن باید همان دامنهی «آدرس سایت» در پاتریس یار باشد. |
pluginVersion | string | خیر | نسخهی پیادهسازی شما، مثل custom-1.0.0. |
orders | array | بله | حداکثر ۵۰ سفارش با ساختن آرایهی سفارش. |
کدام سفارشها و کی ارسال شوند؟
- هنگام ثبت سفارش و هنگام تغییر وضعیت آن، اگر وضعیت از وضعیتهای مجاز باشد و سفارش هنوز به پاتریس تحویل نشده باشد.
- ارسال را در پسزمینه (صف یا job) انجام دهید. ثبت سفارش مشتری نباید منتظر سرور پاتریس بماند.
- هر سفارش را تا وقتی سرور نپذیرفته، در حالت «در انتظار ارسال» نگه دارید.
پیادهسازی در وردپرس
add_action('woocommerce_order_status_changed', function ($order_id, $from, $to) {
if (get_option('my_patris_order_mode') !== 'cloud' || !in_array($to, ['processing', 'on-hold'], true)) {
return;
}
$order = wc_get_order($order_id);
if (!$order || $order->get_meta('_my_patris_delivered')) {
return;
}
$order->update_meta_data('_my_patris_cloud', 'pending');
$order->save();
as_enqueue_async_action('my_patris_cloud_send', [], 'my-patris'); // Action Scheduler (part of WooCommerce)
}, 10, 3);
add_action('my_patris_cloud_send', function () {
$orders = wc_get_orders(['limit' => 50, 'type' => 'shop_order',
'meta_query' => [['key' => '_my_patris_cloud', 'value' => 'pending']]]);
if (!$orders) {
return;
}
$factor = (float) get_option('my_patris_price_factor', 1) ?: 1.0;
$response = wp_remote_post(rtrim(PATRIS_CLOUD_URL, '/') . '/api/site/v1/orders', [
'timeout' => 20,
'headers' => [
'Content-Type' => 'application/json; charset=utf-8',
'X-Payava-Key' => (string) get_option('my_patris_api_key'),
],
'body' => wp_json_encode([
'siteUrl' => home_url(),
'pluginVersion' => 'my-patris-connector-1.0.0',
'orders' => array_map(fn ($o) => my_patris_order_to_array($o, $factor), $orders),
]),
]);
$code = is_wp_error($response) ? 0 : (int) wp_remote_retrieve_response_code($response);
if ($code < 200 || $code >= 300) {
// network error, 401 / 403 / 409 / 429 / 5xx: keep them pending and try again later
$wait = $code === 429 ? max(60, (int) wp_remote_retrieve_header($response, 'retry-after')) : 15 * MINUTE_IN_SECONDS;
as_schedule_single_action(time() + $wait, 'my_patris_cloud_send', [], 'my-patris');
return;
}
$body = json_decode(wp_remote_retrieve_body($response), true);
foreach ((array) ($body['results'] ?? []) as $item) {
$order = wc_get_order((int) $item['id']);
if ($order) {
$order->update_meta_data('_my_patris_cloud', $item['status'] === 'invalid' ? 'invalid' : 'sent');
$order->save();
}
}
});
نمونه پاسخ موفق
{
"ok": true,
"stored": 1,
"updated": 0,
"alreadyDelivered": 0,
"invalid": 0,
"results": [
{ "id": "1532", "status": "stored", "message": null }
]
}
مقدارهای status در results
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
stored | string | — | سفارش جدید ذخیره شد. سفارش را «ارسالشده» علامت بزنید. |
updated | string | — | سفارش قبلاً ارسال شده بود و نسخهی جدید جایگزین شد. «ارسالشده» علامت بزنید. |
already_delivered | string | — | سفارش قبلاً به پاتریس تحویل شده و تغییر نادیده گرفته شد. «ارسالشده» علامت بزنید. |
invalid | string | — | سفارش نامعتبر است (مثلاً id ندارد یا خیلی بزرگ است). علت در message است. دوباره ارسال نکنید. |
کدهای خطا
پاسخ خطا با قالب ProblemDetails است: title کد وضعیت و detail پیام فارسی قابلنمایش به مدیر سایت.
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
400 | invalid_site_url | — | siteUrl خالی یا نامعتبر است. |
400 | too_many_orders | — | بیش از ۵۰ سفارش در یک درخواست. |
401 | unknown_key | — | کلید ارسال نشده یا در سامانهی پاتریس پیدا نشد. |
403 | revoked | — | کلید باطل شده است. |
403 | tenant_inactive | — | حساب پاتریس غیرفعال است. |
403 | no_subscription | — | اشتراک حساب پاتریس فعال نیست یا تمام شده است. |
403 | ip_not_allowed | — | IP سرور سایت برای این کلید مجاز نیست. |
403 | scope_missing | — | امکان «ارسال سفارشها از طریق سرور پاتریس» برای این حساب فعال نیست. |
409 | conflict | — | دو ارسال همزمانِ یک سفارش جدید. کمی بعد دوباره بفرستید. |
429 | rate_limited | — | تعداد درخواستهای این کلید در دقیقه از حد مجاز گذشته است. پس از ثانیههای هدر Retry-After دوباره بفرستید. |
اگر ارسال شکست خورد چه کنم؟
سفارشها را در حالت «در انتظار ارسال» نگه دارید و دوباره تلاش کنید. این زمانبندی پیشنهاد میشود:
- تلاش دوم پس از ۱ دقیقه.
- تلاش سوم پس از ۵ دقیقه.
- تلاش چهارم پس از ۱۵ دقیقه.
- پس از آن هر ۶۰ دقیقه، تا وقتی سرور بپذیرد.
برای 401 و 403 هم همین کار را بکنید و متن detail را به مدیر سایت نشان دهید. وقتی پشتیبانی پایاوا مشکل را رفع کند، تلاش بعدی موفق میشود.
نکتهها
پس از ارسال به سرور، سفارش را «تحویلشده به پاتریس» علامت نزنید. پاتریس یار پس از دریافت سفارش از سرور، خودش POST /wp-json/payava-patris/v1/orders/delivered را صدا میزند. تا آن زمان سفارش باید در GET /wp-json/payava-patris/v1/orders بیاید تا اگر سرور در دسترس نبود، با گذاشتن اتصال روی «دریافت مستقیم از همین اتصال» سفارشها مستقیم از سایت گرفته شوند.
- تغییر وضعیت سفارشی که قبلاً ارسال شده را دوباره بفرستید. سرور تا پیش از تحویل، نسخهی جدید را جایگزین میکند.
- در هر درخواست حداکثر ۵۰ سفارش بفرستید. حجم کل بدنه حداکثر ۱۶ مگابایت است.
- اگر API روی دامنهی دیگری است (مثلاً
api.example.comو سایتshop.example.com)، درsiteUrlهمان دامنهی API را بفرستید. پاتریس یار سفارشهای سرور را با دامنه به همین اتصال نسبت میدهد و فقط در این صورتPOST /wp-json/payava-patris/v1/orders/deliveredرا برای آنها صدا میزند. - اگر سفارشها را با کلید دیگری بفرستید، پاتریس یاری که کلید قبلی را دارد آنها را نمیبیند. کلید سایت و پاتریس یار همیشه یکی باشد.