Como obter o XML do evento de cancelamento

Quando você cancela uma NFS-e do Ambiente Nacional, o cancelamento gera um documento fiscal próprio: o XML do evento de cancelamento (e110001). Este guia mostra como baixá-lo pela API, do cancelamento ao download. Para entender o conceito por trás, veja Evento de cancelamento da NFS-e Nacional.

Pré-requisitos

• Uma NFS-e emitida no Ambiente Nacional (provedores legados não geram esse XML).
• Sua API Key no header X-NFe-Access-Token.
• O companyId da empresa emissora e o id da nota a cancelar.

Solução

O fluxo tem três passos: solicitar o cancelamento, aguardar a nota assumir o status Cancelled e então baixar o XML pelo endpoint dedicado.

Etapa 1: Solicitar o cancelamento

O cancelamento é assíncrono. A API responde de imediato, mas o processamento ocorre em background.

curl -X DELETE "https://api.nfe.io/v1/companies/{companyId}/serviceinvoices/{id}" \
  -H "X-NFe-Access-Token: sua_api_key"

Etapa 2: Aguardar o status Cancelled

Acompanhe o status da nota por consulta ou, preferencialmente, por webhook (invoice.cancelled_successfully). O XML do evento só fica disponível depois que o status vira Cancelled.

curl "https://api.nfe.io/v1/companies/{companyId}/serviceinvoices/{id}" \
  -H "X-NFe-Access-Token: sua_api_key"

Etapa 3: Baixar o XML do evento de cancelamento

Chame o endpoint dedicado. Ele redireciona (HTTP 302) para uma URL assinada com o XML do evento.

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"

Quando existem o request enviado e o retorno autorizado do Ambiente Nacional, o endpoint prioriza o retorno autorizado (procEventoNFSe). O XML do evento é armazenado separadamente e não sobrescreve o XML de emissão (/xml).

Variações

• Baixar o XML de emissão (original): use GET /serviceinvoices/{id}/xml. É um documento diferente do cancelamento — guarde os dois.
• Notificação por webhook: em vez de consultar em loop, assine o evento invoice.cancelled_successfully e baixe o XML quando a notificação chegar.

Armadilhas comuns

• HTTP 404 em provedor legado: ABRASF, Paulistana e similares não geram XML de evento de cancelamento. O endpoint retorna 404 por design — não é erro de integração.
• HTTP 404 antes de cancelar: se a nota ainda não está Cancelled (ex.: cancelamento em processamento), o XML ainda não existe. Aguarde a conclusão.
• Procurar o XML na consulta da nota: o XML do evento não aparece no corpo do GET /serviceinvoices/{id}. Ele é acessível somente pelo endpoint cancellation-xml.
• Confundir com o XML de emissão: baixar /xml traz a nota original, não o cancelamento. Use /cancellation-xml para o comprovante de cancelamento.

Veja também

• Evento de cancelamento da NFS-e Nacional
• Referência da API REST — Nota Fiscal de Serviço