Documentação

Guia textual da API frete.center: autenticação, ambientes, paginação, rate limits, formatos e webhooks.

Ambientes

Autenticação

A API expõe dois esquemas de auth conforme caso de uso:

1. Bearer JWT (apps mobile / SPA web)

Use POST /api/app/v1/auth/login com email + senha pra receber par access_token (1h) + refresh_token (30 dias, single-use).

curl -X POST https://frete.center/api/app/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"voce@empresa.com","password":"sua_senha","device":"iPhone 14 Pro"}'

Em todas as requests subsequentes, mande:

Authorization: Bearer SEU_ACCESS_TOKEN

Quando receber 401 invalid_or_expired_token, troque o refresh por novo par:

POST /api/app/v1/auth/refresh
{"refresh_token":"..."}

2. API Key (server-to-server / integrações de terceiros)

Pra integração backend (sem login interativo), use API Keys que você gera em /api-keys:

X-Frete-Key: fe_live_xxxxxxxxxxxxxxxxxxxxxx

API Keys são válidas pros endpoints /v1/* (separadas das rotas /api/app/v1/* que usam JWT).

Paginação

Endpoints que listam aceitam:

?limit=50&offset=0

Resposta inclui total, limit, offset quando aplicável. Default limit=50, máx 500.

Rate Limits

Resposta 429 Too Many Requests com header Retry-After: seconds.

Formato de erros

Todos endpoints retornam JSON. Erros têm:

{
  "ok": false,
  "error": "código_legível_em_snake_case",
  "message": "explicação humana opcional"
}

Códigos comuns:

• unauthorized — sem ou com token inválido (401)
• forbidden — autenticado mas sem permissão (403)
• not_found — recurso inexistente (404)
• validation_failed — body inválido (422)
• insufficient_funds — saldo carteira insuficiente (402)
• quote_expired — cotação Lalamove expirou (410)
• rate_limited — bateu rate limit (429)

Webhooks

Eventos relevantes podem ser enviados pra um endpoint do seu lado. Configure em team settings (em breve no dev portal).

Eventos disponíveis:

• tracking.driver_assigned
• tracking.picked_up
• tracking.delivered
• tracking.sla_breached
• tracking.canceled
• wallet.credit
• wallet.debit

Payload é assinado com HMAC-SHA256 no header X-Frete-Signature: sha256=....

Privacidade

frete.center segue LGPD (Lei 13.709/2018). Veja Política de Privacidade, Central LGPD e Termos de Uso.

Coordenadas de motoristas em endpoints públicos são jittered ~300m conforme DPIA-001.

Quer ver tudo navegável e testar interativamente? API Reference → · Sandbox →