API REST

Consultas DGT para carteiras de milhares de veículos.

Integra as consultas do teu stock ou frota através de lotes de matrículas. Acompanha cada pedido, obtém o resumo JSON após a análise e descarrega o PDF oficial quando estiver disponível.

Solicitar acesso à API

Um contrato pensado para integrar

Acesso por empresa

Tokens Bearer com permissões definidas e revogação no portal empresarial.

Resumo JSON e PDF

O detalhe do relatório disponibiliza 17 campos do veículo após a análise e acesso ao PDF disponível. Os resultados podem ser nulos durante o processamento.

Lotes assíncronos

POST /reports/batch aceita um array plates e devolve 202. Cada lote respeita o limite configurado e é processado em segundo plano.

Idempotência e acompanhamento

Idempotency-Key identifica os teus pedidos. Consulta depois o estado, o progresso e o resultado através de GET.

/v1

Endpoints principais

API REST versionada em /api/v1, com autenticação por token, limites e um modelo de erros documentado.

Autenticação

Token Bearer associado a uma empresa, com permissões que limitam as operações disponíveis. Podes revogar uma credencial no portal sem afetar as restantes.

Authorization: Bearer <token>

reports	Solicita um relatório DGT, lista-os, lê um, descarrega o seu PDF.
reports/batch	Envia muitas matrículas de uma vez; a carga corre fora do pedido.
usage	Saldo, plano e o livro de movimentos.
vehicles	A tua frota. Opcional, porque solicitar um relatório já regista o seu veículo.
locations · departments · subsidiaries · batches	Como a frota se organiza.

Exemplo de pedido de relatório

curl -X POST https://veriflota.es/api/v1/reports \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"plate":"1234BCD"}'

Resposta inicial: processamento pendente

{
  "id": "01M0ANQ0DFADGVM5PV26ZYV3YX",
  "plate": "1234BCD",
  "status": "placed",
  "progress": "queued",
  "requester": { "type": "api_credential", "name": null },
  "placedAt": "2026-08-19T09:14:22+00:00",
  "settledAt": null,
  "outcome": { "returnCode": null, "documentAvailable": false },
  "vehicle": null
}

Modelo de erros

Erros JSON consistentes, com códigos de máquina estáveis, mapeados a partir das exceções internas.

{
  "error": {
    "code": "insufficient_report_balance",
    "message": "Not enough reports left on this account.",
    "details": { "needed": 5, "available": 2, "shortfall": 3 }
  }
}

unauthenticatedinsufficient_scopevalidation_failedinsufficient_report_balancereport_already_in_flightidempotency_key_reusedrate_limited

Referência completa da API

Todos os endpoints, corpos de pedido, campos de resposta e códigos de erro, gerados a partir da própria API. Inicia sessão para a ler; se ainda não tens conta, solicita primeiro o acesso.

Abrir a referência

Pronto para integrar?

Conta-nos o teu volume de consultas e a integração de que precisas. Ajudamos-te a preparar o acesso para a tua empresa.

Solicitar acesso à API