مرجع واجهة API

العنوان الأساسي وصيغة الاستجابة

كل مسار يُقدَّم تحت البادئة /api. محليًا يكون العنوان الأساسي http://localhost:8000/api. وعلى الخادم يكون عنوان واجهة API الخاصة بك متبوعًا بـ /api، وهي القيمة نفسها التي تقرؤها الواجهتان الأماميتان من NEXT_PUBLIC_API_BASE_URL (متغيرات البيئة).

تخدم واجهة API جمهورين لا يتشاركان رمزًا أبدًا: العملاء، الذين يستخدمون مسارات الموقع، والفريق، الذي يستخدم مسارات لوحة التحكم. أجسام الطلبات بصيغة JSON، ما عدا رفع الملفات. كل إجابة تأتي في الغلاف نفسه:

{
  "success": true,
  "data": { },
  "message": ""
}

يحتوي data على النتيجة. وmessage جملة قصيرة تملؤها بعض عمليات الكتابة، بلغة الطلب، وتكون فارغة في غير ذلك. المال بالدولار العشري في JSON، مثل 14.99، وكل إجمالي تحسبه واجهة API: لا يُوثق بأي شيء يرسله العميل عن المال.

فحص السلامة لا يحتاج إلى رمز:

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

عندما يتعذر قراءة قاعدة البيانات يجيب أيضًا بـ 200، مع "status":"degraded" و"database":"down". يقرأ فحص السلامة في صورة Docker هذا الحقل.

الأخطاء

يحتفظ الفشل بالغلاف، مع success: false وحالة HTTP:

{
  "success": false,
  "data": null,
  "message": "errors.kitchen_closed",
  "errors": { "email": ["…"] },
  "code": "…"
}

• الأخطاء التي يراها العميل مفاتيح مثل errors.kitchen_closed أو errors.outside_area أو errors.rate_limited، يترجمها الموقع بنفسه. الرسائل الأخرى جمل بلغة الطلب.
• يظهر errors عند فشل التحقق، مع المشكلات لكل حقل.
• يحمل code سببًا قابلًا للقراءة آليًا عندما يوجد، مثل changes مع قائمة changes عندما يتغير سعر قبل إرسال الطلب.
• المسار المحمي من دون رمز يجيب بـ 401؛ والرمز من دون الصلاحية يجيب بـ 403.

القوائم والتقسيم إلى صفحات

تأخذ مسارات القوائم page وlimit (ويُقبل page_count بدلًا من limit). الحد الأقصى لـ limit هو 100. ما لم يحدد المستدعي الترتيب، تأتي الصفوف من الأحدث تحديثًا أولًا، مع المعرّف لفض التعادل، لذلك يكون التقسيم إلى صفحات ثابتًا.

{ "items": [ ], "total": 64, "page": 1, "limit": 12, "totalPages": 6 }

تضع قائمتا الأطباق والطلبات الصفوف تحت items. وتضعها قوائم الفئات والتقييمات والعملاء والفريق والأدوار والإعدادات تحت data، مع حقول التقسيم نفسها. القوائم التي تُقرأ بتسلسل، مثل أقسام الصفحة الرئيسية وقائمة انتظار المطابخ، تحافظ على ذلك التسلسل.

اللغة

أرسل Accept-Language: ar للرسائل العربية؛ وأي قيمة أخرى تجيب بالإنجليزية. تحمل سجلات القائمة اللغتين بالشكل { "en": "…", "ar": "…" } أيًا كانت قيمة الترويسة، ويختار العميل إحداهما.

تسجيل الدخول

1. 01

   سجّل الدخول كعضو في الفريق

   الطرفيةنسخ

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"owner@foodstudio.example","password":"FoodDemo2026!"}'

   data.access_token هو رمز الفريق، مع token_type بقيمة Bearer، وexpires_in (7d افتراضيًا، JWT_EXPIRATION) والعضو مع أدواره. ويعيد GET /api/auth/me العضو المسجّل مع صلاحياته.
2. 02

   استدعِ مسارًا محميًا

   الطرفيةنسخ

   curl http://localhost:8000/api/orders -H "Authorization: Bearer YOUR_TOKEN"
3. 03

   سجّل الدخول كعميل

   يجيب POST /api/auth/customer/login بالجسم نفسه بـ { token, user }؛ ويأخذ POST /api/auth/customer/register القيم first_name وlast_name وemail وpassword (8 أحرف أو أكثر) وphone اختياريًا، ويجيب بالشكل نفسه. العميل التجريبي هو sam@foodstudio.example مع FoodDemo2026!.

• يُرفض رمز العميل في كل مسار خاص بالفريق، ويُرفض رمز الفريق في كل مسار خاص بالعملاء.
• البريد غير المعروف وكلمة المرور الخاطئة يجيبان كلاهما بـ 401 مع الرسالة نفسها.
• عشر محاولات تسجيل دخول فاشلة من عنوان واحد خلال 15 دقيقة، لكل نموذج، تجيب بـ 429 حتى يمر 15 دقيقة على أقدم محاولة فاشلة (RATE_LIMIT_LOGIN). لا تُحتسب تسجيلات الدخول الناجحة.
• لا يوجد مسار لتسجيل الخروج: يسجّل العميل خروجه بنسيان رمزه.

الصلاحيات

تتحقق مسارات الفريق من صلاحية، اسمها بالشكل <module>.<action>. يحمل العضو كل صلاحيات كل أدواره.

القائمة

يحمل الطبق name وdescription وingredients باللغتين، وprice، وcategory الخاصة به، وimages، وoption_groups مع choices الخاصة بها وprice_delta لكل اختيار، وallergens، وdietary_tags، وpreparation_minutes، والمفاتيح is_active (منشور)، وis_available (يمكن طلبه الآن)، وis_featured وis_best_seller.

المطابخ وفحص الرمز البريدي

{ "postcode": "10001", "mode": "delivery", "kitchen_code": "central" }

يجيب بـ { result, kitchen, alternatives }، حيث result هي match أو outside_area أو closed. لا يتقيد الاستلام بالرمز البريدي. وتعتمد حالة فتح المطبخ على إعداد ساعة الخدمة.

التسعير، ورموز الخصم، والسلة

{
  "lines": [
    { "product_id": 9, "quantity": 1, "options": [{ "group": "size", "choice": "double" }], "instructions": "no onions" },
    { "offer_id": 1, "quantity": 1, "offer_choices": { "main": 9, "side": 5, "drink": 3 } }
  ],
  "kitchen_code": "central",
  "fulfillment": "delivery",
  "address": { "street": "12 Main St", "city": "Demo City", "postcode": "10001" },
  "promo_code": "TASTE10"
}

• يحدد السطر product_id أو offer_id، مع quantity من 1 إلى 10 وinstructions لا تتجاوز 200 حرف.
• يُبلغ التسعير عن المجموع الفرعي، والخصومات، والرسوم، والإجمالي، والنقاط التي سيكسبها الطلب، وما إذا كان التوصيل ممكنًا (address_incomplete، outside_area، closed، below_minimum)، وقائمة changes لأي سطر تغيّر سعره أو لا يمكن طلبه.
• يخصم رمز الخصم نسبته من المجموع الفرعي للقائمة، ولا يخصم أبدًا من رسوم التوصيل. يخصم redeem_points: true استبدالًا واحدًا لعميل مسجّل لديه نقاط كافية.

إرسال الطلب وتتبّعه

• يأخذ POST /api/orders القيم lines وkitchen_code وfulfillment وaddress من التسعير، إضافة إلى phone، وpayment_method (stripe أو paypal أو demo، كما يعرضها GET /api/payments/methods)، وterms_accepted: true، وللزائر name وemail. اختياري: promo_code، وredeem_points، وdelivery_instructions، وlocale، وaccept_changes، وreturn_url_ok وreturn_url_cancel، اللذان يجب أن يكونا على عنوان موجود في CORS_ORIGIN.
• يجيب بـ 201 مع { order, payment, tracking }. تكون payment.kind إما redirect، مع صفحة المزوّد في payment.url، أو none للدفع التجريبي، الذي يدفعه بعد ذلك POST /api/payments/checkout-session. وtracking رمز موقّع، صالح لثلاث ساعات، لـ GET /api/orders/track/status.
• القيمة نفسها لـ Idempotency-Key من الشخص نفسه تعيد الطلب المحفوظ بدلًا من إنشاء طلب ثانٍ.
• السعر الذي تغيّر، أو الطبق الذي أصبح غير متوفر، يجيب بـ 422 مع code: "changes" حتى يرسل العميل مفتاح التغيير في accept_changes.
• يجيب تتبّع الزائر بـ 404 نفسها للرقم غير المعروف والبريد الخاطئ والمعاملات الناقصة.

تنتقل حالة الطلب عبر pending وconfirmed وpreparing وready، ثم out_for_delivery وdelivered للتوصيل، أو مباشرة إلى delivered للاستلام. يمكن أن يصبح cancelled مع ذكر السبب قبل أن يغادر المطبخ، ولا يصبح refunded إلا عندما يُبلغ مزوّد الدفع عن استرداد.

المدفوعات

• اضبط المدفوعات

العناوين، والأطباق المحفوظة، والمكافآت، والتقييمات، والتواصل

الفريق: القائمة، والفئات، وعروض الكومبو، والصفحة الرئيسية

الفريق: الطلبات والنظرة العامة

• الانتقال الذي لا يسمح به تسلسل الحالات يجيب بـ 409 errors.transition_not_allowed؛ والانتقال الذي لا يحق لهذا الحساب إجراؤه بـ 403 errors.transition_forbidden؛ وتأكيد طلب غير مدفوع بـ 409 errors.payment_required.
• لا يرى حساب المطبخ إلا طلبات مطبخه، من دون أسعار، وأي طلب آخر يجيب بـ 404.

الفريق: العملاء، والفريق، والأدوار

الفريق: الإعدادات، والمطابخ، ورموز الخصم، والملفات المرفوعة، والإشعارات

• الإعدادات التي يعمل بها المطعم هي delivery_fee وpickup_fee وdelivery_minimum وrewards_points_per_dollar وrewards_redeem_points وrewards_redeem_value وservice_clock (real أو demo-fixed)، إلى جانب site_name وsite_tagline وsupport_email وsupport_phone.
• تُحفظ الصورة المرفوعة بصيغة JPEG بعدة أحجام، وتربط الإجابة كل نسخة بعنوانها. تذهب الملفات إلى المخزن عندما تكون متغيرات R2_* مضبوطة، وإلى /media/uploads/… على واجهة API في غير ذلك.
• كل مسار للإشعارات يجيب بالقائمة كاملة، لذلك يستبدل العميل ما لديه بالإجابة.

الحدود لكل عنوان

الطلب الذي يتجاوز حدًا يجيب بـ 429 مع errors.rate_limited. الأعداد محفوظة في ذاكرة واجهة API، لذلك تمسحها إعادة التشغيل. خلف خادم وكيل عكسي، اضبط TRUST_PROXY حتى يُحسب كل زائر على عنوانه الخاص.

المساعد الذكي ومحادثاته

استوديو الذكاء الاصطناعي

خادم MCP

التحديثات المباشرة عبر WebSocket

مسارات وضع العرض التجريبي