Pular para o conteúdo principal
As rotas sem versão continuam funcionando. Para integrações novas, use a v1; para as existentes, a troca é de path.

​
Passo a passo

1

Troque o prefixo

/api/ vira /api/v1/ nas rotas de calculadoras, consultas e JusScore. Health continua em /api/health.
2

Troque o nome da correção simples

correction_simple vira correcao-simples.
3

Consultas assíncronas

O statusUrl do 202 aponta para a versão em que a consulta foi criada, e o GET do protocolo funciona nas duas versões. O webhook não muda: mesmo corpo, mesma assinatura.
4

JusScore

Na v1, acompanhe a consulta pelo GET /api/v1/jus-score/{id_consulta}; url_retorno responde 400 por enquanto. Quando o webhook assinado chegar à v1, ele virá só com a assinatura HMAC, sem a x-api-key, e esta página trará a verificação. Se depende do webhook hoje, continue no legado até lá.
Algumas rotas existem só na v1: GET /api/v1/consumo e o relatório PDF da calculadora completa.

​
Como saber que o legado foi depreciado

Quando o legado for depreciado, toda resposta dele passa a trazer: A data entra no changelog antes de valer.

​
Política de versionamento

A versão vai no path (/api/v1/...). A versão do contrato segue semver: MAJOR é a versão do path, MINOR é mudança compatível e PATCH é só documentação. Mudanças compatíveis entram na versão atual, sem aviso prévio. Sua integração deve tolerá-las:
  • campo novo na resposta;
  • campo opcional novo no request;
  • rota nova;
  • valor novo de enum na resposta, quando o campo estiver documentado como extensível;
  • código de erro novo para uma condição que antes não era tratada.
Mudanças incompatíveis só entram numa versão nova de path:
  • remover ou renomear path, campo ou valor de enum;
  • tornar obrigatório um campo opcional;
  • mudar o tipo ou o formato de um campo;
  • mudar o significado de um status code;
  • mudar o formato do envelope ou do erro;
  • mudar a assinatura ou o corpo de um webhook.
Quando uma versão é depreciada, você recebe três sinais: os headers acima, as operações marcadas como deprecated na referência da versão e comunicação direta aos clientes que ainda a chamam. Uma versão só é desligada quando o prazo de aviso venceu e todo cliente que ainda a chama foi contatado. Desligada, as rotas dela respondem 410 Gone, no formato de erro padrão, com a message apontando para este guia.