Convenções da API

Recursos e versões

As especificações usam recursos REST e versão /api/v1. Datas seguem ISO 8601 em UTC; dinheiro deve evitar ponto flutuante binário.

Paginação

Listagens usam parâmetros consistentes de página/limite ou cursor. A resposta deve informar continuidade e quantidade quando disponível.

Erros

{
  "erro": {
    "codigo": "FRETE_JANELA_INVALIDA",
    "mensagem": "A janela de coleta deve ser anterior à entrega.",
    "correlacaoId": "0192f7f8-5bc6-7ad4-a28a-6b64357b8bc2",
    "campos": [{"campo": "coletaFim", "motivo": "fora_da_janela"}]
  }
}

HTTP	Uso
400	Entrada inválida
401	Autenticação ausente ou expirada
403	Sem permissão para a operação
404	Recurso não encontrado no escopo
409	Conflito de estado ou idempotência
422	Regra de negócio não satisfeita
429	Limite de chamadas excedido
500/503	Falha interna ou dependência indisponível

Clientes devem usar retry apenas em falhas transitórias, com backoff e jitter.