اعلام دریافت سفارشها
پاتریس یار پس از ذخیرهی سفارشها، شناسهی آنها را به POST /patris-yar/orders/delivered میفرستد. سایت باید این سفارشها را «تحویلشده به پاتریس» علامت بزند تا در GET /patris-yar/orders دوباره نیایند.
این endpoint کی صدا زده میشود؟
- پس از هر صفحه از
GET /patris-yar/orders، با شناسهی همهی سفارشهای همان صفحه. - در روش «دریافت از طریق سرور پاتریس»، پس از دریافت سفارشهای این سایت از سرور. خطای این مرحله فقط در log پاتریس یار ثبت میشود.
پیشنیازها
- مسیرها و احراز هویت
- یک ستون یا جدول برای زمان تحویل سفارش به پاتریس.
Endpoint
POST /patris-yar/orders/delivered
هدرها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
X-Payava-Key | string | بله | کلید API حساب پاتریس. |
Content-Type | string | بله | application/json; charset=utf-8 |
پارامترها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
ids | string[] | بله | شناسهی سفارشها. پاتریس یار عددها را به صورت رشته میفرستد، مثل "1532". |
نمونه درخواست و پیادهسازی
- curl
- C#
- Python
- PHP
- Node.js
- Go
اعلام دریافت
curl -X POST https://shop.example.com/patris-yar/orders/delivered \
-H "X-Payava-Key: YOUR_API_KEY" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"ids":["1532","1533"]}'
POST /orders/delivered
patris.MapPost("/orders/delivered", async (DeliveredRequest body, IShopStore store) =>
{
var done = 0;
foreach (var raw in body.Ids ?? new List<string>())
{
if (long.TryParse(raw, out var id) && await store.MarkDeliveredAsync(id)) // false if missing or already delivered
done++;
}
return Results.Json(new { delivered = done });
});
public sealed record DeliveredRequest(List<string>? Ids);
POST /orders/delivered
from pydantic import BaseModel
class DeliveredRequest(BaseModel):
ids: list[str | int] = []
@router.post("/orders/delivered")
def delivered(body: DeliveredRequest):
done = 0
for raw in body.ids:
if str(raw).isdigit() and store.mark_delivered(int(raw)): # False if missing or already delivered
done += 1
return {"delivered": done}
POST /orders/delivered
if ($method === 'POST' && $route === '/orders/delivered') {
$done = 0;
foreach ((array) (json_body()['ids'] ?? []) as $raw) {
if (ctype_digit((string) $raw) && $store->markDelivered((int) $raw)) { // false if missing or already delivered
$done++;
}
}
respond(200, ['delivered' => $done]);
}
POST /orders/delivered
router.post('/orders/delivered', async (req, res, next) => {
try {
let done = 0;
for (const raw of req.body.ids || []) {
if (/^\d+$/.test(String(raw)) && (await store.markDelivered(Number(raw)))) done++; // false if missing or already delivered
}
res.json({ delivered: done });
} catch (err) {
next(err);
}
});
POST /orders/delivered
func delivered(w http.ResponseWriter, r *http.Request) {
var body struct {
IDs []json.Number `json:"ids"` // accepts "1532" and 1532
}
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
writeJSON(w, http.StatusBadRequest, map[string]string{"code": "invalid_json", "message": err.Error()})
return
}
done := 0
for _, raw := range body.IDs {
id, err := raw.Int64()
if err == nil && store.MarkDelivered(r.Context(), id) { // false if missing or already delivered
done++
}
}
writeJSON(w, http.StatusOK, map[string]int{"delivered": done})
}
// patris.HandleFunc("POST "+base+"/orders/delivered", delivered)
نمونه پاسخ موفق
200 OK
{ "delivered": 2 }
پاتریس یار مقدار delivered را نمیخواند. فقط موفق بودن پاسخ (کد 2xx) مهم است.
کدهای خطا
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
401 | payava_patris_unauthorized | — | کلید نادرست است. |
400 | invalid_json | — | بدنهی درخواست JSON معتبر نیست. |
نکتهها
idempotent باشد
یک سفارش ممکن است دوباره اعلام شود (مثلاً وقتی پاسخ قبلی به پاتریس یار نرسیده). سفارشی که قبلاً تحویل شده را بدون خطا رد کنید و زمان تحویل اول را تغییر ندهید.
- شناسهی ناشناخته را نادیده بگیرید و برای آن خطا ندهید.
- میتوانید هنگام علامتگذاری، یادداشت «سفارش برای پاتریس دریافت شد» را در تاریخچهی سفارش ثبت کنید.