تصميم الـ API

عائلتا مسارات تخدمان ثلاثة عملاء. لوحة تحكم الويب تستخدم صفحات مُصيَّرة من الخادم مع مصادقة الجلسة؛ وتطبيقات الجوال تستهلك نقاط JSON:API REST مع مصادقة JWT.

عائلتا المسارات

مسارات الويب — /admin/*

صفحات مُصيَّرة من الخادم للوحة تحكم المسؤول. مصادقة بالجلسة/الكوكيز. صلاحيات المسؤول ومدير الملعب فقط.

مسارات الـ API — /api/v1/*

نقاط JSON:API REST تُعيد JSON منظّم. مصادقة JWT. تُستخدم بواسطة تطبيقات Flutter للجوال (تطبيق مدير الملعب + تطبيق العميل).

اصطلاحات JSON:API

الميزة معامل الاستعلام مثال
ترقيم الصفحات ?page[number] & ?page[size] ?page[number]=1&page[size]=25 (الحد الأقصى 100)
التصفية ?filter[field]=value ?filter[status]=confirmed&filter[dateFrom]=2026-03-01
الترتيب ?sort=field (البادئة - للترتيب التنازلي) ?sort=-date,startTime
التضمين ?include=relation ?include=field,creator (تحميل العلاقات مسبقاً)
الحقول المحددة ?fields[type]=field1,field2 ?fields[bookings]=date,status,price

نقاط API الرئيسية للجوال

المصادقة

POST /api/v1/auth/otp/send طلب رمز OTP
POST /api/v1/auth/otp/verify التحقق من رمز OTP
POST /api/v1/auth/pin/create إنشاء PIN للمستخدم العائد
POST /api/v1/auth/pin/verify التحقق من تسجيل الدخول بـ PIN

الملاعب والجدول الزمني

GET /api/v1/fields عرض الملاعب (مدير الملعب: محدود بالملاعب المُعيّنة)
GET /api/v1/fields/:id تفاصيل الملعب
GET /api/v1/schedule/slots?field={id}&date={YYYY-MM-DD} الفترات المتاحة

الحجوزات

POST /api/v1/bookings/hold حجز مؤقت لفترة (5 دقائق)
POST /api/v1/bookings إنشاء حجز
GET /api/v1/bookings عرض الحجوزات
GET /api/v1/bookings/:id تفاصيل الحجز
PATCH /api/v1/bookings/:id تحديث الحجز
DELETE /api/v1/bookings/:id إلغاء الحجز

المدفوعات

POST /api/v1/payments تسجيل دفعة
GET /api/v1/payments سجل المدفوعات

العقود

GET /api/v1/contracts عرض العقود
GET /api/v1/contracts/:id تفاصيل العقد

أخرى

GET /api/v1/customer-contacts?phone=0512345678 البحث عن عميل
POST /webhooks/whatsapp/messages رسائل WAHA الواردة
POST /webhooks/whatsapp/status حالة تسليم WAHA

التحكم في الوصول حسب الأدوار

الدور النطاق الصلاحيات
admin جميع البيانات كل شيء — إنشاء/قراءة/تحديث/حذف جميع الكيانات، إدارة المستخدمين، عرض التحليلات
executive جميع البيانات (قراءة فقط) عرض لوحات المعلومات والتقارير والتحليلات. بدون إنشاء/تعديل
field_manager الملاعب المُعيّنة فقط إنشاء/إدارة الحجوزات، تسجيل المدفوعات، عرض الجدول الزمني لملاعبهم
customer بياناته الخاصة فقط تصفح الملاعب، إنشاء حجوزات، عرض سجل حجوزاته
نطاق مدير الملعب يُفرض عبر الـ middleware: مديرو الملاعب محدودون بملاعب معيّنة عبر الـ middleware. كل استعلام يجب أن يُصفّى حسب الملاعب المُعيّنة. هذا مُطبّق على مستوى الـ middleware وليس مخفياً في واجهة المستخدم فقط.

صيغة استجابة الأخطاء

جميع أخطاء الـ API تتبع صيغة أخطاء JSON:API. كل خطأ يتضمن code مقروء آلياً، وtitle وdetail مقروءين للبشر، واختيارياً مؤشر source يشير إلى الحقل المسبب للخطأ.

{
  "errors": [{
    "status": "422",
    "code": "BOOKING_CONFLICT",
    "title": "Slot Unavailable",
    "detail": "Field Al-Nakheel Court 1 is already booked on 2026-03-15 from 18:00 to 19:00",
    "source": { "pointer": "/data/attributes/startTime" }
  }]
}