الطلبات - من الاستلام إلى التسليم

نقاط النهاية والصلاحيات

الطلب	الصلاحية
`GET /orders`	`orders:read`
`GET /orders/{order_id}`	`orders:read`
`POST /orders/{order_id}/accept`	`orders:write`
`POST /orders/{order_id}/reject`	`orders:write`
`POST /orders/{order_id}/status`	`orders:write`
`POST /orders/{order_id}/cancel`	`orders:write`
رقم العميل كاملا في الطلبات والأحداث	`customer:contact`

من يفعل ماذا

الطرف	دوره
العميل	يطلب ويدفع من تطبيق AurMap
AurMap	يقبض المبلغ أو يسجل الدفع النقدي، ويسترجع عند الإلغاء، ويحول للتاجر
نظامك	يقبل الطلب، ويجهزه، ويحدث حالته حتى التسليم

نظامك لا يقبض من العميل ولا يسترجع له شيئا في طلبات AurMap.

عند الإطلاق كل الطلبات استلام من الفرع (pickup). التوصيل قريبا.

الحالات

received ──accept──▶ accepted ──▶ preparing ──▶ ready ──▶ completed
   │                     │             │            │
   │ reject              └─────────────┴────────────┴── cancel ─▶ cancelled (merchant)
   ▼
rejected

received ── customer cancels ──▶ cancelled (customer)
received ── accept_by passes ──▶ cancelled (timeout)
ready ── customer_no_show ──▶ cancelled (merchant)

الحالة	من يضعها	المعنى
`received`	AurMap	طلب جديد ينتظر قرارك
`accepted`	أنت	قبلت الطلب
`preparing`	أنت	قيد التجهيز
`ready`	أنت	جاهز للاستلام
`out_for_delivery`	أنت	خرج للتوصيل قريبا
`completed`	أنت	سلم للعميل
`rejected`	أنت	رفضت الطلب قبل قبوله
`cancelled`	حسب السبب	ألغي. السبب في `cancel.reason`

يمكنك القفز للأمام: من accepted إلى ready أو completed مباشرة.
لا يمكنك الرجوع للخلف. ذلك يرد 409 INVALID_TRANSITION.

قواعد الإلغاء والاسترجاع

قبل القبول يستطيع العميل الإلغاء. يسترجع مبلغه كاملا تلقائيا، ويصلك order.cancelled بسبب customer.
بعد القبول لا يلغي إلا التاجر، من نظامك. AurMap يسترجع للعميل المبلغ كاملا، مرة واحدة، إلا في «عدم حضور العميل» أدناه.
مهلة القبول: تحددها أنت بين 2 و15 دقيقة، والافتراضي 5. تغيرها من إيقاف الطلبات. إذا لم تقبل أو ترفض قبل accept_by يلغى الطلب بسبب timeout ويسترجع العميل مبلغه.
دعم AurMap قد يلغي طلبا مفتوحا بسبب aurmap_refund.
العميل لم يحضر: يقرر التاجر خلال 24 ساعة من وصول الطلب إلى ready. الافتراضي استرجاع كامل، والاسترجاع الجزئي عبر merchant_refund.
تعديل الأصناف بعد القبول، والاسترجاع الجزئي في غير عدم الحضور، غير متاحين الآن.

القبول والإلغاء من العميل وانتهاء المهلة قد تحدث في اللحظة نفسها. نطبق أول ما يصل فقط. الآخر يرد 409 ORDER_CLOSED مع الحالة النهائية، أو 409 ALREADY_ACCEPTED.

كيف يصلك الطلب

يصلك حدث order.created على عنوان webhook لحظة إنشاء الطلب. انظر الأحداث.
تحقق من التوقيع، ورد بـ 200 خلال 10 ثوان. الرد استلام، وليس قبولا.
اعرض الطلب في المطبخ، ثم اقبله أو ارفضه قبل accept_by.

إذا تعطل خادمك، المهلة لا تتوقف. عند العودة اسأل عن الطلبات المنتظرة:

bash

aurmap GET '/v1/orders?status=received&place_id=plc_9q3w7e'

كائن الطلب

json

{
  "order_id": "ord_7m1x9c",
  "number": "M-1043",
  "mode": "live",
  "link_id": "lnk_2h6j4n",
  "place_id": "plc_9q3w7e",
  "external_location_id": "pos-branch-17",
  "type": "pickup",
  "status": "received",
  "version": 1,
  "placed_at": "2026-10-14T12:30:05Z",
  "accept_by": "2026-10-14T12:35:05Z",
  "menu_version": 15,
  "priced_by": "aurmap",
  "quote_id": null,
  "customer": { "name": "سارة", "phone_masked": "+9665••••••01", "phone_e164": null, "marketing_opt_in": false },
  "items": [
    {
      "line_id": "1",
      "item_id": "chicken-burger",
      "size_id": "l",
      "name": { "ar": "برجر دجاج", "en": "Chicken burger" },
      "qty": 1,
      "unit_price_minor": 2990,
      "options": [
        { "group_id": "sauce", "option_id": "hot", "qty": 1, "price_minor": 230 },
        { "group_id": "extras", "option_id": "cheese", "qty": 1, "price_minor": 345 }
      ],
      "notes": "بدون مخلل",
      "line_total_minor": 3565
    },
    {
      "line_id": "2", "item_id": "orange-juice", "size_id": "s",
      "name": { "ar": "عصير برتقال", "en": "Orange juice" },
      "qty": 2, "unit_price_minor": 920, "options": [], "notes": null, "line_total_minor": 1840
    }
  ],
  "totals": { "currency": "SAR", "subtotal_minor": 5405, "discount_minor": 0, "service_charge_minor": 0, "tax_minor": 705, "total_minor": 5405, "prices_include_tax": true },
  "payment": { "method": "card", "status": "paid", "amount_minor": 5405 },
  "notes": null,
  "cancel": null
}

الحقل	الوصف
`number`	رقم قصير يقوله العميل عند الاستلام
`accept_by`	آخر وقت للقبول أو الرفض
`version`	يزيد مع كل تغيير. تجاهل أي حدث نسخته أقدم مما عندك
`menu_version`	نسخة القائمة التي سعر منها الطلب
`priced_by`	`aurmap` إذا سعر من قائمتك المنشورة، أو `partner` إذا سعره نظامك
`item_id`، `size_id`، `group_id`، `option_id`	معرفاتك أنت من القائمة
`customer.phone_masked`	رقم العميل مخفيا: رمز الدولة وأول رقم، ثم نقطة لكل رقم مخفي، ثم آخر رقمين
`customer.phone_e164`	الرقم كاملا، فقط إذا كان الربط يحمل `customer:contact`. وإلا `null`
`customer.marketing_opt_in`	هل وافق العميل على رسائل التسويق من هذا التاجر
`payment.method`	`card` مدفوع مسبقا، أو `cash` يدفع عند الاستلام
`payment.status`	`paid` أو `unpaid` أو `refunded` أو `partially_refunded`
`payment.refunded_minor`	المبلغ المسترجع للعميل، بعد الاسترجاع فقط

الرقم الكامل للطلب ولنقاط الولاء عند التاجر فقط. لا تستعمله في التسويق إلا إذا كان marketing_opt_in يساوي true. القاعدة نفسها في الأحداث وسجل الأحداث وطلب التسعير.

الطلب النقدي يصل بـ "method": "cash" و"status": "unpaid". يحصل الفرع المبلغ عند التسليم، ثم تضع الحالة completed.

قبول الطلب

POST /orders/{order_id}/accept بصلاحية orders:write.

bash

aurmap POST /v1/orders/ord_7m1x9c/accept '{"prep_minutes":15,"external_order_id":"POS-88231"}'

json

{ "order_id": "ord_7m1x9c", "status": "accepted", "version": 2, "ready_estimate": "2026-10-14T12:46:00Z", "external_order_id": "POS-88231" }

await aurmap('POST', `/v1/orders/${orderId}/accept`, { prep_minutes: 15, external_order_id: posId }, `accept-${orderId}`);

php

aurmap('POST', "/v1/orders/{$orderId}/accept", ['prep_minutes' => 15, 'external_order_id' => $posId], "accept-{$orderId}");

استعمل مفتاح تكرار ثابتا لكل أمر، مثل accept-<order_id>. إذا أعدت المحاولة لا يقبل الطلب مرتين.

رفض الطلب

POST /orders/{order_id}/reject، من received فقط.

bash

aurmap POST /v1/orders/ord_7m1x9c/reject '{"reason":"item_unavailable","note":"نفدت الكنافة"}'

json

{ "order_id": "ord_7m1x9c", "status": "rejected", "version": 2 }

الأسباب: busy وclosed وitem_unavailable وcannot_fulfil وother، ومع other الملاحظة مطلوبة. العميل يسترجع مبلغه كاملا.

تحديث الحالة

POST /orders/{order_id}/status

bash

aurmap POST /v1/orders/ord_7m1x9c/status '{"status":"ready"}'

json

{ "order_id": "ord_7m1x9c", "status": "ready", "version": 3 }

القيم: preparing وready وcompleted، وout_for_delivery مع التوصيل لاحقا.

إلغاء التاجر بعد القبول

POST /orders/{order_id}/cancel، من accepted أو preparing أو ready.

bash

aurmap POST /v1/orders/ord_7m1x9c/cancel '{"reason":"kitchen_issue","note":"عطل في الفرن"}'

json

{ "order_id": "ord_7m1x9c", "status": "cancelled", "version": 4, "cancel": { "reason": "merchant", "detail": "kitchen_issue", "by": "partner" }, "payment": { "method": "card", "status": "refunded", "amount_minor": 5405 } }

الأسباب: kitchen_issue وitem_unavailable وcustomer_no_show وother. السبب customer_no_show من ready فقط، وقواعده في القسم التالي. AurMap يسترجع للعميل فورا. لا تسترجع شيئا من جهتك. بعدها يصلك order.cancelled ثم order.payment_updated بحالة refunded.

عدم حضور العميل

الطلب جاهز والعميل لم يحضر. يقرر التاجر خلال 24 ساعة من وصول الطلب إلى ready، بالطلب نفسه: POST /orders/{order_id}/cancel بسبب customer_no_show.

بدون merchant_refund: AurMap يرجع للعميل المبلغ كاملا. هذا هو الافتراضي.
مع merchant_refund: يعلن التاجر المبلغ الذي يرجع للعميل وسببه. AurMap يرجع هذا المبلغ للعميل.

bash

aurmap POST /v1/orders/ord_7m1x9c/cancel '{"reason":"customer_no_show","merchant_refund":{"amount_minor":2700,"reason":"جهز الطلب ولم يحضر العميل"}}'

json

{ "order_id": "ord_7m1x9c", "status": "cancelled", "version": 5, "cancel": { "reason": "merchant", "detail": "customer_no_show", "by": "partner" }, "payment": { "method": "card", "status": "partially_refunded", "amount_minor": 5405, "refunded_minor": 2700 } }

الحقل	الوصف
`merchant_refund.amount_minor`	المبلغ الذي يرجع للعميل بالهللة. أكبر من صفر وأقل من المبلغ المدفوع
`merchant_refund.reason`	سبب المبلغ، نص قصير مطلوب

إذا لم يقرر التاجر خلال 24 ساعة، يغلق AurMap الطلب بسبب customer_no_show ويرجع للعميل المبلغ كاملا. لذلك ضع completed فور التسليم.
بعد 24 ساعة يرد الإلغاء 409 ORDER_CLOSED.
merchant_refund يقبل مع customer_no_show فقط، وفي طلب البطاقة فقط. غير ذلك يرد 400 VALIDATION_FAILED.
الطلب النقدي لم يدفع بعد، فلا استرجاع فيه. ألغه بسبب customer_no_show بدون merchant_refund.
بعدها يصلك order.cancelled ثم order.payment_updated بحالة refunded أو partially_refunded.

قراءة الطلبات

الطلب	الوصف
`GET /orders/{order_id}`	طلب واحد
`GET /orders?place_id=&status=&updated_after=&cursor=`	قائمة. `status=open` يجمع كل الطلبات المفتوحة
`GET /orders?ids=ord_a,ord_b`	حتى 100 طلب للمطابقة

التسعير من نظامك قريبا

بعض الأنظمة تسعر قوائمها بنفسها: رسوم خدمة، أسعار ولاء، عروض. لهذه الأنظمة ميزة اختيارية: عند الدفع نسأل نظامك عن السعر، والعميل يدفع ما ترده بالضبط.

سجل quote_url في لوحة المطورين، وفعل «التسعير من نظامي» للربط. يجب أن يكون عنوان https عاما، بقواعد عناوين الـ webhook نفسها في الأحداث.
عند الدفع نرسل إلى quote_url طلبا موقعا بسر الـ webhook. المهلة 3 ثوان.

json

{
  "request_id": "qr_01JA9X",
  "place_id": "plc_9q3w7e",
  "external_location_id": "pos-branch-17",
  "type": "pickup",
  "payment_method": "card",
  "menu_version": 15,
  "customer": { "phone_masked": "+9665••••••01", "phone_e164": null },
  "items": [
    { "line_id": "1", "item_id": "chicken-burger", "size_id": "l", "qty": 1, "options": [ { "group_id": "sauce", "option_id": "hot", "qty": 1 } ], "notes": null }
  ]
}

يرد نظامك 200:

json

{
  "quote_id": "pq_55120",
  "expires_at": "2026-10-14T12:45:00Z",
  "currency": "SAR",
  "lines": [ { "line_id": "1", "unit_price_minor": 2990, "options_minor": 230, "line_total_minor": 3220 } ],
  "subtotal_minor": 3220, "discount_minor": 0, "service_charge_minor": 0, "tax_minor": 420, "total_minor": 3220,
  "cash_allowed": true, "prep_min": 10, "prep_max": 20
}

أو 409 إذا تعذر الطلب:

json

{ "code": "SOLD_OUT", "errors": [ { "line_id": "1", "code": "SOLD_OUT" } ] }

الرمز	المعنى
`MENU_CLOSED`	القائمة مغلقة الآن
`PICKUP_OFF`	الاستلام غير متاح
`ITEM_UNAVAILABLE`	الصنف غير متاح
`SOLD_OUT`	نفد
`INVALID_OPTIONS`	اختيار الإضافات لا يوافق القواعد
`CASH_NOT_ACCEPTED`	الدفع النقدي غير متاح

expires_at بين 5 و15 دقيقة من الآن.
إذا لم يرد نظامك في الوقت، يرى العميل «تعذر التسعير الآن». لا نستعمل سعرا قديما أبدا.
الطلب يصلك بعدها بـ "priced_by": "partner" وquote_id. التزم بالسعر الذي رددته.