إنتقل إلى المحتوى الرئيسي

الاصطلاحات

الأجسام​

  • أجسام الطلبات والردود بصيغة JSON ‏(Content-Type: application/json) بمفاتيح camelCase.
  • المعرّفات UUID، مثل 3f6c1e2a-8b4d-4f1e-9c2a-6d5e7f8a9b0c.
  • الأوقات بصيغة RFC 3339 بتوقيت UTC ‏(2026-10-28T06:12:00Z)؛ والتواريخ بصيغة YYYY-MM-DD.
  • حجم جسم الطلب 8 MiB على الأكثر؛ وما يزيد يتلقى 413.
  • حمولات خطافات الويب استثناء: مفاتيح الغلاف فيها snake_case (راجع خطافات الويب).

المسارات​

الموارد أسماء تحت /v1/؛ والإجراء على أحدها فعل بعد نقطتين، دائمًا بـ POST:

GET /v1/drivers/{id}
POST /v1/drivers/{id}:suspend
POST /v1/alerts/{id}:acknowledge
POST /v1/dispatch/jobs/{id}/stops/{stopId}:complete

الإصدارات وIf-Match​

لكل مورد version يزيد مع كل تغيير. التعديل أو الإجراء الذي يجب ألا يطمس تغيير غيرك يأخذ الإصدار الذي قرأته في If-Match:

curl -X PATCH "https://api.zaitrack.app/v1/drivers/$ID" \
-H "Authorization: Bearer zk_test_…" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d '{"phone": "+966501234567"}'

إن تغيّر المورد منذ قراءته يُرفض الطلب (412، أو 409 لجداول التقارير) ولا يُكتب شيء: اقرأه مجددًا وأعد المحاولة. يذكر مرجع الواجهة البرمجية لكل عملية متى تقرأ If-Match.

ترويسات تستحق الاحتفاظ بها​

ترويسة الردمعناها
X-Zaitrack-Request-Idمعرّف الطلب. اذكره عند الإبلاغ عن مشكلة.
X-Zaitrack-Regionالمنطقة التي خدمت الطلب.
ETagإصدار ما أُعيد، حيث تضبطه العملية.
X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Resetرصيد مؤسستك لهذه العملية.
Idempotency-Replayed: trueالرد إعادة لطلب سابق بالمفتاح نفسه.