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 ورتب وفقها. استخدم روابط الصفحات الواردة، ولا تفترض توفر سجل لكل فترة أو جهاز.