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

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

REST API / V1

واجهة REST API V1

موارد REST API V1 والمصادقة وقراءات ضمن حدود الوصول.

نظرة عامة

تتيح REST API V1 قراءة الشركات والمركبات الظاهرة وسياق المركبة الحالي والسجل المتاح ضمن نطاق مصرّح به. تستخدم الموارد مُعرّفات UUID، وتتطلب قراءتها رمز وصول شخصيًا وصلاحيات مناسبة وإتاحة REST API للشركة النشطة التي ينتمي إليها صاحب الرمز.

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

العنوان الأساسي

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

https://api.tlgps.athear.ly/v1

استخدم العنوان المخصص لبيئتك. استخدم HTTPS في التكاملات المنشورة؛ قد تستخدم بيئة التطوير المحلية HTTP. حماية النقل مسؤولية إعداد البيئة وليست ضمانًا تفرضه هذه المسارات.

الإصدار

يشير هذا المرجع إلى V1. يتضمن مسار الطلب الإصدار /v1، وتبقى أمثلته مرتبطة بهذا الإصدار حتى لو أُضيف إصدار افتراضي أحدث لاحقًا.

اصطلاحات الواجهة

المُعرّفات

استخدم UUID الصادر من استجابة مصرّح بها بدل المُعرّفات الرقمية لقاعدة البيانات. مثال توضيحي:

01900000-0000-7000-8000-000000000001

الوقت والقيَم غير المتاحة

تُنسّق الطوابع الزمنية لاستجابات REST وفق المنطقة الزمنية المهيأة للخادم بصيغة ISO-8601. حلّل الإزاحة الزمنية ولا تقارن النصوص الزمنية دون تحويل مناسب. قد تكون قيَم التتبع الاختيارية null، ولا تدعم جميع الأجهزة كل الحقول.

حدود معدل الطلبات

ملاحظة

لا تحدد مسارات V1 الحالية حدًا ثابتًا على مستوى التطبيق لمعدل طلبات REST.

قد تختلف حدود النشر. أكّد الحدود مع جهة الاتصال في TLGPS، ولا تفترض استخدامًا غير محدود.

المصادقة

كل مسارات موارد الأسطول محمية باستخدام Bearer Token. مسار فحص الحيوية GET /v1/health عام ولا يحتاج إلى رمز.

GET https://api.tlgps.athear.ly/v1/vehicles
Authorization: Bearer <token>
Accept: application/json

تؤدي بيانات الاعتماد المفقودة أو غير الصحيحة إلى 401 Unauthorized. قد تمنع إتاحة الشركة أو الخدمة أو الصلاحيات أو قدرة الرمز العملية باستخدام 403 Forbidden.

التصريح ونطاق الوصول

تُقيّم بيانات الاعتماد وإتاحة الشركة وصلاحيات صاحب الرمز ونطاق الموارد بصورة مستقلة. قدرة الرمز لا تمنح صلاحية تطبيق، وصلاحية المستخدم لا توسّع رمزًا محدود القدرات.

قدرات الرمز

العملية القدرة المطلوبة
GET /v1/companies companies.view-any
GET /v1/companies/{company} companies.view
GET /v1/vehicles vehicles.view-any
GET /v1/vehicles/{vehicle} vehicles.view
GET /v1/vehicles/{vehicle}/history vehicles.history

تخص telemetry.subscribe واجهة Gateway ولا تصرّح بقراءة موارد REST. يحتاج صاحب الرمز أيضًا إلى الصلاحية الفعلية المقابلة ضمن قدرات شركته المتاحة.

رؤية الموارد

مهم

لا يتيح الرمز الصحيح الوصول إلى جميع الموارد.

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

المسارات المدعومة

الطريقة المسار الغرض
GET /v1/health فحص حيوية API العام
GET /v1/companies قائمة الشركات الظاهرة
GET /v1/companies/{company} تفاصيل شركة ظاهرة
GET /v1/vehicles قائمة المركبات الظاهرة
GET /v1/vehicles/{vehicle} تفاصيل مركبة ظاهرة وسياقها الحالي
GET /v1/vehicles/{vehicle}/history سجل المركبة المتاح

صيغ الاستجابة والصفحات

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

{
    "data": [],
    "links": {},
    "meta": {}
}

حالات HTTP

الحالة المعنى
200 نجحت القراءة
400 طلب غير سليم
401 بيانات الاعتماد مفقودة أو غير صحيحة
403 العملية غير مسموحة ضمن حدود الوصول
404 المورد غير موجود أو غير متاح ضمن الرؤية الحالية
422 فشل التحقق من المدخلات
500 خطأ غير متوقع

قد تتضمن أخطاء التحقق message وerrors. لا تفترض تطابق النص المقروء بشريًا في كل حالة.

فحص الحيوية

GET https://api.tlgps.athear.ly/v1/health

الاستجابة:

{ "status": "ok" }

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

الشركات

تمثل الشركة جهة تملك أو تدير أسطولًا. لا تُعاد إلا الشركات الظاهرة للمستخدم الموثّق.

حقول الشركة

الحقل النوع المعنى
uuid UUID مُعرّف الشركة
name string اسم الشركة
vehicles_count integer عدد المركبات المرتبطة بالشركة
{
    "uuid": "01900000-0000-7000-8000-000000000002",
    "name": "Northstar Fleet Operations",
    "vehicles_count": 82
}

قائمة الشركات

GET https://api.tlgps.athear.ly/v1/companies
Authorization: Bearer <token>
Accept: application/json

يتطلب الطلب companies.view-any والصلاحية المقابلة. تُعاد مجموعة مقسمة إلى صفحات، ولا يدعم هذا المسار حاليًا مرشحات بحث. استخدم links وmeta للتنقل.

{
    "data": [
        {
            "uuid": "01900000-0000-7000-8000-000000000002",
            "name": "Northstar Fleet Operations",
            "vehicles_count": 82
        },
        {
            "uuid": "01900000-0000-7000-8000-000000000003",
            "name": "Example Fleet Company",
            "vehicles_count": 154
        }
    ],
    "links": {
        "first": "https://api.tlgps.athear.ly/v1/companies?page=1",
        "last": "https://api.tlgps.athear.ly/v1/companies?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 15,
        "total": 2
    }
}

تفاصيل الشركة

GET https://api.tlgps.athear.ly/v1/companies/{company}
Authorization: Bearer <token>
Accept: application/json

استبدل بـ UUID لشركة ظاهرة. يتطلب الطلب companies.view والصلاحية المقابلة. حالات النتيجة الأساسية هي 200 و401 و403 و404.

{
    "data": {
        "uuid": "01900000-0000-7000-8000-000000000002",
        "name": "Northstar Fleet Operations",
        "vehicles_count": 82
    }
}

المركبات

تمثل المركبات الأصول المتتبعة. تجمع بيانات المركبة الثابتة مع آخر حالة تتبع محلولة عند توفرها. لا تُعاد إلا المركبات الظاهرة للمستخدم.

حقول المركبة

الحقل النوع المعنى
uuid UUID مُعرّف المركبة
plate_number string أو null رقم اللوحة
brand string أو null العلامة المصنعة
model string أو null الطراز
color string أو null اللون
chassis_number string أو null رقم الهيكل
engine_number string أو null رقم المحرك
company object الشركة المالكة
location object أو null سياق الموقع والحالة المحلول
{
    "uuid": "01900000-0000-7000-8000-000000000001",
    "plate_number": "NF-241",
    "brand": "Astra",
    "model": "M588FS",
    "color": "White",
    "chassis_number": null,
    "engine_number": null,
    "company": {
        "uuid": "01900000-0000-7000-8000-000000000002",
        "name": "Northstar Fleet Operations"
    },
    "location": {
        "source": "realtime",
        "status": {
            "connection": "online",
            "movement": "moving"
        },
        "coordinates": {
            "latitude": 0.0,
            "longitude": 0.0
        },
        "geo_address": null,
        "speed": {
            "kmh": 62,
            "mps": 17.22
        },
        "gps_status": true,
        "angle": 175,
        "altitude": 12,
        "ignition": {
            "status": "on"
        },
        "oil": 81,
        "voltage": 13.7,
        "mileage": {
            "km": 2485047,
            "meters": 2485047000
        },
        "temperature": "28",
        "timestamps": {
            "gps": "2026-06-29T23:47:43+02:00",
            "received": "2026-06-29T23:47:43+02:00",
            "last_synced": null
        }
    }
}

قائمة المركبات

GET https://api.tlgps.athear.ly/v1/vehicles
Authorization: Bearer <token>
Accept: application/json

يتطلب الطلب vehicles.view-any والصلاحية المقابلة. تُجمع المرشحات المتعددة باستخدام AND؛ فلا تُعاد إلا المركبات التي تطابقها كلها ضمن نطاق الرؤية.

مرشحات المركبات

تقبل connection وmovement وignition القيَم المدرجة فقط. لا يطبق المرشح الاختياري إذا كان مفقودًا أو فارغًا. تُرفض القيمة غير الصحيحة، بما فيها القيمة المرسلة كمصفوفة، بحالة HTTP 422 وبنية message وerrors المعتادة. يحدد مفتاح الحقل المرشح المرفوض. عند جمع مرشحات صحيحة تُعاد المركبات المطابقة لها جميعًا، باستخدام فهرس الحالة الحالية لا السجل.

{
    "message": "The selected connection is invalid.",
    "errors": { "connection": ["The selected connection is invalid."] }
}

قد تختلف الرسالة المقروءة؛ اعتمد على حالة HTTP ومفاتيح الحقول.

المعامل الاستخدام
uuid مطابقة UUID لمركبة
company مطابقة UUID لشركة
company_name مطابقة جزئية لاسم الشركة
brand مطابقة العلامة المصنعة
model مطابقة الطراز
plate_number مطابقة رقم اللوحة
tracked التصفية بحسب وجود جهاز تتبع مرتبط، باستخدام true أو false
connection online أو offline
movement moving أو idling أو parked أو no_gps
ignition on أو off
gps true أو false
search بحث جزئي غير حساس لحالة الأحرف
sort حقل ترتيب مدعوم، مع بادئة - للترتيب التنازلي

يشمل البحث رقم اللوحة واسم الشركة والعلامة والطراز ورقم المحرك ورقم الهيكل. حقول الترتيب المدعومة هي plate_number وbrand وmodel؛ حدد حقلًا واحدًا في الطلب.

GET https://api.tlgps.athear.ly/v1/vehicles?connection=online&movement=moving&sort=-model
Authorization: Bearer <token>
Accept: application/json

استجابة توضيحية للمجموعة:

{
    "data": [
        {
            "uuid": "01900000-0000-7000-8000-000000000001",
            "plate_number": "NF-241",
            "brand": "Astra",
            "model": "M588FS",
            "company": {
                "uuid": "01900000-0000-7000-8000-000000000002",
                "name": "Northstar Fleet Operations"
            },
            "location": {
                "source": "realtime",
                "status": {
                    "connection": "online",
                    "movement": "moving"
                },
                "coordinates": {
                    "latitude": 0.0,
                    "longitude": 0.0
                },
                "geo_address": null,
                "speed": {
                    "kmh": 62,
                    "mps": 17.22
                },
                "gps_status": true,
                "angle": 175,
                "altitude": 12,
                "ignition": {
                    "status": "on"
                },
                "oil": 81,
                "voltage": 13.7,
                "mileage": {
                    "km": 2485047,
                    "meters": 2485047000
                },
                "temperature": "28",
                "timestamps": {
                    "gps": "2026-06-29T23:47:43+02:00",
                    "received": "2026-06-29T23:47:43+02:00",
                    "last_synced": null
                }
            }
        }
    ],
    "links": {
        "first": "https://api.tlgps.athear.ly/v1/vehicles?page=1",
        "last": "https://api.tlgps.athear.ly/v1/vehicles?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 15,
        "total": 1
    }
}

تفاصيل المركبة

GET https://api.tlgps.athear.ly/v1/vehicles/{vehicle}
Authorization: Bearer <token>
Accept: application/json

استبدل بـ UUID لمركبة ظاهرة. يتطلب الطلب vehicles.view والصلاحية المقابلة. تُحل الموارد باستخدام UUID وليس مُعرّف قاعدة البيانات الرقمي. يعود 404 إذا لم تكن المركبة موجودة أو متاحة ضمن نطاق الرؤية.

الاستجابة الناجحة

{
    "data": {
        "uuid": "01900000-0000-7000-8000-000000000001",
        "plate_number": "NF-241",
        "brand": "Astra",
        "model": "M588FS",
        "company": {
            "uuid": "01900000-0000-7000-8000-000000000002",
            "name": "Northstar Fleet Operations"
        },
        "location": {
            "source": "realtime",
            "status": {
                "connection": "online",
                "movement": "moving"
            },
            "coordinates": {
                "latitude": 0.0,
                "longitude": 0.0
            },
            "geo_address": null,
            "speed": {
                "kmh": 62,
                "mps": 17.22
            },
            "gps_status": true,
            "angle": 175,
            "altitude": 12,
            "ignition": {
                "status": "on"
            },
            "oil": 81,
            "voltage": 13.7,
            "mileage": {
                "km": 2485047,
                "meters": 2485047000
            },
            "temperature": "28",
            "timestamps": {
                "gps": "2026-06-29T23:47:43+02:00",
                "received": "2026-06-29T23:47:43+02:00",
                "last_synced": null
            }
        }
    }
}

حالات الاستجابة

الحالة المعنى
200 أُعيدت المركبة
401 المصادقة مطلوبة
403 لا تسمح حدود الوصول بالعملية
404 المركبة غير موجودة أو غير متاحة

قد تكون location مساوية لـ null عند غياب جهاز تتبع أو حالة متاحة. تُفضّل الحالة الآنية المتاحة على الحالة المخزنة المستخدمة كبديل في مسار REST الحالي.

حالة المركبة وموقعها

يمثل location سياق المركبة المحلول. لا تفترض توفر جميع القيَم؛ يعتمد ذلك على الجهاز والمصدر والحالة المتاحة.

تُعرض timestamps.gps وtimestamps.received وtimestamps.last_synced في REST V1 بصيغة ISO-8601 وفق المنطقة الزمنية المهيأة للتطبيق، بدقة الثواني، أو null. مثال: 2026-10-20T09:08:09+02:00. لا يغيّر التنسيق الطابع الأصلي. يحتفظ Gateway V1 بصيغة UTC وست خانات كسرية لطوابع الحالة نفسها؛ قارن الوقت بعد التحليل وفق الدقة المتاحة، لا النصوص مباشرة.

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

الحقل المعنى
source مصدر الحالة: realtime أو database
status.connection الاتصال: online أو offline
status.movement الحركة: moving أو idling أو parked أو no_gps
coordinates خطوط الطول والعرض بالدرجات العشرية أو null
geo_address عنوان مقروء مستنتج من الإحداثيات أو null
speed.kmh السرعة بالكيلومتر في الساعة
speed.mps السرعة بالمتر في الثانية
gps_status صلاحية تحديد الموقع أو null
angle اتجاه المركبة بالدرجات من 0 إلى 359
altitude الارتفاع بالمتر أو null
ignition.status حالة التشغيل: on أو off
oil قراءة الوقود أو المستشعر أو null
voltage جهد الجهاز أو التغذية أو null
mileage.km المسافة بالكيلومتر
mileage.meters المسافة بالمتر
temperature قراءة الحرارة أو null
timestamps.gps وقت الرصد الصادر من الجهاز
timestamps.received وقت استقبال التتبع الآني
timestamps.last_synced وقت مزامنة الحالة المخزنة

تتضمن geo_address، عند توفرها، display_name وcity وstate وcountry وcountry_code. قد تكون قيَم المستشعرات وحقول التوقيت غير متاحة. تُنسّق طوابع REST الزمنية وفق المنطقة الزمنية للخادم؛ افحص الإزاحة عند مقارنتها ببيانات Gateway.

سجل المركبة

يتيح السجل قراءة نقاط التتبع المتاحة لفترة محددة. تحتاج المركبة إلى جهاز تتبع مرتبط ومصدر مهيأ يدعم سجلها.

إتاحة السجل

بعد التحقق من المصادقة وقدرة الرمز والصلاحية والرؤية، تُعاد حالة HTTP 409 إذا لم يكن للمركبة جهاز تتبع مرتبط:

{
    "message": "Vehicle history is unavailable because no tracking device is assigned."
}

إذا كان الجهاز مرتبطًا لكن إعداد التتبع المطلوب مفقودًا، تُعاد 409 أيضًا، وتكون message هي Vehicle history is unavailable because tracking is not configured for its assigned device. لا يُنفذ طلب سجل إلى المصدر في الحالتين. اطلب من موظف شركة مخوّل تصحيح الربط أو الإعداد قبل إعادة المحاولة.

تبقى المركبة غير المتاحة ضمن الرؤية بحالة 404 دون كشف وجود جهاز. تبقى الصلاحية أو قدرة الرمز غير الكافية بحالة 403، والمصادقة المفقودة أو غير الصحيحة بحالة 401. إذا كان الجهاز مهيأ ولا توجد سجلات للفترة، تُعاد 200 مع data: [] وبيانات الصفحات. لا تمنع بيانات حالة الجهاز الوصفية وحدها قراءة السجل. تبقى أعطال المصدر أو الخادم الحقيقية أخطاء 500 ولا تتحول إلى سجل فارغ أو تعارض متطلبات. تُعاد معاملات التاريخ والنطاق والصفحات غير الصحيحة بحالة 422 وأخطاء الحقول المعتادة.

GET https://api.tlgps.athear.ly/v1/vehicles/{vehicle}/history
Authorization: Bearer <token>
Accept: application/json

يتطلب الطلب vehicles.history والصلاحية المقابلة ورؤية المركبة.

معاملات السجل

المعامل مطلوب المعنى
from نعم بداية الفترة، بصيغة تاريخ قابلة للتحليل
to نعم نهاية الفترة؛ تساوي البداية أو تأتي بعدها
page لا رقم الصفحة، قيمة صحيحة لا تقل عن 1
per_page لا عدد النتائج، افتراضيًا 100، ضمن 1 إلى 100

تُفسّر التواريخ دون إزاحة صريحة وفق المنطقة الزمنية للخادم. تتضمن الاستجابة الطوابع بصيغة ISO-8601. مثال:

GET https://api.tlgps.athear.ly/v1/vehicles/01900000-0000-7000-8000-000000000001/history?from=2026-06-29T10:00:00&to=2026-06-29T12:00:00
Authorization: Bearer <token>
Accept: application/json

استجابة السجل

{
    "data": [
        {
            "coordinates": {
                "latitude": 0.0,
                "longitude": 0.0
            },
            "geo_address": null,
            "speed": {
                "kmh": 43,
                "mps": 11.94
            },
            "gps_status": true,
            "angle": 174,
            "altitude": 5,
            "ignition": {
                "status": "on"
            },
            "oil": 81,
            "voltage": 13.7,
            "mileage": {
                "km": 2485047,
                "meters": 2485047000
            },
            "temperature": "27",
            "timestamps": {
                "gps": "2026-06-29T10:02:55+02:00",
                "received": null,
                "last_synced": null
            }
        }
    ],
    "links": {
        "first": "https://api.tlgps.athear.ly/v1/vehicles/01900000-0000-7000-8000-000000000001/history?from=2026-06-29T10:00:00&to=2026-06-29T12:00:00&page=1",
        "last": "https://api.tlgps.athear.ly/v1/vehicles/01900000-0000-7000-8000-000000000001/history?from=2026-06-29T10:00:00&to=2026-06-29T12:00:00&page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "per_page": 100,
        "total": 1
    }
}

حقول نقطة السجل

تتضمن النقطة coordinates وgeo_address وspeed وgps_status وangle وaltitude وignition وoil وvoltage وmileage وtemperature وtimestamps، بحسب إتاحة المصدر والجهاز.

يحمل timestamps.gps وقت الرصد الأصلي. تكون received وlast_synced مساويتين لـ null في السجل. يحافظ السجل على ترتيب المصدر؛ إذا احتجت ترتيبًا زمنيًا فحلّل طوابع GPS ورتب وفقها. استخدم روابط الصفحات الواردة، ولا تفترض توفر سجل لكل فترة أو جهاز.

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

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

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