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

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

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
    }
}

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

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

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