← Справочник / Reference Български English

FleetBee API — ръководство (бета)

Адрес: https://data.fleetbee.eu/v1. Само четене, JSON. Пълният списък на маршрутите е в справочника.

Ключове

Ключ създава Администраторът на фирмата: настройки → „API ключове“. Избира права по вид данни (коли, шофьори, курсове, позиции, пътни листове, аларми, OBD, дневник, срокове), по желание списък с IP адреси. Ключът се показва веднъж. До два активни ключа едновременно (за смяна без прекъсване); отнемането важи веднага (до 5 s).

curl -H "Authorization: Bearer fb_live_…" https://data.fleetbee.eu/v1/vehicles

Тестов ключ fb_test_… — демо фирма с изкуствени данни, само четене; ползва се от бутона „Опитай“ в справочника. Има собствен, по-строг лимит.

Лимити

Какво	Стойност
Заявки на ключ	30 в минута
Заявки на фирма (всички ключове)	60 в минута
Едновременни заявки на фирма	2 (следващата чака до 5 s, после `429 BUSY`)
Записи на страница	до 1000 (`limit`, `cursor` / `nextCursor`)
Позиции	до 1 ден на заявка; назад до 3 месеца
Размер на отговора	до 2 MB, иначе `400 RESPONSE_TOO_LARGE`

При 429 изчакайте Retry-After секунди (и в полето error.retryAfterSec).

Лентата `GET /feed`

Лентата дава новото след курсор за позиции, курсове, аларми и корекции: подавате nextCursor от предишния отговор. Без курсор — последните 24 часа.
Лаг 30 s: виждат се само записи, записани преди повече от 30 секунди. Така нищо не се появява „зад“ курсора ви и не се губи.
Корекции: променен или преизчислен курс идва отново като trip (последното състояние), изтрит курс — като trip_deleted (потокът trips); изтрити координати на кола за период — като correction (потокът corrections). Обновете/изтрийте същото и при себе си.
410 Gone: курсорът е твърде стар или невалиден за лентата. Започнете наново без курсор (и сверете периода с обикновените маршрути).
7 дни: закъсняла позиция се приема в лентата само ако time ѝ е до 7 дни назад; по-стара не се появява в лентата (виж я през /vehicles/{id}/positions).
Лентата е „поне веднъж“: пазете последния курсор и приемайте повторение (дедупликация по идентификатор).

Грешки

Тялото винаги е { "error": { "code", "message", "details?", "retryAfterSec?" } }.

HTTP	Код	Значение
400	`VALIDATION_ERROR`	Невалидни параметри или курсор.
400	`RESPONSE_TOO_LARGE`	Отговорът надхвърля тавана; поискайте по-малка страница или по-кратък период.
401	`AUTH_REQUIRED`	Липсва, невалиден или отнет ключ.
403	`FORBIDDEN`	Ключът няма право за ресурса или не е разрешен от този IP адрес.
404	`NOT_FOUND`	Няма такъв запис (или е на друга фирма).
409	`CONFLICT`	Конфликт със състоянието на ресурса (напр. износ, който още се подготвя).
410	`CURSOR_EXPIRED`	Курсорът на лентата е изтекъл — започнете без курсор.
429	`RATE_LIMITED` / `BUSY`	Лимит на заявки или твърде много едновременни; виж `Retry-After`.
500	`INTERNAL_ERROR`	Наша грешка; посочете `requestId` в поддръжката.

Промени в бета

Версията е в адреса (/v1). Докато API-то е бета, добавящи промени (нов маршрут, ново поле в отговор, нова стойност в списък) се правят без предизвестие — игнорирайте непознати полета. Несъвместима промяна (махане или преименуване на маршрут/поле, промяна на тип или значение) се обявява поне 2 седмици предварително по имейл до Администратора на всяка фирма с активен ключ. CI проверката oasdiff breaking спира такава промяна, докато не е обявена.

FleetBee API guide (beta)

Base URL: https://data.fleetbee.eu/v1. Read-only JSON. Every route is listed in the reference.

API keys

A company Administrator creates a key under Settings → “API keys”, choosing per-resource read scopes (vehicles, drivers, trips, positions, waybills, alarms, OBD, log, deadlines) and optionally an IP allow-list. The key is shown once. Up to two active keys at a time (rotate without downtime); revocation takes effect within 5 s.

curl -H "Authorization: Bearer fb_live_…" https://data.fleetbee.eu/v1/vehicles

The test key fb_test_… reads a demo company with synthetic data, read-only; the reference’s “Try it” button uses it. It has its own stricter limit.

Limits

What	Value
Requests per key	30 per minute
Requests per company (all keys)	60 per minute
Concurrent requests per company	2 (the next waits up to 5 s, then `429 BUSY`)
Page size	up to 1000 (`limit`, `cursor` / `nextCursor`)
Positions	at most 1 day per request, going back at most 3 months
Response size	up to 2 MB, otherwise `400 RESPONSE_TOO_LARGE`

On 429 wait Retry-After seconds (also in error.retryAfterSec).

The feed `GET /feed`

The feed returns what is new after a cursor for positions, trips, alarms and corrections: pass the previous response’s nextCursor. Without a cursor you get the last 24 hours.
30 s lag: only records written more than 30 seconds ago are visible, so nothing can appear behind your cursor and get lost.
Corrections: a changed or recalculated trip arrives again as trip (its latest state), a deleted trip as trip_deleted (the trips stream); erased coordinates of a vehicle for a period as correction (the corrections stream). Refresh or delete the same on your side.
410 Gone: the cursor is too old or no longer valid. Restart without a cursor (and reconcile the period through the regular routes).
7 days: a late position enters the feed only if its time is at most 7 days old; older ones do not appear (read them via /vehicles/{id}/positions).
Delivery is at-least-once: store the last cursor and de-duplicate by identifier.

Errors

The body is always { "error": { "code", "message", "details?", "retryAfterSec?" } }.

HTTP	Code	Meaning
400	`VALIDATION_ERROR`	Invalid parameters or cursor.
400	`RESPONSE_TOO_LARGE`	Response above the cap; ask for a smaller page or a shorter period.
401	`AUTH_REQUIRED`	Missing, invalid or revoked key.
403	`FORBIDDEN`	The key lacks the scope, or the caller IP is not allowed.
404	`NOT_FOUND`	No such record (or it belongs to another company).
409	`CONFLICT`	Conflict with the resource state (e.g. an export still being prepared).
410	`CURSOR_EXPIRED`	The feed cursor expired — restart without a cursor.
429	`RATE_LIMITED` / `BUSY`	Rate limit or too many concurrent requests; see `Retry-After`.
500	`INTERNAL_ERROR`	Our fault; quote `requestId` to support.

Change policy during beta

The version is in the URL (/v1). While the API is in beta, additive changes (new route, new response field, new enum value) ship without notice — ignore unknown fields. A breaking change (removing or renaming a route or field, changing a type or meaning) is announced at least 2 weeks ahead by email to the Administrator of every company with an active key. The CI check oasdiff breaking blocks such a change until it has been announced.