دریافت سفارشهای جدید
پاتریس یار با GET /patris-yar/orders سفارشهایی را میگیرد که هنوز به پاتریس تحویل نشدهاند. سایت باید فقط سفارشهای تحویلنشده را، از قدیمی به جدید، برگرداند.
پاتریس یار سفارشها را چطور میگیرد؟
- پاتریس یار
GET /patris-yar/orders?limit=50را صدا میزند. - سفارشها را در پاتریس ذخیره میکند.
- شناسهی همهی سفارشهای دریافتی را به
POST /patris-yar/orders/deliveredمیفرستد. - اگر پاسخ خالی نبود، دوباره از مرحلهی ۱ شروع میکند (حداکثر ۲۰ صفحه در هر دور).
این کار وقتی روش اتصال در پاتریس یار «دریافت مستقیم از همین اتصال» است، در فاصلهی زمانی تنظیمشده انجام میشود.
پیشنیازها
- مسیرها و احراز هویت
- قالب سفارش
- سایت باید برای هر سفارش علامت «تحویل به پاتریس» را نگه دارد (مثلاً ستون
patris_delivered_at).
Endpoint
GET /patris-yar/orders?limit=50
هدرها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
X-Payava-Key | string | بله | کلید API حساب پاتریس. |
پارامترها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
limit | integer (query) | خیر | حداکثر تعداد سفارش در پاسخ. پاتریس یار 50 میفرستد. مقدار را بین 1 و 100 محدود کنید. |
کدام سفارشها برگردانده شوند؟
- سفارشهایی که هنوز با
POST /patris-yar/orders/deliveredتحویل نشدهاند. - فقط وضعیتهایی که میخواهید به پاتریس برسند، مثلاً
processingوon-hold. - فقط سفارشهای ثبتشده پس از تاریخ شروع اتصال، تا کل سفارشهای قدیمی به پاتریس نرود.
- مرتبشده بر اساس زمان ثبت، از قدیمی به جدید.
نمونه درخواست و پیادهسازی
- curl
- C#
- Python
- PHP
- Node.js
- Go
دریافت سفارشها
curl "https://shop.example.com/patris-yar/orders?limit=50" \
-H "X-Payava-Key: YOUR_API_KEY"
GET /orders
patris.MapGet("/orders", async (int? limit, IShopStore store) =>
{
var take = Math.Clamp(limit ?? 50, 1, 100);
// undelivered, allowed statuses, created after the start date, oldest first
var orders = await store.GetUndeliveredOrdersAsync(take);
return Results.Json(new { orders = orders.Select(PatrisOrderMapper.ToPatris) });
});
GET /orders
@router.get("/orders")
def orders(limit: int = 50):
take = max(1, min(100, limit))
# undelivered, allowed statuses, created after the start date, oldest first
rows = store.get_undelivered_orders(take)
return {"orders": [to_patris_order(o) for o in rows]}
GET /orders
if ($method === 'GET' && $route === '/orders') {
$limit = max(1, min(100, (int) ($_GET['limit'] ?? 50)));
// undelivered, allowed statuses, created after the start date, oldest first
$orders = $store->undeliveredOrders($limit);
respond(200, ['orders' => array_map('to_patris_order', $orders)]);
}
GET /orders
router.get('/orders', async (req, res, next) => {
try {
const limit = Math.max(1, Math.min(100, parseInt(req.query.limit, 10) || 50));
// undelivered, allowed statuses, created after the start date, oldest first
const orders = await store.getUndeliveredOrders(limit);
res.json({ orders: orders.map(toPatrisOrder) });
} catch (err) {
next(err);
}
});
GET /orders
func orders(w http.ResponseWriter, r *http.Request) {
limit, err := strconv.Atoi(r.URL.Query().Get("limit"))
if err != nil || limit < 1 {
limit = 50
}
limit = min(limit, 100)
// undelivered, allowed statuses, created after the start date, oldest first
list, err := store.UndeliveredOrders(r.Context(), limit)
if err != nil {
writeJSON(w, http.StatusInternalServerError, map[string]string{"code": "server_error", "message": err.Error()})
return
}
out := make([]PatrisOrder, 0, len(list))
for _, o := range list {
out = append(out, toPatrisOrder(o))
}
writeJSON(w, http.StatusOK, map[string]any{"orders": out})
}
// patris.HandleFunc("GET "+base+"/orders", orders)
تابع to_patris_order (یا PatrisOrderMapper.ToPatris، toPatrisOrder) سفارش سایت را به قالب سفارش تبدیل میکند و مبلغها را به واحد پاتریس میبرد.
نمونه پاسخ موفق
200 OK
{
"orders": [
{
"id": 1532,
"number": "1532",
"status": "processing",
"created": "2026-11-07T10:42:13+03:30",
"customer_name": "علی رضایی",
"username": "",
"user_mobile": "",
"phone": "09120000000",
"email": "",
"country": "IR",
"state": "تهران",
"city": "تهران",
"address": "خیابان نمونه، پلاک ۱",
"postcode": "1234567890",
"subtotal": 2400000,
"discount": 200000,
"shipping": 300000,
"total": 2500000,
"transaction_id": "",
"order_key": "",
"note": "",
"visitor_code": 0,
"visitor_name": "",
"lines": [
{ "pip": "101009001", "sku": "", "name": "لنت ترمز جلو", "quantity": 2, "unit_price": 1200000, "discount": 200000 }
]
}
]
}
سفارش جدیدی نیست؟ آرایهی خالی برگردانید:
200 OK
{ "orders": [] }
کدهای خطا
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
401 | payava_patris_unauthorized | — | کلید نادرست است. |
429 | — | — | سایت درخواست را محدود کرده است. پاتریس یار دور بعد دوباره تلاش میکند. |
500 | — | — | خطای سایت. پاتریس یار متن message را نشان میدهد و دور بعد دوباره تلاش میکند. |
نکتهها
سفارش تحویلشده را دوباره برنگردانید
اگر سایت پس از POST /patris-yar/orders/delivered همان سفارشها را دوباره برگرداند، پاتریس یار در هر دور ۲۰ بار همان صفحه را میخواند. پاتریس سفارش تکراری ثبت نمیکند، ولی بار بیدلیل روی سایت میماند.
- در روش «دریافت از طریق سرور پاتریس» هم این endpoint را نگه دارید. اگر سرور در دسترس نباشد، با گذاشتن اتصال روی «دریافت مستقیم از همین اتصال» سفارشها از همین endpoint گرفته میشوند.
- برای کارایی، روی ستونهای وضعیت، زمان ثبت و علامت تحویل index بگذارید.