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

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

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

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

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

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

پیش‌نیازها​

Endpoint​

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

هدرها​

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

پارامترها​

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

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

  • هنگام ثبت سفارش و هنگام تغییر وضعیت آن، اگر وضعیت از وضعیت‌های مجاز باشد و سفارش هنوز به پاتریس تحویل نشده باشد.
  • ارسال را در پس‌زمینه (صف یا job) انجام دهید. ثبت سفارش مشتری نباید منتظر سرور پاتریس بماند.
  • هر سفارش را تا وقتی سرور نپذیرفته، در حالت «در انتظار ارسال» نگه دارید.

نمونه درخواست​

ارسال سفارش به سرور
curl -X POST https://PATRIS_CLOUD_URL/api/site/v1/orders \
-H "X-Payava-Key: YOUR_API_KEY" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"siteUrl":"https://shop.example.com","pluginVersion":"custom-1.0.0","orders":[{"id":1532,"number":"1532","status":"processing","created":"2026-11-07T10:42:13+03:30","customer_name":"علی رضایی","phone":"09120000000","subtotal":2400000,"discount":200000,"shipping":300000,"total":2500000,"lines":[{"pip":"101009001","sku":"","name":"لنت ترمز جلو","quantity":2,"unit_price":1200000,"discount":200000}]}]}'

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

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 /patris-yar/orders/delivered را صدا می‌زند. تا آن زمان سفارش باید در GET /patris-yar/orders بیاید تا اگر سرور در دسترس نبود، با گذاشتن اتصال روی «دریافت مستقیم از همین اتصال» سفارش‌ها مستقیم از سایت گرفته شوند.

  • تغییر وضعیت سفارشی که قبلاً ارسال شده را دوباره بفرستید. سرور تا پیش از تحویل، نسخه‌ی جدید را جایگزین می‌کند.
  • در هر درخواست حداکثر ۵۰ سفارش بفرستید. حجم کل بدنه حداکثر ۱۶ مگابایت است.
  • اگر API روی دامنه‌ی دیگری است (مثلاً api.example.com و سایت shop.example.com)، در siteUrl همان دامنه‌ی API را بفرستید. پاتریس یار سفارش‌های سرور را با دامنه به همین اتصال نسبت می‌دهد و فقط در این صورت POST /patris-yar/orders/delivered را برای آن‌ها صدا می‌زند.
  • اگر سفارش‌ها را با کلید دیگری بفرستید، پاتریس یاری که کلید قبلی را دارد آن‌ها را نمی‌بیند. کلید سایت و پاتریس یار همیشه یکی باشد.