توثيق المطورين
الأخطاء والاصطلاحات
تفسير استجابات REST وأخطاء Gateway.
تعامل مع فشل المصادقة والتصريح والتحقق من المدخلات والاتصال كلٌّ بحسب سببه. أمثلة الأخطاء توضيحية، وقد تختلف الرسائل المقروءة بشريًا.
استجابات REST
| الحالة | المعنى |
|---|---|
200 |
نجحت القراءة |
401 |
المصادقة مفقودة أو غير صحيحة |
403 |
لا تسمح قدرة الشركة أو الصلاحية أو قدرة الرمز بالعملية |
404 |
المورد غير موجود أو غير متاح ضمن نطاق الرؤية الحالي |
409 |
السجل غير متاح لغياب جهاز مرتبط أو إعداد التتبع المطلوب للجهاز |
422 |
معاملات سجل أو قيَم مرشحات connection أو movement أو ignition غير صحيحة |
500 |
خطأ غير متوقع في الخادم |
{ "message": "The given data was invalid.", "errors": { "from": ["The from field is required."] } }
تحتوي قراءات المجموعات على data وlinks وmeta. وتُغلّف قراءة المورد الواحد ضمن data. استخدم روابط الصفحات وبياناتها الوصفية الواردة بدل افتراض عدد ثابت للنتائج.
يستخدم تعارض متطلبات السجل بنية message المعتادة، ولا يُعاد كسجل فارغ. يُعاد 200 مع data: [] فقط إذا كان الجهاز مهيأ ولا توجد نقاط للفترة. تبقى أعطال المصدر أو الخادم بحالة 500. تسبق فحوص التصريح والرؤية فحص الجهاز، ولا تكشف الموارد غير المتاحة حالة أجهزتها.
تُرفض القيَم غير الصحيحة لمرشحات connection وmovement وignition، بما فيها المصفوفات، بحالة 422 ومفتاح الحقل في errors. تُتجاهل المرشحات الاختيارية المفقودة أو الفارغة. تتضمن قيَم الحركة المدعومة no_gps.
أخطاء Gateway
يرسل Gateway رمز الخطأ في data.error:
{ "type": "error", "timestamp": "2026-10-18T12:00:00+00:00", "data": { "error": "invalid_payload", "message": "Missing token." } }
تشمل الرموز الشائعة authentication_failed وunauthorized وforbidden وinvalid_json وinvalid_payload وunknown_message وinvalid_subscription وinternal_error. إذا فشلت دفعة اشتراك مركبات فلا يُسجّل أي اشتراك من تلك الدفعة. الخطأ لا يعني دائمًا انقطاع الاتصال؛ تعامل مع connection_closed أو إغلاق المقبس بصورة مستقلة.
حدود المعدل والحجم
لا تحدد مسارات REST الحالية حصة ثابتة لمعدل الطلبات. يطبّق Gateway حدودًا لأحجام الرسائل وعدد الاشتراكات ومعدل الرسائل، وقد تختلف إعدادات البيئة. أكّد حدود بيئتك بدل افتراض استخدام غير محدود أو اتفاقية مستوى خدمة معلنة.
الوقت والتوافق
حلّل طوابع ISO-8601 الزمنية مع إزاحاتها. تحتفظ طوابع الحالة في REST V1 بإزاحة منطقة التطبيق ودقة الثواني، بينما تحتفظ Gateway V1 بصيغة UTC وست خانات كسرية وZ. يحافظ النقلان على null ومفاهيم الحالة نفسها؛ راعِ الدقة المتاحة عند مقارنة الوقت. يمثل طابع غلاف Gateway وقت الإرسال لا وقت رصد GPS. تأتي حقول العنوان المشتركة من اللقطة المتاحة، ويحتفظ Gateway بثلاثة مراجع جغرافية إضافية (place_id وosm_type وosm_id) للتوافق. لا ينفذ التسلسل طلب ترميز جغرافي عكسي. قد تكون قيَم التتبع الاختيارية null أو غير متاحة. تجاهل الحقول وأنواع رسائل الخادم غير المعروفة ولا تعتمد على ترتيب خصائص JSON. موضوع Gateway المدعوم هو vehicle فقط.
إعادة الاتصال
بعد الانقطاع، أنشئ اتصالًا جديدًا وصادق وأعد إنشاء الاشتراكات المسموحة. تتوقف الحالة الأولية على توفرها. لا يوجد عقد معلن لإعادة إرسال الرسائل الفائتة أو ضمان التسليم أو زمن الوصول؛ صمّم آلية التعافي المناسبة لتكاملك.