انتقل إلى المحتوى
TLGPSالتوثيق

توثيق المطورين

Gateway / V1

واجهة Gateway V1

اتصالات Gateway V1 واشتراكات المركبات والتحديثات المدعومة.

نظرة عامة

تتيح Gateway V1 اتصالات موثّقة واشتراكات في تحديثات تتبع المركبات المدعومة. لا يُفهم من ذلك ضمان للتسليم أو زمن الوصول.

بخلاف طلبات REST المنفصلة، يقيم العميل اتصال WebSocket مستمرًا، ويصادق، ثم يشترك في المركبات المسموح برؤيتها. يتلقى التحديثات المدعومة أثناء استمرار الاتصال والاشتراك دون طلب قراءة جديد لكل تحديث.

تعتمد إتاحة التتبع على المصدر والجهاز المهيأين. يتولى العميل الحفاظ على الاتصال وإدارة الاشتراكات والتعافي بعد الانقطاع. كل المُعرّفات والقيَم في الأمثلة بيانات توضيحية، والرموز بدائل غير صالحة للاستخدام.

عنوان Gateway

العنوان العام المهيأ:

wss://ws.tlgps.athear.ly

استخدم العنوان المخصص لبيئتك. استخدم WSS للتكاملات المنشورة؛ قد تستخدم بيئة التطوير WS.

أصل اتصال المتصفح

إذا أرسل العميل ترويسة Origin فيجب أن تطابق أصلًا يسمح به إعداد TLGPS. نسّق متطلبات أصل المتصفح مع جهة الاتصال المخوّلة. قد لا ترسل الأنظمة التي لا تعمل في المتصفح هذه الترويسة؛ غيابها لا يتجاوز المصادقة أو صلاحيات العملية والموارد.

إصدار البروتوكول

يشير هذا المرجع إلى V1. تعلن رسالة authenticated عن إصدار Gateway ومهلة الخمول. استخدم القيم الفعلية الواردة في الاتصال بدل افتراض إعداد ثابت.

المصادقة

تحتاج تكاملات Gateway إلى رمز وصول شخصي مناسب، وشركة نشطة يتوفر لها Gateway، وصلاحيات المستخدم المناسبة. تستخدم البوابة نفسها اعتماد متصفح قصير العمر ومنفصلًا. لا تضع رمز وصول شخصيًا في شيفرة متصفح عامة.

الحصول على الرمز

يمكن للمستخدم المخوّل إصدار رمز من صفحة رموز API في البوابة. إذا لم تتوفر هذه الصلاحية فتواصل مع مسؤول مخوّل. لا يوفر التوثيق مسارًا عامًا لإصدار الرموز.

يملك الرمز اسمًا وقدرات وتاريخ انتهاء إذا حُدد. احفظ السر في خادم موثوق. تحتاج اشتراكات التكامل إلى قدرة الرمز telemetry.subscribe والصلاحية الفعلية المقابلة والوصول إلى المركبة. لا تستبدل قدرات REST مثل vehicles.view أو vehicles.history هذه المتطلبات.

رسالة المصادقة

افتح الاتصال ثم أرسل:

{
    "type": "authenticate",
    "data": {
        "token": "<gateway-ticket-or-personal-access-token>"
    }
}

تنبيه

لا تستخدم رمزًا حقيقيًا في أمثلة مشتركة.

يتطلب الاتصال مصادقة مستقلة؛ انتظر رسالة نجاح قبل الاشتراك.

تأكيد المصادقة

{
    "type": "authenticated",
    "timestamp": "2026-07-01T10:19:12+02:00",
    "data": {
        "gateway": {
            "version": "v1",
            "heartbeat": {
                "idle_timeout": 120
            }
        }
    }
}

قيمة gateway.heartbeat.idle_timeout بالثواني. مثال 120 قيمة توضيحية لإعداد الاتصال؛ اعتمد القيمة التي يعيدها خادم بيئتك.

فشل المصادقة

{
    "type": "error",
    "timestamp": "2026-06-30T19:38:34+02:00",
    "data": {
        "error": "authentication_failed",
        "message": "Authentication failed."
    }
}

قد يغلق الخادم الاتصال بعد فشل المصادقة. لا تفترض بقاء المقبس متاحًا بعد رسالة خطأ.

انتهاء بيانات الاعتماد وتغيّر الوصول

لا تتيح الرموز المنتهية أو الملغاة إنشاء وصول جديد. تخضع الاتصالات القائمة لإعادة تحقق دورية من بيانات الاعتماد وإتاحة الشركة والصلاحيات ورؤية المركبات. قد تُزال اشتراكات أو يُغلق الاتصال عند تغير الوصول؛ لا يُضمن السحب الفوري.

اعتماد المتصفح الذي تستخدمه البوابة ليس واجهة عامة لإصدار رموز التكامل. نسّق أي تكامل متصفح مخصص مع TLGPS بدل تضمين رمز وصول شخصي فيه.

إغلاق الاتصال وإعادته

قد يرسل الخادم رسالة أخيرة مثل:

{
    "type": "connection_closed",
    "timestamp": "2026-06-30T19:38:34+02:00",
    "data": {
        "reason": "unauthorized",
        "message": "Connection authorization is no longer valid."
    }
}

عند الانقطاع تُزال اشتراكات الاتصال. أنشئ اتصالًا جديدًا وصادق مجددًا وأعد الاشتراكات المسموح بها. لا تفترض استعادتها تلقائيًا أو إعادة إرسال ما فات من رسائل.

صيغ الرسائل

تُرسل الرسائل بصيغة JSON. تستخدم رسائل الخادم الغلاف التالي:

{
    "type": "<message-type>",
    "timestamp": "2026-10-18T12:00:00+00:00",
    "data": {}
}

يحدد type نوع الرسالة، ويحمل timestamp وقت إرسالها بصيغة ISO-8601، وتحتوي data على بيانات النوع. لطلبات العميل صيغها الخاصة أدناه؛ لا يُطلب طابع زمني من العميل.

رسائل العميل

النوع الغرض
authenticate مصادقة الاتصال
subscribe طلب اشتراكات مركبات
unsubscribe إزالة اشتراكات
ping الحفاظ على نشاط الاتصال

رسائل الخادم

النوع المعنى
authenticated نجحت المصادقة
subscribed أُقرّ الاشتراك
unsubscribed أُقرّ إلغاء الاشتراك
telemetry حالة أو تحديث تتبع مركبة
pong رد فحص الاتصال
error خطأ في الطلب أو البروتوكول
connection_closed إغلاق الاتصال

تجاهل أنواع رسائل الخادم والحقول التي لا تعرفها. لا تفترض ترتيبًا مشتركًا بين اتصالات مختلفة أو عبر إعادة الاتصال، ولا تعتمد على ترتيب خصائص JSON.

فحص الاتصال

أرسل ping دوريًا خلال عمر الاتصال، ويجيب الخادم بـ pong. اختر فترة أقصر من مهلة الخمول التي أعلنها الاتصال. قد يغلق الخادم اتصالًا خاملًا أو غير مستجيب.

طلب فحص الاتصال

{
    "type": "ping",
    "data": {}
}

رد فحص الاتصال

{
    "type": "pong",
    "timestamp": "2026-06-30T19:38:34+02:00",
    "data": {}
}

لا تتطلب رسائل الفحص اشتراكًا ولا تحمل تتبعًا. استمر في إرسالها أثناء الاشتراكات. بعد الانقطاع صادق على اتصال جديد وأعد الاشتراكات؛ إرسال الفحص لا يعيد اتصالًا مغلقًا.

أسباب الإغلاق

تشمل الأسباب المعرفة في البروتوكول heartbeat_timeout وduplicate_authentication وserver_shutdown وmaintenance وunauthorized وprotocol_violation. تعامل مع الإغلاق نفسه، ولا تعتمد على وصول رسالة أخيرة في كل ظرف.

الاشتراكات

موضوع الاشتراك المدعوم في هذا الإصدار هو vehicle فقط. تُرفض المواضيع الأخرى. يتكون الاشتراك من topic وidentifier، حيث المُعرّف هو UUID المركبة نفسه المستخدم في REST.

طلب الاشتراك

أرسل مصفوفة غير فارغة باسم subscriptions في المستوى الأعلى للرسالة، بعد نجاح المصادقة:

{
    "type": "subscribe",
    "subscriptions": [
        {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        }
    ]
}

يمكن أن تحتوي الدفعة على عدة مركبات. تُدمج الأزواج المكررة من الموضوع والمُعرّف في اشتراك فعلي واحد. إذا كانت أي مركبة غير متاحة فلا يُسجّل أي اشتراك من تلك الدفعة، دون كشف ما إذا كانت المركبة غير موجودة أو غير مصرّح بها.

إقرار الاشتراك

يُعاد إقرار لكل اشتراك مقبول:

{
    "type": "subscribed",
    "timestamp": "2026-07-05T15:37:10+02:00",
    "data": {
        "subscription": {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        }
    }
}

ملاحظة

يمكن الاشتراك في مركبة غير متصلة.

وإذا لم تتوفر حالة محلولة للمركبة، يصل subscribed دون رسالة telemetry أولية. يظل الاشتراك فعالًا لاستقبال تحديثات لاحقة إذا توفرت.

إلغاء الاشتراك

{
    "type": "unsubscribe",
    "subscriptions": [
        {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        }
    ]
}

إقرار الإلغاء:

{
    "type": "unsubscribed",
    "timestamp": "2026-07-05T15:37:10+02:00",
    "data": {
        "subscription": {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        }
    }
}

إلغاء اشتراك غير مسجل لا يغيّر الاشتراكات الأخرى. ترتبط الاشتراكات بالاتصال الحالي وتنتهي بإغلاقه. لا يُعد إقرار الاشتراك ضمانًا لوصول حالة أولية أو تدفق بلا انقطاع.

تحديثات المركبة

تخص رسائل telemetry المركبة التي أُنشئ الاشتراك لها. يحمل كل تحديث معلومات الاشتراك وUUID المركبة وحالتها. يمكن أن تتعايش عدة اشتراكات على الاتصال نفسه.

الصلاحيات المطلوبة

يتطلب مسار التكامل برمز شخصي قدرة telemetry.subscribe والصلاحية الفعلية المقابلة، بالإضافة إلى صلاحية المركبة ورؤيتها ضمن الشركة. تستخدم البوابة مسار اعتماد متصفح مخصصًا يخضع لقدرات التتبع وصلاحياته؛ وليس تجاوزًا عامًا للتصريح.

الحالة الأولية والتحديثات اللاحقة

عند توفر حالة حالية، يمكن أن يلي إقرار الاشتراك تحديث أولي. وعند ورود تتبع مدعوم لاحقًا، تصل رسالة مثل:

{
    "type": "telemetry",
    "timestamp": "2026-06-30T19:53:37+02:00",
    "data": {
        "subscription": {
            "topic": "vehicle",
            "identifier": "01900000-0000-7000-8000-000000000001"
        },
        "vehicle": {
            "uuid": "01900000-0000-7000-8000-000000000001",
            "state": {
                "source": "realtime",
                "status": {
                    "connection": "online",
                    "movement": "parked"
                },
                "coordinates": {
                    "latitude": 0.0,
                    "longitude": 0.0
                },
                "geo_address": null,
                "speed": {
                    "kmh": 0,
                    "mps": 0
                },
                "gps_status": true,
                "angle": 61,
                "altitude": -1,
                "ignition": {
                    "status": "off"
                },
                "oil": 0,
                "voltage": 26.16,
                "mileage": {
                    "km": 27246189,
                    "meters": 27246189000
                },
                "temperature": "-255",
                "timestamps": {
                    "gps": "2026-06-30T17:52:51.000000Z",
                    "received": "2026-06-30T17:52:52.506493Z",
                    "last_synced": null
                }
            }
        }
    }
}

تستخدم vehicle.state تمثيل القيَم المشتركة نفسه المستخدم في location لدى REST عند تمثيل اللقطة المحلولة نفسها: أرقام الإحداثيات، ووحدات السرعة والمسافة وتقريبها، وقيَم الحالة والقيَم المنطقية وnull. لا يتضمن هذا التمثيل UUID الجهاز أو بيانات المصدر الخام أو بيانات الاعتماد.

تحتفظ طوابع الحالة timestamps.gps وreceived وlast_synced في Gateway V1 بصيغة UTC ISO-8601 وست خانات كسرية مع Z، أو null. يحتفظ REST V1 بصيغته الحالية وفق المنطقة الزمنية للتطبيق وإزاحتها وبدقة الثواني. يحافظ هذا الاختلاف على توافق V1؛ حلّل الوقت وقارن وفق الدقة المتاحة بدل مقارنة النصوص. أما timestamp في غلاف رسالة Gateway فيمثل وقت إرسال الرسالة بصيغة ISO-8601 وفق منطقة التطبيق وبدقة الثواني، لا وقت رصد GPS.

تستخدم geo_address العنوان المتاح في اللقطة أو null؛ لا ينفذ التسلسل طلب ترميز جغرافي عكسي. يتشارك النقلان display_name وcity وstate وcountry وcountry_code. ويحتفظ Gateway V1 أيضًا بمراجع الترميز الجغرافي الاختيارية place_id وosm_type وosm_id للتوافق مع العملاء الحاليين، بينما لا يعرضها REST. تستخدم الحالة الأولية والتحديثات اللاحقة تمثيل Gateway نفسه، وتبقى الحالة الأولية مشروطة بتوفر لقطة.

يظل الغلاف خاصًا بكل نقل، وقد تلاحظ القراءات والاشتراكات المنفصلة لقطات مختلفة. لا يعني ذلك تطابق الحمولات نصيًا أو ضمان التسليم أو زمن الوصول.

مفاهيم حقول الحالة

الحقل المعنى
source مصدر الحالة المحلولة
status حالة الاتصال والحركة
coordinates الإحداثيات إن توفرت
geo_address عنوان الموقع إن توفر
speed السرعة بوحداتها
gps_status صلاحية تحديد الموقع
angle وaltitude الاتجاه والارتفاع
ignition حالة التشغيل
oil وvoltage وtemperature قراءات مستشعرات اختيارية
mileage المسافة بوحداتها
timestamps أوقات الرصد والاستقبال والمزامنة حسب الإتاحة

تُرسل البيانات أثناء استمرار الاشتراك المصرّح به. تعامل مع تكرار التحديثات، والقيَم غير المتاحة، والانقطاع؛ لا يُعلن هذا المرجع ضمانًا للتسليم أو زمن الوصول أو إعادة إرسال الرسائل الفائتة.

الطوابع الزمنية

الحقل المعنى
timestamp وقت إرسال رسالة Gateway
vehicle.state.timestamps.gps وقت رصد الجهاز
vehicle.state.timestamps.received وقت استقبال التتبع
vehicle.state.timestamps.last_synced وقت المزامنة إن توفر

رسائل الخطأ

تحتوي رسالة error على رمز قابل للمعالجة في data.error ورسالة مقروءة في data.message:

{
    "type": "error",
    "timestamp": "2026-06-30T14:52:31+02:00",
    "data": {
        "error": "invalid_payload",
        "message": "Missing token."
    }
}

رموز الخطأ

الرمز المعنى
authentication_failed فشلت مصادقة بيانات الاعتماد
already_authenticated جرت محاولة مصادقة اتصال موثّق
unauthorized يجب إتمام المصادقة قبل العملية
forbidden لا تسمح الصلاحيات بالعملية
invalid_json الرسالة ليست JSON صحيحًا
invalid_payload حقول الرسالة مفقودة أو غير سليمة
unknown_message نوع طلب غير مدعوم
invalid_subscription اشتراك غير سليم أو مركبة غير متاحة
internal_error خطأ غير متوقع

قد لا يغلق الخطأ الاتصال؛ قد يتمكن العميل من تصحيح الطلب والمتابعة. تعامل أيضًا مع إغلاق المقبس بصورة مستقلة. قد تُطبّق حدود لأحجام الرسائل ومعدلاتها وعدد الاشتراكات بحسب إعداد البيئة. لا تفترض حدودًا غير معلنة.

التوافق والتعافي

تجاهل الحقول وأنواع رسائل الخادم غير المعروفة، وتعامل مع رموز الخطأ غير المعروفة كفشل عام. حافظ على الفصل بين نجاح المصادقة ونجاح الاشتراك وإتاحة الحالة. بعد الاتصال من جديد أعد المصادقة والاشتراكات؛ لا يوجد استرجاع تلقائي للاشتراكات أو عقد معلن لإعادة بث الرسائل الفائتة.

توثيق عام · يتطلب التكامل وصولًا مصرّحًا به

توثيق تديره فرق الهندسة. تستخدم الأمثلة بيانات توضيحية وقيَمًا بديلة لبيانات الاعتماد.

العودة إلى الأعلى