الكتالوج

كل المسارات أدناه عامة على http://localhost:5000. تتبع السلاسل المترجمة Accept-Language (ar / ar-* → العربية، وإلا الإنجليزية).

الإقلاع

الطريقة	المسار	الغرض
GET	/v1/init	لقطة الإطلاق
GET	/v1/home	أقسام الرئيسية (شرائح، أرفف، عروض)

استدعِ GET /v1/init عند إطلاق التطبيق. المصادقة اختيارية: أرسل Bearer عند التسجيل.

results في init

الحقل	المعنى
store.name، store.tagline	محلّيان مسبقاً
store.maintenanceMode، store.maintenanceMessage	عند التفعيل امنع كتابات السلة/الطلب/المفضلة
store.payment	مفاتيح الطرق (الإتمام ما يزال cod / wallet فقط)
store.loyalty، store.pro	أعلام البرنامج والمزايا
store.assistant.enabled، store.assistant.allowGuests	إظهار الدردشة / السماح للضيوف
store.supportContact، store.socialMedia	التذييل / التواصل
user	العميل العام، أو null
wishlistProductIds	لحالة القلب؛ فارغ للضيف
cart.offers	العروض المنطبقة على السلة حالياً
delivery	النمط الحالي (delivery | pickup)، branch، zone (الرسوم بالفلس)، اختياري addressId
content.popups	نوافذ تسويقية محلّاة

الأقسام والعلامات والمجموعات

الطريقة	المسار	الغرض
GET	/v1/categories	شجرة / قائمة الأقسام
GET	/v1/categories/:slug	تفاصيل القسم
GET	/v1/brands	قائمة العلامات
GET	/v1/brands/:slug	تفاصيل العلامة
GET	/v1/collections	قائمة المجموعات
GET	/v1/collections/:slug	تفاصيل المجموعة

قراءات الكتالوج تستخدم slug وليس المعرّف.

المنتجات

الطريقة	المسار	المصادقة	الغرض
GET	/v1/products	عامة	بحث / تصفية
GET	/v1/products/:slug	عامة	تفاصيل المنتج
GET	/v1/products/:slug/reviews	عامة	التقييمات ومتوسط التقييم

استعلام القائمة

الاستعلام	ملاحظات
page، limit	الصفحات (limit حد أقصى 100)
categorySlug، brandSlug، collectionSlug	النطاق
search	نص حر
tag	اختصار الوسم
inStock، onSale	منطقي
minPrice، maxPrice	فلس
sort	newest | price_asc | price_desc | name | discount_desc

results هو { data, pagination }. الأسعار على البطاقات بالفلس. قد يتغيّر التوفر بعد اختيار التوصيل / الاستلام.

الوصفات والعروض والصفحات والخطط

الطريقة	المسار	الغرض
GET	/v1/recipes	قائمة الوصفات
GET	/v1/recipes/:slug	تفاصيل الوصفة
GET	/v1/offers	العروض النشطة (حسب الفرع عند اختيار التوصيل)
GET	/v1/pages/:slug	صفحة محتوى / قانونية (about، faq، privacy، …)
GET	/v1/subscription-plans	خطط برو العامة + enabled + المزايا

التقييمات (كتابة)

الطريقة	المسار	المصادقة	الجسم
POST	/v1/reviews	عميل	productId، orderId، rating، اختياري title، body
PATCH	/v1/reviews/:reviewId	عميل	جزئي rating، title، body

يمكن للعملاء تقييم منتجات من طلباتهم فقط. rating من 1 إلى 5.