Cancelamento de DC-e
DELETE /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}
Solicita o cancelamento de uma DC-e autorizada, com justificativa.
{
"reason": "Cancelamento por erro na descricao dos itens declarados"
}
reason é obrigatório e precisa ter de 15 a 255 caracteres, contados depois de remover os espaços do início e do fim. Sem reason, a resposta é 400; fora do limite, 422 com a regra L-XJUST.
O que é recusado na hora
Antes de enviar o pedido à SEFAZ, a API confere o que o estado do documento já decide. Essas recusas voltam na própria resposta do DELETE, e nada é enviado:
| Situação | Resposta |
|---|---|
| O documento não está autorizado (ainda em processamento, rejeitado, recusado) | 409, type terminado em document-not-authorized |
| O documento já está cancelado | 409, type terminado em document-already-cancelled |
| Passaram-se mais de 24 horas desde a autorização | 422, type terminado em cancellation-not-allowed, regra 2P12-14 |
| O horário de autorização ou de emissão do documento está à frente do relógio atual (mais de 5 minutos) | 422, type terminado em cancellation-not-allowed, regra 2P13-14 ou 2P13-10 — tente de novo em alguns minutos |
A janela de 24 horas é contada a partir do horário de autorização informado pela SEFAZ.
204 significa "pedido aceito", não "cancelada"
O cancelamento é transmitido à SEFAZ de forma assíncrona. O 204 diz que o pedido passou nas verificações acima e foi enviado para processamento — o desfecho vem depois.
Confirme o resultado de uma das duas formas:
GET {id}— quando o cancelamento é homologado,statusviraCancelled; o código e o motivo da SEFAZ ficam emcancellationCStatecancellationReasonGET {id}/events— aparecem os eventosCancelRequested,CancelledouCancelRejected, com ocStatda SEFAZ
Um 204 seguido de CancelRejected no histórico é um cenário possível — o pedido foi aceito pela API, mas a SEFAZ recusou o cancelamento em si. Trate o status e o histórico como fonte da verdade, não o código HTTP da chamada de cancelamento.
Concorrência (If-Match)
DELETE /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}
If-Match: W/"3"
If-Match com a versão esperada do documento faz o cancelamento falhar com 412 se o documento mudou desde a sua leitura. O valor é o do cabeçalho ETag da resposta de GET {id} — no formato de ETag fraca, W/"3". Sem o cabeçalho, não há pré-condição — o pedido segue mesmo que o documento tenha mudado.
Erros
| Código | O que significa |
|---|---|
400 | reason ausente (reason is required.) |
401 | Token ausente, inválido ou expirado — peça um novo token (veja Autenticação) |
403 | A assinatura da URL não é a do token nem uma que o usuário acessa (type termina em subscription-scope-undetermined) |
404 | Empresa da URL inexistente ou fora da assinatura (type termina em company-not-in-subscription), ou documento inexistente nessa empresa |
409 | O documento não está autorizado (document-not-authorized) ou já está cancelado (document-already-cancelled) |
412 | O If-Match enviado não corresponde à versão atual do documento — releia o documento e tente de novo |
422 | Justificativa fora de 15 a 255 caracteres (regra L-XJUST), ou cancelamento não permitido pelo estado do documento (cancellation-not-allowed, por exemplo a janela de 24 horas vencida) |
503 | Não deu para verificar agora a titularidade da empresa (company-ownership-unverified). Nada foi enviado — tente de novo |
As mensagens de erro (title, detail, errors[].reason) vêm em inglês. O motivo da SEFAZ, em cancellationReason e nos eventos, vem em português, como ela respondeu.
{
"type": "https://docs.nfe.io/errors/dce/validation-failed",
"status": 422,
"errors": [
{ "name": "reason", "reason": "reason must be between 15 and 255 characters.", "rule": "L-XJUST" }
]
}
{
"type": "https://docs.nfe.io/errors/dce/cancellation-not-allowed",
"title": "The document cannot be cancelled.",
"status": 422,
"errors": [
{ "reason": "The cancellation window of 24 hours after authorization has passed (authorized at 2026-08-19T13:04:19.0000000+00:00).", "rule": "2P12-14" }
]
}