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

ارسال سفارش به سرور پاتریس

در روش «دریافت از طریق سرور پاتریس»، سایت هر سفارش جدید یا تغییرکرده را با POST /api/site/v1/orders به سرور پاتریس می‌فرستد. سرور سفارش را نگه می‌دارد و پاتریس یار را فوراً خبر می‌کند، پس سایت دیگر درخواست دوره‌ای GET /wp-json/payava-patris/v1/orders دریافت نمی‌کند.

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

  • وقتی هاست سایت ضعیف است و درخواست‌های دوره‌ای پاتریس یار بار ایجاد می‌کنند.
  • وقتی می‌خواهید سفارش بلافاصله پس از ثبت به پاتریس برسد.

این روش فقط وقتی کار می‌کند که پاتریس یار روی ویندوز ۱۰ یا ۱۱ اجرا شود و به حساب پاتریس وصل باشد.

پیش‌نیازها​

Endpoint​

POST https://patrisyar.payava.com/api/site/v1/orders

هدرها​

نامنوعالزامیتوضیح
X-Payava-Keystringبلهکلید API حساب پاتریس؛ همان کلید سایت.
Content-Typestringبلهapplication/json; charset=utf-8

پارامترها​

نامنوعالزامیتوضیح
siteUrlstringبلهآدرس اصلی سایت. دامنه‌ی (host) آن باید همان دامنه‌ی «آدرس سایت» در پاتریس یار باشد.
pluginVersionstringخیرنسخه‌ی پیاده‌سازی شما، مثل custom-1.0.0.
ordersarrayبلهحداکثر ۵۰ سفارش با ساختن آرایه‌ی سفارش.

کدام سفارش‌ها و کی ارسال شوند؟​

  • هنگام ثبت سفارش و هنگام تغییر وضعیت آن، اگر وضعیت از وضعیت‌های مجاز باشد و سفارش هنوز به پاتریس تحویل نشده باشد.
  • ارسال را در پس‌زمینه (صف یا 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();
}
}
});

نمونه پاسخ موفق​

200 OK
{
"ok": true,
"stored": 1,
"updated": 0,
"alreadyDelivered": 0,
"invalid": 0,
"results": [
{ "id": "1532", "status": "stored", "message": null }
]
}

مقدارهای status در results​

نامنوعالزامیتوضیح
storedstring—سفارش جدید ذخیره شد. سفارش را «ارسال‌شده» علامت بزنید.
updatedstring—سفارش قبلاً ارسال شده بود و نسخه‌ی جدید جایگزین شد. «ارسال‌شده» علامت بزنید.
already_deliveredstring—سفارش قبلاً به پاتریس تحویل شده و تغییر نادیده گرفته شد. «ارسال‌شده» علامت بزنید.
invalidstring—سفارش نامعتبر است (مثلاً id ندارد یا خیلی بزرگ است). علت در message است. دوباره ارسال نکنید.

کدهای خطا​

پاسخ خطا با قالب ProblemDetails است: title کد وضعیت و detail پیام فارسی قابل‌نمایش به مدیر سایت.

نامنوعالزامیتوضیح
400invalid_site_url—siteUrl خالی یا نامعتبر است.
400too_many_orders—بیش از ۵۰ سفارش در یک درخواست.
401unknown_key—کلید ارسال نشده یا در سامانه‌ی پاتریس پیدا نشد.
403revoked—کلید باطل شده است.
403tenant_inactive—حساب پاتریس غیرفعال است.
403no_subscription—اشتراک حساب پاتریس فعال نیست یا تمام شده است.
403ip_not_allowed—IP سرور سایت برای این کلید مجاز نیست.
403scope_missing—امکان «ارسال سفارش‌ها از طریق سرور پاتریس» برای این حساب فعال نیست.
409conflict—دو ارسال هم‌زمانِ یک سفارش جدید. کمی بعد دوباره بفرستید.
429rate_limited—تعداد درخواست‌های این کلید در دقیقه از حد مجاز گذشته است. پس از ثانیه‌های هدر Retry-After دوباره بفرستید.

اگر ارسال شکست خورد چه کنم؟​

سفارش‌ها را در حالت «در انتظار ارسال» نگه دارید و دوباره تلاش کنید. این زمان‌بندی پیشنهاد می‌شود:

  1. تلاش دوم پس از ۱ دقیقه.
  2. تلاش سوم پس از ۵ دقیقه.
  3. تلاش چهارم پس از ۱۵ دقیقه.
  4. پس از آن هر ۶۰ دقیقه، تا وقتی سرور بپذیرد.

برای 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 را برای آن‌ها صدا می‌زند.
  • اگر سفارش‌ها را با کلید دیگری بفرستید، پاتریس یاری که کلید قبلی را دارد آن‌ها را نمی‌بیند. کلید سایت و پاتریس یار همیشه یکی باشد.