اعلام وضعیت سفارش در پاتریس
پاتریس یار هر بار که وضعیت یک سفارش در پاتریس تغییر کند، آن را به POST /wp-json/payava-patris/v1/orders/:id/ack میفرستد. سایت میتواند این وضعیت را در تاریخچهی سفارش ثبت کند یا به مشتری نشان دهد.
این endpoint کی صدا زده میشود؟
در هر دور همگامسازی، برای حداکثر ۵۰ سفارشی که وضعیتشان در پاتریس عوض شده و هنوز به سایت اعلام نشده است. اگر پاسخ موفق نباشد، پاتریس یار همان اعلام را در دور بعد تکرار میکند.
پیشنیازها
- مسیرها و احراز هویت در وردپرس
- سفارش قبلاً با
GET /wp-json/payava-patris/v1/ordersیا از طریق سرور پاتریس به پاتریس رسیده باشد.
Endpoint
POST /wp-json/payava-patris/v1/orders/1532/ack
هدرها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
X-Payava-Key | string | بله | کلید API حساب پاتریس. |
Content-Type | string | بله | application/json; charset=utf-8 |
پارامترها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
id | integer (path) | بله | شناسهی سفارش در سایت. |
patris_order_id | integer | بله | شمارهی سفارش در پاتریس. |
status | string | بله | کاری که پاتریس با سفارش کرد. جدول بعد را ببینید. |
state | string یا null | خیر | وضعیت متنی سفارش در پاتریس. ممکن است null باشد. |
archive | integer | خیر | کد بایگانی سفارش در پاتریس. |
مقدارهای status
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
read | string | — | سفارش در پاتریس دریافت شد. |
submitted | string | — | سفارش در پاتریس ثبت شد. |
confirmed | string | — | سفارش در پاتریس تأیید یا بایگانی شد. |
edited | string | — | سفارش در پاتریس ویرایش شد؛ ممکن است تعداد یا مبلغ تغییر کرده باشد. |
deleted | string | — | سفارش در پاتریس حذف شد. |
مقدار ناشناخته را مثل 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 }
کدهای خطا
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
401 | payava_patris_unauthorized | — | کلید نادرست است. |
404 | payava_patris_not_found | — | سفارش در سایت پیدا نشد. |
400 | invalid_json | — | بدنهی درخواست JSON معتبر نیست. |
نکتهها
پاسخ ناموفق تکرار میشود
پاتریس یار اعلام وضعیت را تا وقتی پاسخ موفق نگیرد، در هر دور تکرار میکند و خطا را در وضعیت اتصال نشان میدهد. سفارشهایی را که از سایت حذف میکنید، بهجای حذف کامل غیرفعال کنید تا این endpoint برای آنها 404 ندهد.
- یک وضعیت ممکن است دو بار برسد (مثلاً وقتی پاسخ قبلی گم شده). ذخیره را idempotent بنویسید.
statusبا مقدارeditedیعنی پاتریس سفارش را تغییر داده است. اقلام و مبلغ جدید در این درخواست ارسال نمیشوند؛ فقط وضعیت میرسد.