Documentação técnica da API FleetPay

Uma API só, em dois ambientes: homologação em https://api.fleetpay.site/v1 e produção em https://api.fleetpay.tech/v1. Trilho fiscal (CT-e, CIOT, MDF-e, NF-e importadas), parcelas de repasse ao motorista, cadastros e consultas — autenticação por chave de API em homologação e OAuth2 em produção, com autorização por escopos.

O caminho de uma requisição

Nenhuma chamada chega a um recurso sem passar por três portas, nesta ordem: autenticação da credencial, escopo habilitado e isolamento por empresa. A borda gerenciada faz WAF e rate limit antes da aplicação; o token OAuth é emitido fora do /v1, no endpoint padrão /oauth/token.

Chave de API em homologação, OAuth2 em produção

As credenciais são geradas em Configurações → API de Integração no painel da sua empresa. A autorização é a mesma nas duas formas: os escopos habilitados para a empresa.

curl --request GET https://api.fleetpay.site/v1/fiscal/status \
  --header "Authorization: Bearer fp_hml_SUA_CHAVE"

curl --request POST https://api.fleetpay.tech/oauth/token \
  --data grant_type=client_credentials \
  --data client_id=SEU_CLIENT_ID \
  --data client_secret=SEU_CLIENT_SECRET

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}

Escopos fail-closed

A credencial nasce sem acesso. Cada escopo é um toggle no painel — habilite somente o que o seu sistema usa.

O que a API expõe

Operações simuladas em homologação

Nem toda operação tem provedor real por trás em homologação. As de baixo respondem em modo simulado: a resposta é gerada pela FleetPay, é plausível, é determinística e não tem efeito regulatório. O contrato de request e response já é o definitivo — integre agora; quando o provedor real entrar, o mesmo pedido passa a devolver dado real, no mesmo formato. Cada operação documenta os valores sentinela que forçam resposta de falha, para você testar o caminho de erro.

O trilho fiscal é outra história: CT-e e MDF-e passam por integração fiscal real no ambiente de homologação do provedor fiscal — emissão, consulta, XML, documento auxiliar, cancelamento, carta de correção, encerramento e inclusão de condutor.

Desenhada para operação financeira

Um envelope só, sempre rastreável

Toda falha responde o mesmo formato. Trate error.code por programa e guarde o request_id — é com ele que o suporte encontra a sua requisição.

{
  "error": {
    "code": "escopo_nao_habilitado",
    "message": "Habilite o escopo fiscal para esta credencial.",
    "request_id": "a1b2c3d4-e5f6-..."
  }
}