XML do Evento de Cancelamento da NFS-e Nacional
Para quem é este comunicado: clientes que emitem e cancelam NFS-e no Ambiente Nacional (ADN) e precisam do comprovante fiscal do cancelamento, especialmente integrações via API.
O que muda no seu lado: nada quebra. Há uma nova capacidade — baixar o XML do evento de cancelamento por um endpoint dedicado.
Visão geral
A NFS-e do Ambiente Nacional passa a disponibilizar o XML do evento de cancelamento (e110001) — o documento fiscal que comprova oficialmente o cancelamento da nota. Esse XML agora é persistido e exposto por um endpoint próprio, separado do XML de emissão.
Antes, o cancelamento de uma NFS-e Nacional confirmava a operação, mas o cliente não tinha como obter o XML do evento. Esta versão fecha esse gap.
Por que
No Ambiente Nacional, o cancelamento segue o modelo da NF-e modelo 55: é um evento fiscal autônomo, com XML próprio vinculado à nota original. Pela LC 214/2025, esse evento é o documento que dá validade jurídica ao cancelamento. Disponibilizá-lo dá ao cliente o comprovante fiscal completo da operação.
Como funciona
Após o cancelamento ser concluído (status Cancelada), o XML do evento fica disponível por um endpoint dedicado:
curl -L "https://api.nfe.io/v1/companies/{companyId}/serviceinvoices/{id}/cancellation-xml" \
-H "X-NFe-Access-Token: sua_api_key" \
-o "nota-cancelamento.xml"
O endpoint redireciona (HTTP 302) para uma URL assinada com o XML. Quando existem o request enviado e o retorno autorizado do Ambiente Nacional, o retorno autorizado (procEventoNFSe) tem prioridade.
O XML do evento de cancelamento é armazenado separadamente e não sobrescreve o XML de emissão. GET /serviceinvoices/{id}/xml continua devolvendo a nota original; o cancelamento vem por /cancellation-xml.
O que mudou
- Novo endpoint:
GET /v1/companies/{companyId}/serviceinvoices/{id}/cancellation-xml. - Persistência dedicada: o XML do evento é guardado em chave própria, sem colidir com o XML de emissão.
- Prioridade do retorno autorizado: quando disponível, o
procEventoNFSeautorizado é priorizado sobre o request enviado.
Provedores legados (ABRASF, Paulistana, etc.) não geram XML de evento de cancelamento — é uma característica do padrão antigo. Para esses provedores, o endpoint retorna 404, sem regressão no comportamento existente.
Benefícios
- Comprovante fiscal completo: emissão e cancelamento, cada um com seu XML.
- Sem perda do documento original: os dois XMLs coexistem.
- Integração simples: um endpoint análogo ao download de XML que você já usa.
Detalhamento técnico
| Item | Comportamento |
|---|---|
| Endpoint | GET /v1/companies/{companyId}/serviceinvoices/{id}/cancellation-xml |
| Resposta de sucesso | HTTP 302 → URL assinada com o XML (application/xml) |
| Prioridade | Retorno autorizado (procEventoNFSe) sobre o request enviado |
| 404 — provedor legado | Padrão antigo não tem evento próprio de cancelamento |
| 404 — nota não cancelada | XML só existe após status = Cancelled |
| Webhook relacionado | invoice.cancelled_successfully ao concluir o cancelamento |
A consulta da nota (GET /serviceinvoices/{id}) não inclui esse XML no corpo — ele é acessível apenas pelo endpoint dedicado.
Próximos passos
- 📩 Compartilhe este comunicado com os devs que mantêm sua integração de NFS-e.
- 🧾 Se você emite no Ambiente Nacional, passe a arquivar o XML de cancelamento junto com o de emissão.
- 🧪 Cancele uma NFS-e Nacional de teste e baixe o XML pelo novo endpoint — siga o passo a passo.
- 💬 Dúvidas: nosso canal de suporte e o time de Customer Success estão prontos para ajudar.
FAQ
O endpoint funciona para qualquer prefeitura? Não. Apenas para notas do Ambiente Nacional. Provedores legados (ABRASF, Paulistana, etc.) retornam 404.
O XML de emissão foi afetado?
Não. O XML de cancelamento é armazenado separadamente; GET /xml continua igual.
Quando o XML fica disponível? Somente após o cancelamento concluir e a nota assumir o status Cancelada. Antes disso, o endpoint retorna 404.
Preciso guardar esse XML? Sim. É documento fiscal; mantenha pelo prazo legal mínimo de 5 anos, junto com o XML de emissão.
Em resumo:
- Nova capacidade: baixe o XML do evento de cancelamento (
e110001) da NFS-e Nacional porGET /serviceinvoices/{id}/cancellation-xml.- Sem quebra: o XML de emissão não é sobrescrito; provedores legados seguem como antes (404 no novo endpoint).
- Disponível após
Cancelled— e priorizando o retorno autorizado do Ambiente Nacional.