اصطلاحات واجهة البرمجة

واجهة البرمجة المركزية هي نقطة الدخول الوحيدة لتطبيق الهاتف. وهي تقدّم الكتالوج نفسه، من قاعدة البيانات نفسها، التي يعتمد عليها الموقع ولوحة الإدارة.

العقد والمرجع التفاعلي

العقد ملف OpenAPI 3.1 يُدار إصداره مع الكود (docs/api/openapi.yaml). يقارن اختبار آلي مساراته بمسارات التطبيق في الاتجاهين: مسار بلا عقد، أو عقد بلا مسار، يُفشل مجموعة الاختبارات. وسيُولَّد عميل TypeScript لتطبيق الهاتف من هذا العقد توليدًا آليًا، ولن يُكتب يدويًا أبدًا.

يقدّم التطبيق مرجعًا تفاعليًا (Scalar) على العنوان /docs/api، مع لوحة «جرّب» ومقتطفات كود بحسب لغة البرمجة.

الاصطلاحات

الموضوع	القاعدة
العنوان	/api/v1/… — الإصدار جزء من العنوان.
الصيغة	JSON، في الإدخال كما في الإخراج. أرسل Accept: application/json.
الأخطاء	{ "message": "…" }؛ وفي 422، { "message": "…", "errors": { "champ": ["…"] } }.
الرموز	200 قراءة، 201 إنشاء، 202 مقبول (إرسال الرمز)، 401 الدخول مطلوب، 403 رفض، 404 غير موجود أو غير منشور، 409 الوسيط غير متاح، 422 بيانات مرفوضة، 429 طلبات كثيرة جدًا.
المصادقة	Authorization: Bearer <jeton> — رمز وصول واحد لكل جهاز، يُحصل عليه بالدخول بالرمز.
اللغة	Accept-Language: ar أو fr للرسائل؛ الفرنسية افتراضيًا. المحتوى بالعربية أيًا كانت اللغة.
المعرّفات	تُعنون المنتجات والمجالات بمعرّف عنوانها (slug)، والمحتويات برقمها.
المبالغ	بالسنتيم، مع العملة وتسمية جاهزة للعرض.
التواريخ	ISO 8601 مع المنطقة الزمنية.

حدود التكرار

المسار	الحد
واجهة البرمجة كلها	120 طلبًا في الدقيقة، لكل حساب أو لكل عنوان.
طلب الرمز	5 في الدقيقة لكل عنوان؛ و3 كل 10 دقائق لكل معرّف.
التحقق من الرمز	10 في الدقيقة، لكل معرّف وعنوان.

عند بلوغ الحد يكون الرد 429 مع رسالة.

المسارات

الطريقة	المسار	الوصول	الصفحة
GET	/catalogue	عام	الكتالوج
GET	/catalogue/themes، /catalogue/themes/{slug}	عام	الكتالوج
GET	/catalogue/products/{slug}	عام	الكتالوج
GET	/contents/{id}/stream	مقتطف: عام · مقفل: رمز وصول وحق	التشغيل
POST	/auth/otp/request	عام، محدود	الحسابات
POST	/auth/otp/verify	عام، محدود	الحسابات
GET	/me	رمز وصول	الحسابات
POST	/auth/logout	رمز وصول	الحسابات