Versões e depreciação

O que pode mudar sem aviso, e o que nunca muda.

A API está em v1, e a versão vive no caminho: https://api.amivu.com.br/v1. Enquanto ela existir, o contrato descrito nesta documentação continua valendo.

O que pode mudar sem aviso

Estas mudanças são retrocompatíveis e podem acontecer a qualquer momento:

Campo novo num objeto de resposta.
Valor novo num campo que já é aberto — um code de erro novo, um type de canal novo.
Rota nova, ou parâmetro opcional novo numa rota existente.
Evento novo de webhook. Ele só chega a quem o assinar.
Mudança na ordem de campos do JSON, ou no texto de message num erro.

Seu código precisa tolerar campo desconhecido

Um analisador que estoure ao ver uma chave que não conhece quebra na primeira melhoria da API. Ignore o que não reconhece — vale para respostas e para webhooks.

O que é quebra

Nada disso acontece dentro de uma versão:

Remover ou renomear um campo de resposta.
Mudar o tipo de um campo, ou torná-lo nulo quando não era.
Tornar obrigatório um parâmetro que era opcional.
Remover uma rota, um valor de enum ou um evento.
Mudar o significado de um campo — o mais traiçoeiro, e o mais proibido.

Quando algo assim for necessário, nasce uma versão nova. A anterior continua no ar durante o prazo abaixo.

Política de depreciação

Anúncio	No changelog e por e-mail para quem usou a rota nos últimos 30 dias.
Aviso na resposta	O cabeçalho `Deprecation` acompanha toda resposta da rota, e `Sunset` diz a data de desligamento.
Prazo mínimo	12 meses entre o anúncio e o desligamento.
Segurança	Uma falha grave pode encurtar o prazo. Nesse caso o aviso é individual, direto ao responsável pela conta.

Deprecation: Sat, 26 Aug 2028 00:00:00 GMT
Sunset: Wed, 26 Aug 2029 00:00:00 GMT
Link: <https://developers.amivu.com.br/docs/changelog>; rel="deprecation"

Como escrever código que sobrevive

Trate o type do erro; registre o code em vez de fazer switch exaustivo nele.
Não deduza formato de identificador. Guarde-os como texto opaco — o dia em que a codificação interna mudar, o seu código nem percebe.
Leia capabilities antes de assumir o que um canal faz.
Ignore campos e eventos desconhecidos, em vez de estourar.

A especificação sempre disponível em api.amivu.com.br/v1/openapi.json é a fonte para gerar cliente e diferenciar versões.

Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.