Estado atual
A API por token usa nomes de método dentro de /api/v1/{token}/{metodo}, mas a revisão auditada não oferece versionamento independente por método nem uma política pública formal de estabilidade. Este documento define a política editorial recomendada; sua adoção pelo produto precisa ser aprovada antes de virar compromisso contratual.
Política recomendada
Uma mudança é compatível quando:
- adiciona campo opcional à resposta;
- adiciona parâmetro opcional com comportamento anterior preservado;
- adiciona novo método ou novo código de erro sem alterar os existentes;
- esclarece descrição sem mudar comportamento.
Uma mudança é incompatível quando:
- remove ou renomeia método, parâmetro ou campo documentado;
- altera tipo, unidade, obrigatoriedade, paginação ou semântica;
- muda autenticação, escopo ou isolamento por empresa;
- muda sucesso para erro, ou o inverso, para a mesma entrada;
- faz uma consulta produzir efeito de negócio novo.
Janela recomendada
Depois de aprovada como política do produto:
- anunciar depreciação no changelog e na página do método;
- oferecer substituto e guia de migração;
- manter a forma anterior por pelo menos 90 dias, salvo incidente de segurança ou obrigação legal;
- incluir headers de depreciação quando a arquitetura permitir;
- remover somente após telemetria sanitizada e comunicação aos integradores afetados.
Esta janela ainda é recomendação, não garantia vigente.
Regras para consumidores hoje
- Aceite campos adicionais em objetos.
- Não gere modelos fechados a partir dos exemplos atuais.
- Valide campos essenciais e trate valores nulos.
- Fixe o conjunto de métodos que sua integração usa.
- Teste contra a versão efetivamente implantada antes de adotar uma mudança.
- Não confunda documentação atualizada com backend publicado.