Cancelamento de DC-e

DELETE /v1/subscriptions/{subscriptionId}/taxpayers/{taxpayerId}/contentdeclarations/{id}

Solicita o cancelamento de uma DC-e autorizada, com justificativa.

Corpo do pedido

{
  "reason": "Cancelamento por erro na descricao dos itens declarados"
}

reason é obrigatório, de 15 a 255 caracteres — fora disso, 400.

204 significa "pedido aceito", não "cancelada"

O cancelamento é transmitido à SEFAZ de forma assíncrona. O 204 diz que o pedido passou na validação de entrada e foi enfileirado — o desfecho vem depois.

Confirme o resultado de uma das duas formas:

• GET {id} — quando o cancelamento é homologado, status vira Cancelled
• GET {id}/events — aparecem os eventos CancelRequested, Cancelled ou CancelRejected, com o cStat da SEFAZ

Não trate 204 como confirmação de cancelamento

Um 204 seguido de CancelRejected no histórico é um cenário real e esperado — o pedido foi aceito pela API, mas a SEFAZ recusou o cancelamento em si. Trate o status/histórico como fonte da verdade, não o código HTTP da chamada de cancelamento.

Duas regras que só a SEFAZ responde

Não viram erro no 204 — a SEFAZ é quem decide, depois:

• Prazo de 24 horas, contado da autorização — fora dele, o cancelamento é rejeitado
• O documento tem que estar autorizado — cancelar o que não autorizou é rejeitado

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 (formato de ETag fraca, W/"3", ou o número puro 3) faz o cancelamento falhar com 412 se o documento mudou desde a sua leitura. 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	Justificativa fora do limite de 15 a 255 caracteres (xJust, regra L-XJUST)
401	Token ausente, expirado, com audiência errada, ou chave de API no lugar de JWT
403	Token válido mas sem o escopo/papel da operação, ou a assinatura da URL não é do token nem acessível ao usuário (type termina em subscription-scope-undetermined)
404	Documento inexistente, ou fora da assinatura da URL
409	O documento já está cancelado
412	O If-Match enviado não corresponde à versão atual do documento — releia o documento e tente de novo

400 — justificativa fora do limite (application/problem+json)

{
  "status": 400,
  "errors": [
    { "name": "reason", "reason": "xJust must be between 15 and 255 characters long.", "rule": "L-XJUST" }
  ]
}

Veja também

• Como consultar uma DC-e
• Emitir uma DC-e