Cancelar e substituir
Uma nota autorizada não pode ser editada. Para corrigir um erro, você cancela a nota ou emite outra que a substitui. Este guia mostra quando usar cada caminho e como acompanhar o resultado.
Cancelar ou substituir?
- O serviço não foi prestado ou a nota saiu em duplicidade
- Use
- Cancelar
- Resultado
- A nota fica cancelada e nenhuma outra é emitida.
- Valor, descrição, tomador ou tributação saíram errados
- Use
- Substituir
- Resultado
- A nova nota é autorizada e a original é cancelada na mesma operação.
Prazos e motivos aceitos são definidos pela prefeitura de cada município. Quando ela recusa o pedido, a API devolve o motivo e a nota continua autorizada.
Cancelar uma nota
Envie o motivo e uma justificativa de pelo menos 15 caracteres. A justificativa é transmitida à prefeitura junto com o pedido.
curl -X POST https://api.emissordenota.com/v1/nfse/nfse_3Jt9wPz7Qa/cancelar \ -H "Authorization: Bearer $EDN_KEY" \ -H "Idempotency-Key: cancelar-fatura-0042" \ -H "Content-Type: application/json" \ -d '{ "motivo": "servico_nao_prestado", "justificativa": "Contrato encerrado antes do início do serviço." }'MotivoQuando usar
- erro_na_emissaoA nota foi emitida com dados errados e não será substituída.
- servico_nao_prestadoO serviço descrito na nota não aconteceu.
- outrosQualquer outro caso. A justificativa precisa explicar o motivo.
{ "id": "nfse_3Jt9wPz7Qa", "status": "cancelada", "cancelamento": { "motivo": "servico_nao_prestado", "justificativa": "Contrato encerrado antes do início do serviço.", "cancelada_em": "2026-11-10T09:15:02-03:00" }}Quando a prefeitura demora a responder, a nota volta ainda como autorizada, com cancelamento.status igual a processando. O evento nfse.cancelada avisa quando o cancelamento for confirmado.
Substituir uma nota
Envie os dados completos da nova nota, como em uma emissão, mais a justificativa. O empresa_id não entra no corpo: a nova nota é sempre da mesma empresa da original.
curl -X POST https://api.emissordenota.com/v1/nfse/nfse_3Jt9wPz7Qa/substituir \ -H "Authorization: Bearer $EDN_KEY" \ -H "Idempotency-Key: substituir-fatura-0042" \ -H "Content-Type: application/json" \ -d '{ "justificativa": "Valor do serviço informado a menor.", "data_competencia": "2026-11-09", "tomador": { "documento": "98765432000198", "nome": "Clínica Bem Viver Ltda" }, "servico": { "codigo_tributacao_nacional": "010701", "descricao": "Suporte técnico em informática - novembro/2026", "valor": 1800.00 } }'{ "id": "nfse_9Lm4tXc2Hb", "status": "processando", "substitui": "nfse_3Jt9wPz7Qa", "valor": 1800.00}Quando a nova nota é autorizada, a original passa para cancelada e ganha o campo substituida_por. Você recebe dois eventos: nfse.autorizada para a nova e nfse.cancelada para a original. Se a nova nota for rejeitada, a original continua autorizada e nada muda.
Quando o pedido é recusado
StatusCódigoO que fazer
- 409nfse_ja_canceladaA nota já foi cancelada ou substituída. Consulte GET /nfse/{id} para ver o estado atual.
- 409nfse_nao_autorizadaSó notas autorizadas podem ser canceladas. Espere uma nota em processando terminar.
- 422cancelamento_recusadoA prefeitura não aceitou o pedido, em geral por prazo vencido. O motivo vem em erro.detalhes.
Prazo vencido na prefeitura