> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.datalbus.com.br/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.datalbus.com.br/_mcp/server. # Introduction API para integradores consultarem os dados de telemetria da frota no Datalbus: veículos, dispositivos, motoristas, viagens, eventos e relatórios. ## URL base Todas as rotas desta documentação são relativas à variável `{{baseUrl}}`. O valor de produção está no ambiente **Produção** desta documentação. ## Autenticação 1. Faça `POST /login` com o e-mail e a senha do usuário de integração. A resposta traz o `token` (JWT). 2. Envie o token em todas as demais requisições, no cabeçalho `Authorization: Bearer `. 3. O token fica vinculado a **uma empresa** (tenant): por padrão, a primeira empresa liberada para o usuário. Consulte a empresa ativa com `GET /login` e troque de empresa com `PATCH /login`, que devolve um novo token. 4. **Cada novo login (`POST /login` ou `PATCH /login`) invalida os tokens anteriores do mesmo usuário.** Por isso: * use um usuário exclusivo para a integração, que não seja usado por pessoas nem por outros sistemas; * guarde o token e reutilize-o; faça um novo login só quando receber `401`. 5. A validade do token está na claim `exp` do JWT. ## Cabeçalhos | Cabeçalho | Quando enviar | | -------------------------------- | -------------------------------------------------------------------------------------------------------- | | `Accept: application/json` | Em **todas** as requisições. | | `Authorization: Bearer ` | Em todas as requisições, exceto `GET /healthcheck` e `POST /login`. | | `Content-Type: application/json` | Em requisições com corpo (`POST`, `PATCH`, `DELETE` com corpo). | | `Time-Zone: ` | Obrigatório em `GET /reports/events/listDetailed` e `GET /reports/faults`. Exemplo: `America/Sao_Paulo`. | ## Paginação As listas paginadas retornam este envelope: #### json ```json { "current_page": 1, "data": [ ... ], "first_page_url": "...", "from": 1, "last_page": 5, "last_page_url": "...", "links": [ ... ], "next_page_url": "...", "path": "...", "per_page": 10, "prev_page_url": null, "to": 10, "total": 47 } ``` #### JavaScript ```javascript { "current_page": 1, "data": [ ... ], "first_page_url": "...", "from": 1, "last_page": 5, "last_page_url": "...", "links": [ ... ], "next_page_url": "...", "path": "...", "per_page": 10, "prev_page_url": null, "to": 10, "total": 47 } ``` #### Python ```python { "current_page": 1, "data": [ ... ], "first_page_url": "...", "from": 1, "last_page": 5, "last_page_url": "...", "links": [ ... ], "next_page_url": "...", "path": "...", "per_page": 10, "prev_page_url": null, "to": 10, "total": 47 } ``` #### Java ```java { "current_page": 1, "data": [ ... ], "first_page_url": "...", "from": 1, "last_page": 5, "last_page_url": "...", "links": [ ... ], "next_page_url": "...", "path": "...", "per_page": 10, "prev_page_url": null, "to": 10, "total": 47 } ``` #### cURL ```curl { "current_page": 1, "data": [ ... ], "first_page_url": "...", "from": 1, "last_page": 5, "last_page_url": "...", "links": [ ... ], "next_page_url": "...", "path": "...", "per_page": 10, "prev_page_url": null, "to": 10, "total": 47 } ``` #### Shell ```bash { "current_page": 1, "data": [ ... ], "first_page_url": "...", "from": 1, "last_page": 5, "last_page_url": "...", "links": [ ... ], "next_page_url": "...", "path": "...", "per_page": 10, "prev_page_url": null, "to": 10, "total": 47 } ``` * `page`: número da página (padrão `1`). * `per_page`: itens por página (padrão `10`, máximo `1000`). * Para percorrer todas as páginas, repita a consulta incrementando `page` até `current_page` = `last_page`. * A ordem dos itens não é garantida. ## Datas e fusos horários * Os formatos de data **dos parâmetros** variam por endpoint e estão indicados em cada um: | Endpoint | Formato | | ------------------------------------------------------------------------------------------------------------ | ------------ | | `/trips`, `/trips/{id}/events`, `/trips/{id}/locations`, `/drivers/score*`, `/reports/vehicle-load` | `YYYY-MM-DD` | | `/reports/events/listDetailed`, `/reports/faults`, `/reports/retarder/*`, `/reports/engine-rotation-profile` | `DD/MM/YYYY` | | `/reports/performance` | `DD-MM-YYYY` | * Datas com `/` devem ser codificadas na URL (`26/10/2026` → `26%2F10%2F2026`). O Postman e a maioria das bibliotecas HTTP fazem isso automaticamente. * Horários de telemetria em `/trips`, `/trips/{id}/events`, `/trips/{id}/locations`, `/realtime-locations` e `/reports/vehicle-load` estão em **UTC**, no formato `YYYY-MM-DD HH:MM:SS` (sem indicação de fuso). * Campos `created_at` e `updated_at` estão em ISO-8601 UTC (ex.: `2026-10-25T10:24:02.000000Z`). * Nos relatórios com cabeçalho `Time-Zone`, as datas da resposta seguem o fuso informado. ## Tipos numéricos Alguns campos decimais são retornados como **string** (ex.: `"38.4"`). Converta-os no cliente. O tipo de cada campo está indicado nos endpoints. ## Erros | Status | Situação | Corpo | | ------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | `400` | Parâmetro inválido (em `POST /login` e nos endpoints de viagens) | `{"message": {"": [""]}}` | | `400` | `per_page` acima de 1000 | `{"error": "per_page must be less than or equal to 1000 for this resource."}` | | `401` | Token ausente, inválido, expirado ou substituído por um novo login | `{"message": "Unauthenticated."}` | | `403` | Usuário inativo ou sem acesso à empresa solicitada | ver endpoint | | `404` | Recurso ou resultado não encontrado (onde indicado) | ver endpoint | | `422` | Parâmetro inválido (demais endpoints) | `{"message": "", "errors": {"": [""]}}` | | `500` | Erro interno | `{"message": "Server Error"}` | As mensagens de validação são retornadas em português. ## Identificadores de veículo * `asset_id` em viagens, eventos, posições e carga do veículo é o **identificador do veículo na telemetria**. É o mesmo valor em todos esses endpoints e é o valor aceito pelo filtro `asset_id` de `GET /trips`. * O **prefixo** do veículo aparece como `asset_description` (`/assets`), `license_nmbr` (`/trips`), `description` (`/realtime-locations`) e `asset` (filtros). Use o prefixo para relacionar o cadastro de `/assets` com as viagens.