Versionamento e depreciação
Como a v1 evolui sem quebrar integrações publicadas.
Atualizado em 01/09/2026
- O prefixo /v1 define a versão major do contrato HTTP público.
- Mudanças compatíveis podem adicionar campos opcionais, novos endpoints ou novos eventos sem trocar a major.
- Clientes devem ignorar campos JSON desconhecidos e não assumir ordem de propriedades.
- Mudança incompatível exige nova versão pública ou uma estratégia de depreciação explícita; não será escondida em uma alteração silenciosa da v1.
- Uma major já disponível em Production tem janela normal mínima de 365 dias entre o anúncio público de depreciação e o sunset.
- Toda depreciação informa escopo afetado, substituição, caminho de migração e data de sunset no Changelog e na documentação.
- Urgência legal, segurança ou abuso pode exigir janela excepcional menor, sempre com comunicação explícita e nunca como breaking silencioso da v1.
- Não existe alias legado para contratos que nunca foram lançados publicamente; o contrato atual é a authority.
Importante: Não hardcode textos de erro nem listas fechadas de campos de response. Faça lógica por status/code e preserve tolerância a campos adicionais compatíveis.