Versionamento e depreciação

A API é versionada pelo caminho. A versão atual é a v1: https://emitra.com.br/api/v1/integracao. Uma integração escrita hoje continua funcionando enquanto a v1 existir.

O que pode mudar sem nova versão#

Estas mudanças são consideradas compatíveis e podem chegar a qualquer momento na v1:

• novos recursos, rotas e parâmetros opcionais;
• novos campos nas respostas;
• novos valores em campos de lista aberta, como rejeicao.codigo ou code de erro;
• novos tipos de evento de webhook (você só recebe os eventos em que se inscreveu);
• mudanças no texto de message e de orientacao.

O que exige nova versão#

• remover ou renomear um campo, rota ou parâmetro;
• mudar o tipo de um campo (ex.: string para número);
• tornar obrigatório um parâmetro que era opcional;
• mudar o significado de um valor existente.

Quando isso for necessário, a mudança sai numa nova versão (/v2), e a v1 continua no ar durante o período de depreciação.

Política de depreciação#

1. A depreciação é anunciada no changelog.
2. As respostas da rota depreciada passam a trazer o header Sunset com a data de desligamento.
3. A rota fica no ar por pelo menos 6 meses depois do anúncio.

HTTP/1.1 200 OK
Sunset: Tue, 11 May 2027 23:59:59 GMT

Leiaute fiscal × versão da API#

A versão da API é independente da versão do leiaute da NFS-e. Quando a Sefin publica uma nota técnica (por exemplo, um novo campo de IBS/CBS), a Emitra atualiza a montagem da DPS sem mudar a v1. Campos fiscais novos entram como opcionais.

Se uma nota técnica tornar um dado obrigatório, você verá a rejeição correspondente da Sefin com orientação, e o changelog explicará o campo novo.

Como acompanhar#

• Changelog da API: toda mudança, compatível ou não.
• openapi.json: o contrato formal, sempre da versão publicada.
• Monitore o header Sunset nos seus logs e crie um alerta quando ele aparecer.

Próximos passos#

• Changelog
• Visão geral da API