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

اعلام وضعیت سفارش در پاتریس

پاتریس یار هر بار که وضعیت یک سفارش در پاتریس تغییر کند، آن را به POST /wp-json/payava-patris/v1/orders/:id/ack می‌فرستد. سایت می‌تواند این وضعیت را در تاریخچه‌ی سفارش ثبت کند یا به مشتری نشان دهد.

این endpoint کی صدا زده می‌شود؟​

در هر دور همگام‌سازی، برای حداکثر ۵۰ سفارشی که وضعیتشان در پاتریس عوض شده و هنوز به سایت اعلام نشده است. اگر پاسخ موفق نباشد، پاتریس یار همان اعلام را در دور بعد تکرار می‌کند.

پیش‌نیازها​

Endpoint​

POST /wp-json/payava-patris/v1/orders/1532/ack

هدرها​

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

پارامترها​

نامنوعالزامیتوضیح
idinteger (path)بلهشناسه‌ی سفارش در سایت.
patris_order_idintegerبلهشماره‌ی سفارش در پاتریس.
statusstringبلهکاری که پاتریس با سفارش کرد. جدول بعد را ببینید.
statestring یا nullخیروضعیت متنی سفارش در پاتریس. ممکن است null باشد.
archiveintegerخیرکد بایگانی سفارش در پاتریس.

مقدارهای status​

نامنوعالزامیتوضیح
readstring—سفارش در پاتریس دریافت شد.
submittedstring—سفارش در پاتریس ثبت شد.
confirmedstring—سفارش در پاتریس تأیید یا بایگانی شد.
editedstring—سفارش در پاتریس ویرایش شد؛ ممکن است تعداد یا مبلغ تغییر کرده باشد.
deletedstring—سفارش در پاتریس حذف شد.

مقدار ناشناخته را مثل read در نظر بگیرید.

پیاده‌سازی در وردپرس​

POST /orders/:id/ack
function my_patris_ack(WP_REST_Request $request)
{
$order = wc_get_order((int) $request['id']);
if (!$order) {
return new WP_Error('payava_patris_not_found', 'Order not found', ['status' => 404]);
}
$labels = [
'read' => 'سفارش در پاتریس دریافت شد',
'submitted' => 'سفارش در پاتریس ثبت شد',
'confirmed' => 'سفارش در پاتریس تأیید / بایگانی شد',
'edited' => 'سفارش در پاتریس ویرایش شد',
'deleted' => 'سفارش در پاتریس حذف شد',
];
$status = (string) $request->get_param('status');
$label = $labels[$status] ?? $labels['read'];
$patrisId = (int) $request->get_param('patris_order_id');
$state = sanitize_text_field((string) $request->get_param('state'));

$order->update_meta_data('_my_patris_order_id', $patrisId);
$order->update_meta_data('_my_patris_status', sanitize_key($status));
$order->add_order_note(sprintf('%s (شماره‌ی سفارش در پاتریس: %d)%s.', $label, $patrisId, $state !== '' ? ' — وضعیت: ' . $state : ''));
$order->save();
return ['ok' => true];
}

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

200 OK
{ "ok": true }

کدهای خطا​

نامنوعالزامیتوضیح
401payava_patris_unauthorized—کلید نادرست است.
404payava_patris_not_found—سفارش در سایت پیدا نشد.
400invalid_json—بدنه‌ی درخواست JSON معتبر نیست.

نکته‌ها​

پاسخ ناموفق تکرار می‌شود

پاتریس یار اعلام وضعیت را تا وقتی پاسخ موفق نگیرد، در هر دور تکرار می‌کند و خطا را در وضعیت اتصال نشان می‌دهد. سفارش‌هایی را که از سایت حذف می‌کنید، به‌جای حذف کامل غیرفعال کنید تا این endpoint برای آن‌ها 404 ندهد.

  • یک وضعیت ممکن است دو بار برسد (مثلاً وقتی پاسخ قبلی گم شده). ذخیره را idempotent بنویسید.
  • status با مقدار edited یعنی پاتریس سفارش را تغییر داده است. اقلام و مبلغ جدید در این درخواست ارسال نمی‌شوند؛ فقط وضعیت می‌رسد.