Versionamento de API

O que é versionamento de API?

Uma API é uma espécie de contrato: ela define quais endereços existem, quais dados devem ser enviados e o que será devolvido. Quando esse contrato muda, os sistemas que dependem dele podem parar de funcionar. O versionamento de API é a forma de controlar essas mudanças, dando um nome ou número a cada conjunto de regras, como v1, v2 e assim por diante.

Assim, quem já está integrado pode continuar usando a versão antiga enquanto se prepara para migrar, e quem está começando pode adotar diretamente a versão mais nova.

Para que serve o versionamento em uma API fiscal?

Em uma API fiscal, as mudanças são frequentes. Notas técnicas alteram leiautes, novos campos surgem, como os grupos de IBS e CBS da reforma tributária, e o Padrão Nacional da NFS-e muda a forma de emitir notas de serviço em muitos municípios. O versionamento permite que o fornecedor incorpore essas novidades sem obrigar todos os clientes a reescrever a integração no mesmo dia.

Para um ERP ou marketplace que emite milhares de notas, isso significa previsibilidade: a emissão continua funcionando, e a adaptação pode ser planejada, testada no ambiente de homologação e só depois levada ao ambiente de produção.

Como funciona o versionamento na prática?

A forma mais comum é colocar a versão no próprio endereço do endpoint, como em /v1/nfe ou /v2/nfse. Outras abordagens usam um header da requisição ou um query parameter para indicar qual versão o sistema quer usar. Em todos os casos, o servidor recebe a chamada e aplica as regras daquela versão específica.

Muitos fornecedores também adotam o versionamento semântico, com números como 2.1.3, em que o primeiro número indica mudanças que quebram compatibilidade, o segundo indica novidades compatíveis e o terceiro indica correções.

Qual a diferença entre mudança compatível e mudança que quebra a integração?

Uma mudança compatível é aquela que não afeta quem já está integrado, como adicionar um campo opcional no payload ou um novo campo na resposta. Esse tipo de alteração normalmente pode entrar na versão atual.

Uma mudança que quebra a integração, chamada em inglês de breaking change, exige ajuste do lado do cliente. Exemplos: remover um campo, renomear um atributo, tornar obrigatório algo que era opcional ou mudar o formato de uma data. Essas mudanças costumam justificar uma nova versão principal da API.

O que acontece quando uma versão de API é descontinuada?

Versões antigas não ficam disponíveis para sempre. O processo comum é anunciar a descontinuação (deprecation) com antecedência, manter a versão funcionando por um período de transição e só então desligá-la. Durante esse tempo, a documentação, muitas vezes publicada em OpenAPI, indica o que mudou e como migrar.

Para quem integra, é importante acompanhar os comunicados do fornecedor, registrar nos logs qual versão está em uso e testar a nova versão em homologação antes da data limite.

Versionamento de API é o mesmo que versão do leiaute fiscal?

Não. A versão do leiaute fiscal é definida pelos órgãos autorizadores, como a SEFAZ ou o padrão nacional da NFS-e, e descreve o formato do XML do documento. Já o versionamento de API é definido pelo fornecedor da API e descreve o formato das requisições e respostas em JSON entre o sistema do cliente e a plataforma.

Uma boa API fiscal consegue absorver mudanças de leiaute sem obrigar o cliente a trocar de versão da API sempre que possível, convertendo os dados internamente para o formato exigido pelo órgão.

Exemplos de Versionamento de API

• Um ERP integrado envia notas para o endpoint /v1/nfe. O fornecedor lança a /v2/nfe com novos campos da reforma tributária, e o ERP continua emitindo pela v1 enquanto testa a v2 em homologação.
• Uma plataforma de venda adiciona um campo opcional de observações na resposta da API sem criar nova versão, pois a mudança não quebra integrações existentes.
• Um marketplace recebe aviso de que a v1 da API de NFS-e será descontinuada e usa o período de transição para adaptar o payload ao formato da v2.
• Uma equipe de desenvolvimento registra no log de integração a versão da API usada em cada requisição para facilitar a investigação de rejeições após uma migração.