Versão de API e quebra de compatibilidade: o que acontece quando a consolidadora muda o contrato sem avisar

Quando o problema não está no seu código

Uma integração que funcionava normalmente e, de repente, começa a falhar ou a retornar dado diferente do esperado, sem nenhuma alteração recente do lado de quem consome a API, costuma ter uma causa externa: a consolidadora publicou uma nova versão da própria API, e algo que antes funcionava de um jeito, agora funciona de outro.

O que costuma mudar entre versões

• Um campo que existia deixa de existir, ou passa a ter outro nome;
• O formato de um valor muda — de texto pra número, de um padrão de data pra outro;
• Um comportamento que antes era opcional passa a ser obrigatório, ou vice-versa.

Quebra de compatibilidade x evolução compatível

Uma mudança bem planejada geralmente é aditiva — adiciona campo novo sem remover ou alterar o que já existia, o que não quebra nada do lado de quem já integra. Uma quebra de compatibilidade acontece quando algo que já existia muda de forma incompatível com o que estava documentado antes, exigindo ajuste imediato pra continuar funcionando.

Por que nem toda consolidadora avisa com antecedência

Idealmente, uma mudança de versão vem acompanhada de aviso prévio, com prazo de transição pra quem consome a API se ajustar. Na prática, isso nem sempre acontece de forma clara ou com antecedência suficiente, o que exige de quem integra um mecanismo próprio pra perceber a mudança rápido, mesmo sem aviso formal.

Como perceber a quebra rápido, mesmo sem aviso

Monitorar a estrutura do dado retornado, não só se a chamada teve sucesso ou falha, ajuda a identificar quando um campo esperado deixou de vir, ou veio num formato diferente — um sinal de que algo mudou do outro lado, mesmo que a chamada em si não tenha retornado erro nenhum.

Fixar a versão da API, quando possível

Algumas consolidadoras permitem que quem integra especifique explicitamente qual versão da API deseja usar, mesmo que uma versão mais nova já exista. Isso dá controle sobre quando migrar, em vez de ser forçado a se adaptar no momento em que a consolidadora decide desativar a versão anterior.