كل النقاط تحت /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 في النسخة الإنجليزية من هذه الصفحة.