REST API / V1
المركبات
موارد REST API V1 والمصادقة وقراءات ضمن حدود الوصول.
تمثل المركبات الأصول المتتبعة. تجمع بيانات المركبة الثابتة مع آخر حالة تتبع محلولة عند توفرها. لا تُعاد إلا المركبات الظاهرة للمستخدم.
حقول المركبة
| الحقل | النوع | المعنى |
|---|---|---|
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 } }