الطلبات

البادئة: /v1/orders على الواجهة العامة. المصادقة: عميل لكل مسار.

الطريقة	المسار	الغرض
POST	/v1/orders	إنشاء الطلب من السلة الحالية
GET	/v1/orders	قائمة طلبات العميل
GET	/v1/orders/:orderId	تفاصيل الطلب
POST	/v1/orders/:orderId/cancel	إلغاء

إنشاء الطلب

يلتقط الخادم لقطة من السلة واختيار التوصيل والأسعار. السلة الفارغة تفشل بـ CART_EMPTY.

أرسل JWT العميل. لا يستطيع الضيوف إنشاء طلب.

الجسم

الحقل	مطلوب	ملاحظات
paymentMethod	نعم	cod أو wallet فقط
notes	لا	حد أقصى 256 حرفاً
address	لا	تفاصيل عنوان الإتمام (تسمية، قطعة، شارع، …)
deliverySlot	توصيل مجدول	{ templateId, date } حيث date هو YYYY-MM-DD

مثال

POST /v1/orders
Content-Type: application/json
Authorization: Bearer <accessToken>

{
  "paymentMethod": "cod",
  "notes": "اتصل عند الوصول",
  "address": {
    "label": "المنزل",
    "block": "4",
    "street": "1",
    "building": "12",
    "phone": "50000000"
  },
  "deliverySlot": {
    "templateId": "665f0c0c0c0c0c0c0c0c0c0e",
    "date": "2026-09-13"
  }
}

results هو مستند الطلب الكامل (المعرّفات، الأسطر، الإجماليات بالفلس، الحالة placed).

يفشل دفع المحفظة إن لم يكفِ الرصيد. تُرفض الطرق الإلكترونية حتى لو أظهرت مفاتيح اللوحة خلاف ذلك.

القائمة والتفاصيل

GET /v1/orders مقسّم صفحات. GET /v1/orders/:orderId يرجع طلباً يملكه العميل.

الإلغاء

الجسم

الحقل	مطلوب	القيم
reason	نعم	changed_mind، ordered_by_mistake، too_slow، found_elsewhere، other
note	لا	حد أقصى 256

يُسمح بالإلغاء فقط بينما الطلب في حالة قابلة للإلغاء (عادة قبل اكتمال الالتقاط). قد يلغي الموظفون لاحقاً من اللوحة بمجموعة أسباب مختلفة.

قيم الحالة

الحالة	معنى العميل
placed	أُرسل
confirmed	قبله المتجر؛ بانتظار ملتقط
picking	قيد الالتقاط
ready	معبّأ / جاهز للسائق أو الاستلام
out_for_delivery	في الطريق
delivered	تم
delivery_failed	فشلت آخر محاولة
cancelled	ملغى

بعد confirmed تملك واجهة الملتقط وواجهة السائق بقية الانتقالات.