اعلام وضعیت سفارش در پاتریس
پاتریس یار هر بار که وضعیت یک سفارش در پاتریس تغییر کند، آن را به POST /patris-yar/orders/:id/ack میفرستد. سایت میتواند این وضعیت را در تاریخچهی سفارش ثبت کند یا به مشتری نشان دهد.
این endpoint کی صدا زده میشود؟
در هر دور همگامسازی، برای حداکثر ۵۰ سفارشی که وضعیتشان در پاتریس عوض شده و هنوز به سایت اعلام نشده است. اگر پاسخ موفق نباشد، پاتریس یار همان اعلام را در دور بعد تکرار میکند.
پیشنیازها
- مسیرها و احراز هویت
- سفارش قبلاً با
GET /patris-yar/ordersیا از طریق سرور پاتریس به پاتریس رسیده باشد.
Endpoint
POST /patris-yar/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 در نظر بگیرید.
نمونه درخواست و پیادهسازی
- curl
- C#
- Python
- PHP
- Node.js
- Go
اعلام وضعیت
curl -X POST https://shop.example.com/patris-yar/orders/1532/ack \
-H "X-Payava-Key: YOUR_API_KEY" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"patris_order_id":845,"status":"confirmed","state":"ارسال شد","archive":1}'
POST /orders/:id/ack
patris.MapPost("/orders/{id:long}/ack", async (long id, AckRequest body, IShopStore store) =>
{
var order = await store.GetOrderAsync(id);
if (order is null)
return Results.Json(new { code = "payava_patris_not_found", message = "Order not found" }, statusCode: 404);
await store.SavePatrisStatusAsync(id, body.PatrisOrderId, body.Status ?? "read", body.State?.Trim());
return Results.Json(new { ok = true });
});
public sealed class AckRequest
{
[System.Text.Json.Serialization.JsonPropertyName("patris_order_id")] public long PatrisOrderId { get; set; }
public string? Status { get; set; }
public string? State { get; set; }
public int Archive { get; set; }
}
POST /orders/:id/ack
class AckRequest(BaseModel):
patris_order_id: int = 0
status: str = "read"
state: str | None = None
archive: int = 0
@router.post("/orders/{order_id}/ack")
def ack(order_id: int, body: AckRequest):
if store.get_order(order_id) is None:
return JSONResponse({"code": "payava_patris_not_found", "message": "Order not found"}, status_code=404)
store.save_patris_status(order_id, body.patris_order_id, body.status, (body.state or "").strip())
return {"ok": True}
POST /orders/:id/ack
if ($method === 'POST' && preg_match('#^/orders/(\d+)/ack$#', $route, $m)) {
$id = (int) $m[1];
if ($store->order($id) === null) {
respond(404, ['code' => 'payava_patris_not_found', 'message' => 'Order not found']);
}
$body = json_body();
$store->savePatrisStatus($id, (int) ($body['patris_order_id'] ?? 0), (string) ($body['status'] ?? 'read'), trim((string) ($body['state'] ?? '')));
respond(200, ['ok' => true]);
}
POST /orders/:id/ack
router.post('/orders/:id/ack', async (req, res, next) => {
try {
const id = /^\d+$/.test(req.params.id) ? Number(req.params.id) : 0;
if (!id || !(await store.getOrder(id))) {
return res.status(404).json({ code: 'payava_patris_not_found', message: 'Order not found' });
}
const { patris_order_id = 0, status = 'read', state = '' } = req.body;
await store.savePatrisStatus(id, Number(patris_order_id), status, String(state || '').trim());
res.json({ ok: true });
} catch (err) {
next(err);
}
});
POST /orders/:id/ack
func ack(w http.ResponseWriter, r *http.Request) {
id, _ := strconv.ParseInt(r.PathValue("id"), 10, 64)
if _, found, err := store.Order(r.Context(), id); err != nil || !found {
writeJSON(w, http.StatusNotFound, map[string]string{"code": "payava_patris_not_found", "message": "Order not found"})
return
}
var body struct {
PatrisOrderID int64 `json:"patris_order_id"`
Status string `json:"status"`
State *string `json:"state"`
Archive int `json:"archive"`
}
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
writeJSON(w, http.StatusBadRequest, map[string]string{"code": "invalid_json", "message": err.Error()})
return
}
state := ""
if body.State != nil {
state = strings.TrimSpace(*body.State)
}
store.SavePatrisStatus(r.Context(), id, body.PatrisOrderID, body.Status, state)
writeJSON(w, http.StatusOK, map[string]bool{"ok": true})
}
// patris.HandleFunc("POST "+base+"/orders/{id}/ack", ack)
نمونه پاسخ موفق
200 OK
{ "ok": true }
کدهای خطا
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
401 | payava_patris_unauthorized | — | کلید نادرست است. |
404 | payava_patris_not_found | — | سفارش در سایت پیدا نشد. |
400 | invalid_json | — | بدنهی درخواست JSON معتبر نیست. |
نکتهها
پاسخ ناموفق تکرار میشود
پاتریس یار اعلام وضعیت را تا وقتی پاسخ موفق نگیرد، در هر دور تکرار میکند و خطا را در وضعیت اتصال نشان میدهد. سفارشهایی را که از سایت حذف میکنید، بهجای حذف کامل غیرفعال کنید تا این endpoint برای آنها 404 ندهد.
- یک وضعیت ممکن است دو بار برسد (مثلاً وقتی پاسخ قبلی گم شده). ذخیره را idempotent بنویسید.
statusبا مقدارeditedیعنی پاتریس سفارش را تغییر داده است. اقلام و مبلغ جدید در این درخواست ارسال نمیشوند؛ فقط وضعیت میرسد.