Skip to navigation
Datalbus API V2

Introduction

View as Markdown

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 <token>.
  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çalhoQuando enviar
Accept: application/jsonEm todas as requisições.
Authorization: Bearer <token>Em todas as requisições, exceto GET /healthcheck e POST /login.
Content-Type: application/jsonEm requisições com corpo (POST, PATCH, DELETE com corpo).
Time-Zone: <fuso IANA>Obrigatório em GET /reports/events/listDetailed e GET /reports/faults. Exemplo: America/Sao_Paulo.

Paginação

As listas paginadas retornam este envelope:

{
  "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:
EndpointFormato
/trips, /trips/{id}/events, /trips/{id}/locations, /drivers/score*, /reports/vehicle-loadYYYY-MM-DD
/reports/events/listDetailed, /reports/faults, /reports/retarder/*, /reports/engine-rotation-profileDD/MM/YYYY
/reports/performanceDD-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

StatusSituaçãoCorpo
400Parâmetro inválido (em POST /login e nos endpoints de viagens){"message": {"<campo>": ["<mensagem>"]}}
400per_page acima de 1000{"error": "per_page must be less than or equal to 1000 for this resource."}
401Token ausente, inválido, expirado ou substituído por um novo login{"message": "Unauthenticated."}
403Usuário inativo ou sem acesso à empresa solicitadaver endpoint
404Recurso ou resultado não encontrado (onde indicado)ver endpoint
422Parâmetro inválido (demais endpoints){"message": "<mensagem>", "errors": {"<campo>": ["<mensagem>"]}}
500Erro 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.