Cancelar uma NFe

O cancelamento de NFe é regulamentado pela SEFAZ: precisa ser feito dentro do prazo legal (geralmente 24 horas após a autorização) e exige uma justificativa de 15 a 255 caracteres.

Pré-requisitos

A NFe deve estar autorizada (status: "004").
Você deve ter a chave de acesso (44 caracteres) da NFe.
O cancelamento deve estar dentro do prazo SEFAZ.

Fluxo

Enviar o cancelamento

curl -X POST $BASE/nfe/cancelamento \
  -H "Authorization: Token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chave": "35260512345678000199550010000000011000000010",
    "motivo": "Cancelamento solicitado pelo cliente — pedido refeito."
  }'

Resposta:

{
  "status": "001",
  "descricao": "Evento registrado com sucesso.",
  "data": { "recibo": "rec_cancel_001" }
}

Consultar o resultado

Polling com intervalo mínimo de 2 segundos:

curl $BASE/nfe/cancelamento/rec_cancel_001 \
  -H "Authorization: Token $TOKEN"

Quando aprovado pela SEFAZ:

{
  "status": "010",
  "descricao": "A nota está cancelada.",
  "data": { ... }
}

(Opcional) Confirmar via consulta da nota original
Terminal window
```
curl $BASE/nfe/nota/{recibo_emissao_original}/completa \
  -H "Authorization: Token $TOKEN"
```
A nota agora retorna status: "010".

Regras do `motivo`

Regra	Valor
Tamanho mínimo	15 caracteres
Tamanho máximo	255 caracteres
Quebras de linha	São substituídas por espaço

Exemplos de motivos válidos

✅ "Cancelamento solicitado pelo cliente — pedido 12345 refeito."
✅ "Erro de valor no item 2; nova nota emitida com correção."
✅ "Duplicidade detectada após retry; nota original mantida."

Motivos a evitar

❌ "Cancelar" (curto demais — viola limite mínimo de 15 chars)
❌ "Teste" (curto e suspeito)
❌ "Erro" (sem contexto)

Erros comuns

Mensagem	Causa
`Campo nfe@chave deve ter 44 caracteres.`	Chave incorreta ou incompleta
`Campo nfe@motivo deve ter entre 15 e 255 caracteres.`	Texto fora do tamanho permitido
`status: "900"` (rejeição SEFAZ)	Prazo de cancelamento expirado; ou nota não pertence à sua empresa

Fora do prazo SEFAZ?

Se o prazo expirou (varia por estado, geralmente 24h):

A SEFAZ rejeitará o cancelamento (status: "900").
Você precisará fazer uma nota de devolução (NFe finalidade: "D" referenciando a original).
Consulte seu contador para o procedimento correto na sua UF.

E para NFCe e NFSe?

Documento	Endpoint	Notas
NFe	`POST /nfe/cancelamento`	Prazo SEFAZ ~24h
NFCe	`POST /nfce/cancelamento`	Prazo geralmente menor (alguns minutos)
NFSe	`POST /nfse/cancelamento`	Regras municipais variam

O formato do body é o mesmo (chave + motivo) para os três.