---
title: "Guia: cancelar e substituir NFS-e"
description: "Quando cancelar e quando substituir uma NFS-e autorizada pela API: motivos aceitos, requisições, eventos enviados e erros quando a prefeitura recusa o pedido."
url: https://docs.emissordenota.com/guias/cancelar-e-substituir
language: pt-BR
---
# 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?

| Situação | Use | Resultado |
| --- | --- | --- |
| O serviço não foi prestado ou a nota saiu em duplicidade | Cancelar | A nota fica cancelada e nenhuma outra é emitida. |
| Valor, descrição, tomador ou tributação saíram errados | Substituir | 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**

```bash
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."
  }'
```

| Motivo | Quando 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**

```json
{
  "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**

```bash
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**

```json
{
  "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

| Status | Código | O que fazer |
| --- | --- | --- |
| 409 | nfse_ja_cancelada | A nota já foi cancelada ou substituída. Consulte GET /nfse/{id} para ver o estado atual. |
| 409 | nfse_nao_autorizada | Só notas autorizadas podem ser canceladas. Espere uma nota em processando terminar. |
| 422 | cancelamento_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.
