GuiasCancelar e substituir

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.

Requisição
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_emissao
    A nota foi emitida com dados errados e não será substituída.
  • servico_nao_prestado
    O serviço descrito na nota não aconteceu.
  • outros
    Qualquer outro caso. A justificativa precisa explicar o motivo.
Resposta · 200 OK
{  "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.

Requisição
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    }  }'
Resposta · 201 Created
{  "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_cancelada
    A nota já foi cancelada ou substituída. Consulte GET /nfse/{id} para ver o estado atual.
  • 409nfse_nao_autorizada
    Só notas autorizadas podem ser canceladas. Espere uma nota em processando terminar.
  • 422cancelamento_recusado
    A prefeitura não aceitou o pedido, em geral por prazo vencido. O motivo vem em erro.detalhes.

Prazo vencido na prefeitura

Quando o município não aceita mais o cancelamento eletrônico, o caminho é o processo administrativo na própria prefeitura. Até lá, a nota continua autorizada na API.