Vera Public API (1.0.0)

Download OpenAPI specification:

Filo takip verileri (araçlar, canlı konumlar, raporlar ve geçmiş) için genel (public) REST API. Eski SOAP servisinin yerini alır; aşağıdaki modernize edilmiş JSON alan adları, tüm API kullanıcıları için eski SOAP alanlarının yerini tamamen alır.

Kimlik doğrulama

Tüm uç noktalar, HTTP Bearer token olarak gönderilen bir API anahtarı gerektirir: Authorization: Bearer <anahtar>. Anahtarlar firma bazında verilir; her anahtar yalnızca o firmanın araçlarına erişebilir.

Yanıt zarfı (envelope)

Başarılı yanıtlar her zaman { "data": ..., "meta": { "count": N } } biçimindedir. Hatalar { "error": { "code": "...", "message": "..." } } biçimindedir; code makine tarafından okunabilir, message İngilizce ve insan tarafından okunabilir bir açıklamadır.

Sahiplik koruması (ownership guard)

İstenen deviceId, çağıranın hesabına ait değilse (anahtarın araç kapsamına göre), API 404/403 döndürmez — HTTP 200 ile boş sonuç döner: { "data": [], "meta": { "count": 0 } }. Bu davranış, eski servisin yetkisiz/bilinmeyen cihazlar için "sonuç yok" davranışıyla eşleşir.

Tarih aralığı sınırları

date1/date2 alan rapor ve geçmiş uç noktaları, sunucu tarafında en fazla aralık uygular:

/v1/history/tracking: 300 gün
diğer tüm tarih-aralıklı uç noktalar (/v1/reports/mileage, /v1/reports/working-hours, /v1/reports/heat, /v1/history/alarms): 32 gün

Sınırın aşılması, date1'in date2'den sonra olması veya geçersiz bir tarih biçimi, HTTP 422 ve {"error":{"code":"INVALID_DATE_RANGE", ...}} ile sonuçlanır.

Auth

API anahtarı doğrulama.

API anahtarını doğrula

Sağlanan Authorization: Bearer API anahtarının geçerli, aktif ve (IP kısıtlaması varsa) izin verilen bir IP'den çağrıldığını onaylar. Anahtar bu handler çalışmadan önce middleware tarafından zaten doğrulanmıştır; 200 yanıtı yalnızca geçerliliği teyit eder.

Authorizations:

bearerAuth

Responses

Response samples

200
401
403

Content type

application/json

{"data": {"valid": true
},
"meta": { }
}

Vehicles

Filo araç listesi.

Kimliği doğrulanmış hesabın tüm araçlarını listele

API anahtarının bağlı olduğu hesabın erişebildiği tüm araçları döner (hesabın araç kapsamı üzerinden). Sorgu parametresi yoktur. Eski DRIVER alanı bu uç noktada kasıtlı olarak yer almaz (eski servisle veri (wire) uyumluluğu için).

Authorizations:

bearerAuth

Responses

Response samples

200
401
403

Content type

application/json

{"data": [{"deviceId": "352093081234567",
"licensePlate": "34 ABC 123",
"deviceType": "FMC130"
}
],
"meta": {"count": 42
}
}

Locations

Araçların canlı/son bilinen konumları.

Bir veya tüm araçların son bilinen konumunu al

Araç başına en son bilinen konum/telemetri verisini döner. deviceId boş bırakılırsa veya gönderilmezse, hesap kapsamındaki tüm araçların son konumu döner. deviceId gönderilir ama hesaba ait değilse, hata değil boş liste döner (sahiplik koruması — üstteki genel açıklamaya bakın).

Authorizations:

bearerAuth

query Parameters

deviceId

string

Example: deviceId=352093081234567

Cihaz kimliği (IMEI). Hesap kapsamındaki tüm araçları dahil etmek için boş bırakılabilir veya gönderilmeyebilir. Hesaba ait olmayan bir deviceId gönderilirse yanıt boş liste olur (HTTP 200), hata değil.

Responses

Response samples

200
401
403

Content type

application/json

{"data": [{"deviceId": "352093081234567",
"licensePlate": "34 ABC 123",
"address": "Atatürk Bulvarı No:1, Ankara",
"latitude": 39.925018,
"longitude": 32.836956,
"speed": 62.5,
"heading": 180,
"mileageKm": 123456.7,
"driver": "Ahmet Yılmaz",
"ignition": true,
"workingHours": 8.5
}
],
"meta": {"count": 42
}
}

Reports

Tarih aralığı üzerinden kilometre, çalışma saati ve sıcaklık raporları.

Günlük kilometre (mesafe) raporu

date1 ile date2 arasında (dahil), cihaz başına ve gün başına kat edilen mesafeyi (km) döner. deviceId isteğe bağlıdır; kapsamdaki tüm araçlar için boş bırakılabilir. Maksimum aralık: 32 gün.

Authorizations:

bearerAuth

query Parameters

deviceId	string Example: deviceId=352093081234567 Cihaz kimliği (IMEI). Hesap kapsamındaki tüm araçları dahil etmek için boş bırakılabilir veya gönderilmeyebilir. Hesaba ait olmayan bir `deviceId` gönderilirse yanıt boş liste olur (HTTP 200), hata değil.
date1 required	string <date> Example: date1=2026-07-01 Aralık başlangıç tarihi, dahil, `YYYY-MM-DD`.
date2 required	string <date> Example: date2=2026-07-02 Aralık bitiş tarihi, dahil, `YYYY-MM-DD`. `date1`'den önce olamaz.

Responses

Response samples

200
401
403
422

Content type

application/json

{"data": [{"deviceId": "352093081234567",
"licensePlate": "34 ABC 123",
"date": "2026-07-01",
"distanceKm": 214.3
}
],
"meta": {"count": 42
}
}

Toplam çalışma saati raporu

date1..date2 aralığı boyunca cihaz başına tek bir toplam çalışma saati değeri döner (gün başına bir satır değil). deviceId isteğe bağlıdır; kapsamdaki tüm araçlar için boş bırakılabilir. Maksimum aralık: 32 gün. Eski serviste her zaman boş dönen DATE alanı bu uç noktanın çıktısından kaldırılmıştır.

Authorizations:

bearerAuth

query Parameters

deviceId	string Example: deviceId=352093081234567 Cihaz kimliği (IMEI). Hesap kapsamındaki tüm araçları dahil etmek için boş bırakılabilir veya gönderilmeyebilir. Hesaba ait olmayan bir `deviceId` gönderilirse yanıt boş liste olur (HTTP 200), hata değil.
date1 required	string <date> Example: date1=2026-07-01 Aralık başlangıç tarihi, dahil, `YYYY-MM-DD`.
date2 required	string <date> Example: date2=2026-07-02 Aralık bitiş tarihi, dahil, `YYYY-MM-DD`. `date1`'den önce olamaz.

Responses

Response samples

200
401
403
422

Content type

application/json

{"data": [{"deviceId": "352093081234567",
"licensePlate": "34 ABC 123",
"workingHours": 63.25
}
],
"meta": {"count": 42
}
}

Sıcaklık (ısı sensörü) raporu

Tek bir cihaz için date1 ile date2 arasında, konum/telemetri bağlamıyla birlikte sıcaklık sensörü ölçümlerini döner. deviceId zorunludur. Maksimum aralık: 32 gün.

Authorizations:

bearerAuth

query Parameters

deviceId required	string Example: deviceId=352093081234567 Cihaz kimliği (IMEI). Bu uç nokta için zorunludur. Cihaz hesaba ait değilse yanıt boş liste olur (HTTP 200), hata değil. Gönderilmezse HTTP 422 ve `{"error":{"code":"MISSING_PARAMETER", ...}}` döner.
date1 required	string <date> Example: date1=2026-07-01 Aralık başlangıç tarihi, dahil, `YYYY-MM-DD`.
date2 required	string <date> Example: date2=2026-07-02 Aralık bitiş tarihi, dahil, `YYYY-MM-DD`. `date1`'den önce olamaz.

Responses

Response samples

200
401
403
422

Content type

application/json

{"data": [{"deviceId": "352093081234567",
"licensePlate": "34 ABC 123",
"timestamp": "2026-07-01T08:15:00+03:00",
"temperature": 4.2,
"address": "Atatürk Bulvarı No:1, Ankara",
"latitude": 39.925018,
"longitude": 32.836956,
"speed": 62.5,
"ignition": true,
"heading": 180
}
],
"meta": {"count": 42
}
}

CAN-Bus telemetri raporu

Tek bir cihaz için date1 ile date2 arasında CAN-Bus telemetri ölçümlerini döner (motor devri, soğutma suyu sıcaklığı, hız, yakıt seviyesi, mesafe, yakıt tüketimi vb.). deviceId zorunludur. Maksimum aralık: 32 gün. Her ölçüm zaman damgası için bir satır; o ölçümde bulunmayan bir sinyal null olur.

Authorizations:

bearerAuth

query Parameters

deviceId required	string Example: deviceId=352093081234567 Cihaz kimliği (IMEI). Bu uç nokta için zorunludur. Cihaz hesaba ait değilse yanıt boş liste olur (HTTP 200), hata değil. Gönderilmezse HTTP 422 ve `{"error":{"code":"MISSING_PARAMETER", ...}}` döner.
date1 required	string <date> Example: date1=2026-07-01 Aralık başlangıç tarihi, dahil, `YYYY-MM-DD`.
date2 required	string <date> Example: date2=2026-07-02 Aralık bitiş tarihi, dahil, `YYYY-MM-DD`. `date1`'den önce olamaz.

Responses

Response samples

200
401
403
422

Content type

application/json

{"data": [{"deviceId": "352093081234567",
"licensePlate": "34 ABC 123",
"timestamp": "2026-07-01T08:15:00+03:00",
"engineRpm": 1450,
"coolantTemp": 87.5,
"speed": 62,
"fuelLevelPercent": 74,
"fuelLevelLitres": 148,
"totalDistanceKm": 123456.7,
"totalFuelUsed": 4820.5,
"fuelRate": 12.3,
"address": "Atatürk Bulvarı, Edirne"
}
],
"meta": {"count": 42
}
}

Yolcu iniş/biniş raporu

Çağıranın firmasına ait yolcu biniş kayıtlarını (biniş ve iniş zamanı, konum ve koordinatlar, plaka ve cihaz) date1 ile date2 arasında (biniş zamanı üzerinden) döner. Diğer rapor endpoint'lerinden farklı olarak bu, cihaza değil firmaya göre kapsamlanır — çağıran firmasının tüm yolcu binişlerini görür. Maksimum aralık: 32 gün. Opsiyonel plateNumber plakaya göre filtreler (kısmi eşleşme).

Authorizations:

bearerAuth

query Parameters

date1 required	string <date> Example: date1=2026-07-01 Aralık başlangıç tarihi, dahil, `YYYY-MM-DD`.
date2 required	string <date> Example: date2=2026-07-02 Aralık bitiş tarihi, dahil, `YYYY-MM-DD`. `date1`'den önce olamaz.
plateNumber	string Example: plateNumber=34 ABC Opsiyonel plaka filtresi (kısmi, büyük/küçük harf duyarsız eşleşme).

Responses

Response samples

200
401
403
422

Content type

application/json

{"data": [{"passengerName": "Ahmet Yılmaz",
"plateNumber": "34 ABC 123",
"deviceId": "352093081234567",
"boardingTime": "2026-07-06T08:15:00+03:00",
"alightingTime": "2026-07-06T08:47:00+03:00",
"boardingAddress": "Kadıköy, İstanbul",
"boardingLatitude": 40.9901,
"boardingLongitude": 29.0301,
"alightingAddress": "Beşiktaş, İstanbul",
"alightingLatitude": 41.0422,
"alightingLongitude": 29.0089
}
],
"meta": {"count": 42
}
}

History

Tarih aralığı üzerinden geçmiş konum ve alarm olayları.

Geçmiş konum (rota) noktaları

Tek bir cihaz için date1 ile date2 arasındaki geçmiş konum/telemetri noktalarını döner. deviceId zorunludur. Maksimum aralık: 300 gün (diğer tarih-aralıklı uç noktalardan daha geniş).

Authorizations:

bearerAuth

query Parameters

deviceId required	string Example: deviceId=352093081234567 Cihaz kimliği (IMEI). Bu uç nokta için zorunludur. Cihaz hesaba ait değilse yanıt boş liste olur (HTTP 200), hata değil. Gönderilmezse HTTP 422 ve `{"error":{"code":"MISSING_PARAMETER", ...}}` döner.
date1 required	string <date> Example: date1=2026-07-01 Aralık başlangıç tarihi, dahil, `YYYY-MM-DD`.
date2 required	string <date> Example: date2=2026-07-02 Aralık bitiş tarihi, dahil, `YYYY-MM-DD`. `date1`'den önce olamaz.

Responses

Response samples

200
401
403
422

Content type

application/json

{"data": [{"deviceId": "352093081234567",
"licensePlate": "34 ABC 123",
"timestamp": "2026-07-01T08:15:00+03:00",
"address": "Atatürk Bulvarı No:1, Ankara",
"latitude": 39.925018,
"longitude": 32.836956,
"speed": 62.5,
"ignition": true,
"heading": 180
}
],
"meta": {"count": 42
}
}

Geçmiş alarm olayları

Tek bir cihaz için date1 ile date2 arasındaki, konum bağlamıyla birlikte geçmiş alarm olaylarını döner. deviceId zorunludur. Maksimum aralık: 32 gün. Diğer rapor/geçmiş uç noktalarından farklı olarak satırlarda ignition alanı bulunmaz.

Authorizations:

bearerAuth

query Parameters

deviceId required	string Example: deviceId=352093081234567 Cihaz kimliği (IMEI). Bu uç nokta için zorunludur. Cihaz hesaba ait değilse yanıt boş liste olur (HTTP 200), hata değil. Gönderilmezse HTTP 422 ve `{"error":{"code":"MISSING_PARAMETER", ...}}` döner.
date1 required	string <date> Example: date1=2026-07-01 Aralık başlangıç tarihi, dahil, `YYYY-MM-DD`.
date2 required	string <date> Example: date2=2026-07-02 Aralık bitiş tarihi, dahil, `YYYY-MM-DD`. `date1`'den önce olamaz.

Responses

Response samples

200
401
403
422

Content type

application/json

{"data": [{"deviceId": "352093081234567",
"licensePlate": "34 ABC 123",
"timestamp": "2026-07-01T08:15:00+03:00",
"address": "Atatürk Bulvarı No:1, Ankara",
"latitude": 39.925018,
"longitude": 32.836956,
"speed": 62.5,
"heading": 180,
"alarm": "Overspeed"
}
],
"meta": {"count": 42
}
}