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

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

REST API / V1

سجل المركبة

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

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

إتاحة السجل

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

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

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

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