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

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

Gateway / V1

المصادقة

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

تحتاج تكاملات 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."
    }
}

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

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

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

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