مرجع الواجهة البرمجية

هذه الصفحة موجهة إلى مطوري الأنظمة التي ترتبط بالأسطول (الموارد البشرية، تخطيط الموارد، التقارير). وهي تلخّص واجهة REST البرمجية: طريقة المصادقة، وما يحتاجه كل طلب، وما يعيده. والمرجع الكامل بكل الحقول والمرشحات هو ملف OpenAPI 3.1: openapi.yaml.

العنوان الأساسي والمصادقة

يبدأ كل طلب بعنوان نظامك متبوعًا بـ /api/v1، مثل https://fleet.example.com/api/v1. ويظهر العنوان الدقيق في العنوان الأساسي بشاشة الإعدادات ← الربط مع الأنظمة.

أرسل المفتاح الذي أنشأته في تلك الشاشة مع كل طلب:

Authorization: Bearer <token>
Accept: application/json

لا تُقبل جلسة المتصفح لمستخدم مسجَّل الدخول. والطلب بلا مفتاح، أو بمفتاح خاطئ أو ملغى أو منتهٍ، يُرد عليه بـ 401. وتردّ الواجهة دائمًا بصيغة JSON، ورسائلها بالإنجليزية.

صلاحيات المفتاح وصلاحيات المستخدم ونطاق البيانات

يجب أن يجتاز كل طلب ثلاثة فحوص:

1. صلاحيات المفتاح. تسمح read بكل طلبات GET، وتسمح write:drivers بمزامنة السائقين (PUT drivers/by-iqama/{iqama} وPATCH drivers/{id}/status). وإن نقصت الصلاحية فالرد 403.
2. صلاحيات مستخدم المفتاح. يعمل المفتاح باسم مستخدمه، فيحتاج هذا المستخدم الصلاحية نفسها التي تحتاجها الشاشات (انظر الجدول أدناه)، وإلا فالرد 403، مثل The token user lacks the "Vehicles::viewAny" permission.
3. مشاريع مستخدم المفتاح ومدنه. المستخدم المحدود ببعض المشاريع أو المدن لا يرى إلا مركباتها وسجلاتها، والسائقين الذين يشرف عليهم أو الذين يحملون إحدى هذه المركبات، تمامًا كما في الشاشات. والسجل الخارج عن هذا النطاق يُرد عليه بـ 404.

وتتبع البيانات الشخصية قواعد الشاشات أيضًا: يكون iqama_number بقيمة null ما لم يملك مستخدم المفتاح صلاحية Drivers::view. ولا تُكشف الملفات المخزنة أبدًا، بل يذكر السجل فقط إن كان له ملف (has_file وhas_photo وphotos_count).

حد الطلبات

يحق لكل مفتاح 60 طلبًا في الدقيقة. وتحمل الردود الترويستين X-RateLimit-Limit وX-RateLimit-Remaining، وبعد تجاوز الحد يكون الرد 429 مع الترويسة Retry-After (بالثواني).

الطلبات

الطريقة	المسار	صلاحية المفتاح	صلاحية مستخدم المفتاح
GET	/vehicles	read	Vehicles::viewAny
GET	/vehicles/{id}	read	Vehicles::view
GET	/drivers	read	Drivers::viewAny
GET	/drivers/{id}	read	Drivers::view
GET	/contracts	read	Contracts::viewAny
GET	/contracts/{id}	read	Contracts::view
GET	/handovers	read	VehicleTransfers::viewAny
GET	/downtimes	read	VehicleDowntimes::viewAny
GET	/maintenances	read	VehicleMaintenances::viewAny
GET	/fuel-logs	read	VehicleFuelLogs::viewAny
GET	/accidents	read	Accidents::viewAny
GET	/violations	read	Violations::viewAny
GET	/invoices	read	Reports::MonthlyInvoices
GET	/projects	read	Projects::viewAny
GET	/cities	read	Cities::viewAny
GET	/companies	read	Companies::viewAny
PUT	/drivers/by-iqama/{iqama}	write:drivers	Drivers::create (سائق جديد) أو Drivers::edit (سائق موجود)
PATCH	/drivers/{id}/status	write:drivers	Drivers::edit

في محرر الأدوار، viewAny هي مربع القائمة في الصف، وview مربع عرض، وReports::MonthlyInvoices هي الفواتير الشهرية ضمن التقارير. ولا يعرض /invoices إلا الفواتير الشهرية الصادرة، بالأرقام المحفوظة وقت إصدارها.

معاملات القوائم

تقبل كل قائمة:

المعامل	المعنى
page	رقم الصفحة، من 1.
per_page	10 أو 25 أو 50 أو 100 (الافتراضي 25).
search	نص حر حتى 100 حرف، يُطابق مع الحقول الرئيسية للقائمة (مثل رقم اللوحة).
sort	id أو created_at أو updated_at أو أحد حقول القائمة (مثل license_plate وstart_date).
dir	asc أو desc.
updated_since	تاريخ أو تاريخ ووقت: السجلات التي تغيّرت في هذا الوقت أو بعده فقط، للمزامنة التدريجية.

إضافة إلى مرشحاتها الخاصة (المعرّفات مفصولة بفواصل، مثل project=3,4):

القائمة	المرشحات
/vehicles	project وcity وcompany وownership_type (own أو lease أو replacement)
/drivers	status (active أو inactive) وsupervisor وlicense_type
/contracts	vehicle وcompany وcontract_type (own أو lease) وstatus (active أو upcoming أو expired)
/handovers	vehicle وdriver وopen (1: بلا تاريخ نهاية بعد، 0: منتهية)
/downtimes	vehicle وcontract وstatus (inactive أو replacement)
/maintenances	vehicle وdriver وmaintenance_type
/fuel-logs و/accidents و/violations	vehicle وdriver
/invoices	month (YYYY-MM) وcontract وcompany

والمعامل الخاطئ (مثل per_page=20) يُرد عليه بـ 422.

صيغة الرد

ترد القائمة بـ {data, meta, links}، والسجل الواحد بـ {data}. وكل سجل بالشكل {id, type, attributes, relationships}: تعطي relationships معرّفات السجلات المرتبطة (مثل مشروع المركبة)، ويمكن قراءتها من /projects و/cities و/companies. والتواريخ بالصيغة YYYY-MM-DD، والأوقات بصيغة ISO 8601، والمبالغ أرقام JSON، والأسماء المترجمة بالشكل {"ar": …, "en": …}.

curl -H "Authorization: Bearer $FLEET_TOKEN" \
     -H "Accept: application/json" \
     "https://fleet.example.com/api/v1/vehicles?per_page=10&project=3"

{
  "data": [
    {
      "id": 12,
      "type": "vehicles",
      "attributes": {
        "license_plate": "ABC 1234",
        "brand": { "ar": "تويوتا", "en": "Toyota" },
        "vehicle_type": { "ar": "سيدان", "en": "Sedan" },
        "vehicle_sub_type": null,
        "fuel_type": { "ar": "بنزين 91", "en": "Petrol 91" },
        "model_year": 2024,
        "ownership_type": "lease",
        "vehicle_license_number": "123456789",
        "vehicle_license_expiry_date": "2027-03-31",
        "has_waei": true,
        "owned_cost_bearer": null,
        "created_at": "2026-01-15T09:30:00+03:00",
        "updated_at": "2026-10-02T14:05:11+03:00"
      },
      "relationships": {
        "project": { "id": 3, "type": "projects" },
        "city": { "id": 1, "type": "cities" },
        "company": { "id": 5, "type": "companies" }
      }
    }
  ],
  "meta": { "page": 1, "per_page": 10, "total": 1, "last_page": 1 },
  "links": {
    "first": "https://fleet.example.com/api/v1/vehicles?per_page=10&project=3&page=1",
    "prev": null,
    "next": null,
    "last": "https://fleet.example.com/api/v1/vehicles?per_page=10&project=3&page=1"
  }
}

مزامنة السائقين

PUT /drivers/by-iqama/{iqama}

ينشئ السائق صاحب رقم الإقامة هذا (201، ويحتاج Drivers::create) أو يحدّث السائق الموجود (200، ويحتاج Drivers::edit)، ويرد ببيانات السائق. وتكرار الطلب نفسه لا يغيّر شيئًا. والقواعد هي قواعد نموذج السائق: رقم الإقامة في المسار 10 أرقام يبدأ بـ 1 أو 2، ويجب ألا يتكرر رقم الرخصة ولا رقم الإقامة ولا البريد الإلكتروني. ولا يمكن تحديث سائق خارج مشاريع مستخدم المفتاح ومدنه، إذ يُعد رقم الإقامة مستخدمًا (422).

الحقل	القاعدة
name	إلزامي، حتى 255 حرفًا.
license_number	إلزامي، حتى 255 حرفًا، غير مكرر.
license_type_id	إلزامي، معرّف نوع رخصة.
license_issued_date	إلزامي، تاريخ.
license_expiry_date	إلزامي، تاريخ في يوم license_issued_date أو بعده.
phone_number	إلزامي، حتى 20 حرفًا.
email	اختياري، بريد صحيح غير مكرر.
supervisor_id	إلزامي، معرّف مستخدم.
status	اختياري، active أو inactive. السائق الجديد نشط، والموجود يحتفظ بحالته.
notes	اختياري، حتى 1000 حرف.

لا يمكن إرسال صورة السائق عبر الواجهة البرمجية.

PATCH /drivers/{id}/status

يفعّل السائق أو يوقفه. محتوى الطلب: {"status": "active"} أو {"status": "inactive"}. ويرد ببيانات السائق (200).

تُسجَّل التغييرات التي تتم عبر الواجهة البرمجية في سجل النشاط، باسم مستخدم المفتاح.

الأخطاء

كل خطأ بصيغة JSON وفيه message:

الرمز	متى	مثال
401	لا يوجد مفتاح، أو المفتاح خاطئ أو ملغى أو منتهٍ.	{"message": "Unauthenticated."}
403	ينقص المفتاحَ صلاحيةٌ، أو ينقص مستخدمَه صلاحيةٌ.	{"message": "The token user lacks the \"Drivers::view\" permission."}
404	لا يوجد السجل أو المسار، أو السجل خارج مشاريع المستخدم ومدنه.	{"message": "Not found."}
422	معاملات أو محتوى غير صحيح؛ وتسرد errors الرسائل لكل حقل.	{"message": "The selected per page is invalid.", "errors": {"per_page": ["The selected per page is invalid."]}}
429	أكثر من 60 طلبًا في الدقيقة بهذا المفتاح.	{"message": "Too Many Attempts."}