سُفرة التوثيق · سُفرة

خاص بـ: الحزمة الكاملة · واجهة API

مرجع الـ API

كل نقاط API في سُفرة، مع قواعد الوصول وأجسام الطلبات والردود.

كل النقاط تحت /api، تستقبل وترسل JSON، وموجودة في src/app/api. المبالغ أعداد صحيحة بأصغر وحدة للعملة (في الريال: البيسة). الأخطاء دائماً بهذا الشكل:

{ "error": { "code": "cart_invalid", "message": "Choose the required options for every dish." } }
الحالة متى
400 جسم الطلب ليس JSON
401 unauthorized: نقطة من اللوحة بلا جلسة صالحة
403 forbidden: موظف يستدعي نقطة للمالك فقط
404 not_found
409 تعارض: closed و not_accepting و bad_transition و slug_taken و last_owner...
422 validation ومشكلات الإدخال الأخرى
429 rate_limited
502 / 503 مزوّد الدفع أو الذكاء الاصطناعي غير متاح

نقاط اللوحة تستخدم الكوكي sufra_session الذي يضبطه POST /api/auth/login (httpOnly لمدة 12 ساعة).

النقاط العامة

GET /api/menu

القائمة وكل ما يحتاجه التطبيق لبناء طلب: بيانات المطعم (الاسم والعملة وخاناتها وهل هو مفتوح ويستقبل الطلبات)، والتسعير (taxPercent و deliveryFee و minOrder)، وطرق الاستلام والدفع المفعّلة، والأقسام بأطباقها وخياراتها. المثال الكامل في النسخة الإنجليزية من هذه الصفحة.

POST /api/orders

يرسل طلباً. الحد 8 طلبات في الدقيقة لكل زائر.

{
  "type": "DELIVERY",
  "customerName": "سالم الحارثي",
  "phone": "+968 9123 4567",
  "address": "القرم، سكة 2601، مبنى 12",
  "tableNo": "",
  "notes": "اضغط الجرس من فضلك",
  "paymentMethod": "CASH",
  "locale": "ar",
  "items": [
    { "itemId": "…", "quantity": 2, "optionIds": ["…", "…"], "note": "بدون مخلل" }
  ]
}
الحقل القواعد
type PICKUP أو DELIVERY (يتطلب address من 5 أحرف فأكثر) أو DINE_IN (يتطلب tableNo)، ويجب أن يكون مفعّلاً في الإعدادات
phone من 8 إلى 15 رقماً، مع + ومسافات وشرطات اختيارية
paymentMethod CASH أو CARD، ويجب أن تكون الطريقة مفعّلة
items من 1 إلى 60 سطراً، والكمية من 1 إلى 50، والخيارات يجب أن تخص الطبق، وتُجاب المجموعات المطلوبة، ولا تتجاوز maxSelect في أي مجموعة

الردود: 201 {"code": "SF-7KQ2-M9XD"} للنقد، و 201 {"code": "…", "payUrl": "https://…thawani.om/pay/…"} للبطاقة (أرسل الزبون إلى payUrl). الأخطاء: closed و not_accepting و type_disabled و payment_disabled و invalid_phone و address_required و table_required و cart_invalid و below_minimum و payment_unavailable.

يتجاهل الخادم أي سعر يرسله التطبيق: يحسب كل سطر من قاعدة البيانات (src/lib/pricing.ts)، ويضيف رسوم التوصيل للتوصيل، والضريبة على المجموع مع رسوم التوصيل.

GET /api/orders/{code}

تتبع الطلب للزبون (120 طلباً في الدقيقة لكل زائر). يعيد order فيه: الرمز والحالة وطريقة الاستلام واسم الزبون والهاتف مخفياً جزئياً (+••• •••• •567) والمجموع ورسوم التوصيل والضريبة والإجمالي وطريقة الدفع وحالته والأطباق بخياراتها وevents (كل حالة مع وقتها).

الحالات: NEW و PREPARING و READY و OUT_FOR_DELIVERY و COMPLETED و CANCELLED. الدفع: UNPAID و PAID و FAILED.

POST /api/reservations

{ "name": "سالم", "phone": "92223333", "people": 4, "date": "2026-10-20", "time": "20:00", "notes": "عيد ميلاد" }

الرد 201 {"code": "RS-…"}. عدد الأشخاص من 1 إلى 30، والتاريخ خلال الستين يوماً القادمة. الحد 5 في الدقيقة لكل زائر.

GET /api/payments/thawani/return?order={code}&locale={ar|en}

حيث يعيد ثواني الزبون. يتحقق من الجلسة لدى ثواني، ويعلّم الطلب مدفوعاً أو ملغى، ثم يحوّل إلى صفحة التتبع. انظر الدفع.

تسجيل الدخول

النقطة الجسم الرد
POST /api/auth/login {"email", "password"} 200 {"user": {"name", "email", "role"}} مع كوكي الجلسة، و 401 invalid_credentials عند الخطأ. 10 محاولات في الدقيقة لكل زائر و8 لكل بريد كل 15 دقيقة
POST /api/auth/logout بلا جسم 200 {"ok": true} ويُحذف الكوكي

نقاط اللوحة (تتطلب جلسة)

النقطة من الوصف
GET /api/dashboard/stats موظف أرقام اليوم، والطلبات الجارية، والحجوزات المعلّقة، وآخر 7 أيام، والأكثر مبيعاً
GET /api/dashboard/orders?view=active|today|all&q= موظف الطلبات بكل تفاصيلها، و q يبحث في الرمز والهاتف والاسم
GET /api/dashboard/orders/{id} موظف طلب واحد
PATCH /api/dashboard/orders/{id} موظف {"status": "READY", "note": "…"} ينقل الطلب في مساره (وإلا 409 bad_transition)، و {"paymentStatus": "PAID"} يسجّل استلام النقد (يُرفض لطلبات البطاقة)
GET /api/dashboard/categories موظف الأقسام مع عدد أطباقها
POST /api/dashboard/categories مالك {"slug", "nameAr", "nameEn", "sort", "active"}
PATCH /api/dashboard/categories/{id} مالك أي من الحقول السابقة
DELETE /api/dashboard/categories/{id} مالك فقط إن كان فارغاً (409 not_empty)
GET /api/dashboard/items?category={id} موظف كل الأطباق، ومنها أطباق الأقسام المخفية
POST /api/dashboard/items مالك طبق جديد (الحقول في النسخة الإنجليزية)
GET /api/dashboard/items/{id} موظف طبق واحد
PATCH /api/dashboard/items/{id} مالك، والموظف لـ {"available"} فقط أي حقول الطبق، و optionGroups يستبدل كل المجموعات
DELETE /api/dashboard/items/{id} مالك الطلبات السابقة تحتفظ بنسختها
POST /api/dashboard/upload مالك ملف file (JPEG/PNG/WebP حتى 4 ميجابايت) ← {"url": "/uploads/…"}
GET /api/dashboard/settings موظف الإعدادات مع integrations: {thawani, thawaniMode, ai}
PATCH /api/dashboard/settings مالك، والموظف لـ {"acceptingOrders"} فقط أي حقل من الإعدادات، و hours بصيغة [{"day": 0–6, "open": "HH:MM", "close": "HH:MM", "closed": false}]
GET /api/dashboard/reservations?view=upcoming|all موظف الحجوزات
PATCH /api/dashboard/reservations/{id} موظف {"status": "CONFIRMED"} (PENDING و CONFIRMED و DECLINED و SEATED و CANCELLED)
POST /api/dashboard/ai/describe مالك {"nameAr", "nameEn", "notes"} ← {"suggestion": {"ar", "en"}}، و 503 ai_disabled إن لم يكن مفعّلاً
GET /api/dashboard/staff مالك الحسابات
POST /api/dashboard/staff مالك {"name", "email", "password" (10+), "role": "OWNER"|"STAFF"}
PATCH /api/dashboard/staff/{id} مالك name و role و active و password، و 409 last_owner يحمي آخر مالك

أمثلة الردود الكاملة وحقول الطبق ومثال curl في النسخة الإنجليزية من هذه الصفحة.