البدء

عناوين الأساس

البيئة	الواجهة العامة (العميل)	واجهة الإدارة (ملتقط / سائق)
محلي	http://localhost:5000	http://localhost:5001
بادئة الإصدار	/v1	/v1

مثال: قائمة المنتجات GET http://localhost:5000/v1/products.

الترويسات

الترويسة	مطلوبة	ملاحظات
Content-Type: application/json	مع أجسام JSON
Accept-Language	موصى بها	ar أو ar-* → العربية؛ غير ذلك → الإنجليزية
Authorization: Bearer <accessToken>	بعد الدخول	JWT وصول العميل أو الموظف
X-Cart-Token	تطبيق العميل، الضيوف	رمز معتم من results.cartToken
X-Assistant-Guest	تطبيق العميل، الضيوف	مفتاح ضيف hex بطول 32 تولّده وتحفظه

هوية العميل وسلة الضيف ومفتاح المساعد تُرسل في هذه الترويسات (أو في JSON للتحديث).

اللغة

يُفسَّر Accept-Language: يبدأ بـ ar → ar، وإلا en. نصوص الكتالوج في الواجهة العامة محلولة مسبقاً لتلك اللغة. وثائق الإدارة/النواة ما تزال تستخدم كائنات { en, ar }.

المال

كل حقول المال أعداد صحيحة بالفلس. 1.250 د.ك = 1250. اعرض ثلاث خانات عشرية في الواجهة.

الصفحات

نقاط القائمة التي تقبل الترقيم تستخدم:

الاستعلام	الافتراضي	الأقصى
page	1	—
limit	20	100
search	اختياري	120 حرفاً

بيانات التعريف:

{
  "total": 80,
  "page": 1,
  "limit": 20,
  "hasMore": true
}

التعامل مع الرموز

• بعد OTP أو دخول الموظف احفظ accessToken وrefreshToken (SecureStore). أرسل Authorization: Bearer <accessToken> مع كل طلب مصادق.
• عند 401 استدعِ POST /v1/auth/refresh مع { "refreshToken" }، خزّن الزوج الجديد، وأعد المحاولة مرة واحدة. إن فشل التحديث أرسل المستخدم للدخول.
• أثناء الضيف احفظ results.cartToken وأرسل X-Cart-Token مع السلة والتوصيل.
• اللغة هي Accept-Language لكل طلب. لا تضع السلة أو التوصيل داخل JWT.
• Swagger على /docs مولَّد من نفس مخططات TypeBox للمسارات. العمليات مجمّعة حسب الوحدة. استخدم Authorize لإرسال JWT Bearer.

وضع الصيانة

عند تفعيل صيانة المتجر تفشل عمليات /v1/cart وإنشاء/إلغاء الطلبات وكتابة المفضلة بخطأ تحقق. القراءات تبقى تعمل.