الاصطلاحات
الأجسام
- أجسام الطلبات والردود بصيغة 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 | الرد إعادة لطلب سابق بالمفتاح نفسه. |