مرجع الواجهة البرمجية (API)
كل العملاء — المواقع الأربعة وتطبيقات Flutter الثلاثة — يتواصلون مع واجهة REST واحدة بإصدار /api/v1. العقد وثيقة OpenAPI 3.1 تُولَّد من وحدات التحكم نفسها.
تفاعلي
واجهة Swagger
https://api.helsen-med.com/docs — تصفّح كل عملية وجرّبها. متاحة عندما يفعّلها النشر (SWAGGER_ENABLED، مفعّل افتراضيًا).
في المستودع
docs/api/openapi.json
العقد المحفوظ في المستودع. يفشل التكامل المستمر إذا اختلف عن توليد جديد، فلا يكون قديمًا أبدًا على الفرع الرئيسي.
في المستودع
docs/endpoints.md
جدول مولَّد لكل نقطة نهاية، ومن يحق له استدعاؤها، وحد الطلبات عليها.
كيف يبقى العقد صادقًا
- تُولَّد وثيقة OpenAPI بالأمر
pnpm --filter @mp/api gen:openapi، وتُولَّد حزم SDK وجدول النقاط بالأمرpnpm gen:sdk. - تحمل كل عملية امتدادين يُقرآن من المزخرفات نفسها التي تطبّقها الحراسات:
x-access(عام، أو أي مستخدم مسجّل، أو قائمة أدوار) وx-rate-limit. - عميل TypeScript
@mp/sdkمولَّد من الوثيقة وتستخدمه كل واجهات الويب. أما عميل Dart (packages_dart/mp_api) فمكتوب يدويًا عن قصد؛ يُولَّد منه فقط كتالوج الأخطاء وقائمة العمليات، ويتحقق اختبار انحراف من وجود كل مسار يستدعيه.
أعراف تتبعها كل نقطة نهاية
| الموضوع | القاعدة |
|---|---|
| المسار الأساسي | /api/v1؛ وفحص الصحة على /health (الحياة) و/ready (الجاهزية، يفحص قاعدة البيانات). |
| المصادقة | رمز وصول JWT من نوع Bearer (15 دقيقة) مع رمز تحديث متجدد. |
| المبالغ | أعداد صحيحة بأصغر وحدة للعملة مع رمز ISO للعملة. في الشبكة يُرسل المبلغ كنص وليس رقمًا في JSON. |
| المعرّفات | UUID v7 (قابلة للترتيب زمنيًا). للطلبات والمنتجات أيضًا رمز قصير مقروء. |
| منع التكرار | كل عملية كتابة تمس المال أو الطلبات تتطلب ترويسة Idempotency-Key؛ إعادة المحاولة تُعيد الاستجابة المخزنة بدل التنفيذ مرتين. |
| التقسيم إلى صفحات | بالمؤشر (cursor) في كل قوائم النتائج، وليس بالإزاحة. |
| الأخطاء | كل خطأ يحمل رمزًا ثابتًا من الكتالوج في packages/contracts/src/errors.ts، مثل order.ILLEGAL_TRANSITION. |
| عزل البائعين | لا يرى البائع إلا بياناته. قراءة مورد يخص بائعًا آخر تُرجع common.NOT_FOUND — وليس 403 الذي يؤكد وجود المعرّف. |
| حد الطلبات | حد عام لكل عنوان IP (120 طلبًا في الدقيقة ما لم يُضبط غير ذلك)، مع حدود أشد على المسارات الحساسة كتسجيل الدخول ورموز التحقق. |
| الأوقات | بتوقيت UTC وبصيغة ISO 8601. |
مجموعات نقاط النهاية
يسرد الجدول المولَّد نحو 400 عملية، وتنقسم حسب الجمهور:
- عام ومشترٍ: auth وcatalog وsearch وcart وcheckout وorders وreturns وreviews وquestions وaddresses وnotifications وconversations وprivacy.
- البائع: seller-onboarding وseller-orders وseller-shipments وseller-returns وseller-earnings وseller-invoices وseller-staff وseller-performance وinventory وmedia.
- التوصيل: dispatch وdriver وdriver-onboarding وdelivery-zones.
- الموظفون: مجموعات
admin-*(الكتالوج، الطلبات، النزاعات، الاسترجاعات البنكية، خطط العمولة، قبول البائعين والسائقين، المستخدمون، سجل التدقيق، مفاتيح الميزات، المحتوى، الدعم) والمالية.