VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/NF-e (nota fiscal)

Cancelar, corrigir e inutilizar

Cancela uma nota, envia carta de correção e inutiliza uma faixa de números não usados.

Depois de autorizada, uma NF-e não pode ser editada. Estas rotas cobrem as três saídas permitidas pela SEFAZ: cancelar (até 24 horas), corrigir o texto com uma carta de correção, e inutilizar números que ficaram sem nota.

Cancelar uma nota

POST/api/v1/admin/nfe/{id}/cancelAdmin

Cancela uma NF-e

Parâmetros de caminho

iduuidobrigatório
Id interno da nota.

Corpo da requisição

justificationstringobrigatório
Motivo, de 15 a 255 caracteres.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/nfe/b7a76302-e926-4988-a015-789e8f225c60/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "justification": "Venda cancelada a pedido do cliente."
  }'

Resposta

200Nota cancelada
json
{
  "id": "b7a76302-e926-4988-a015-789e8f225c60",
  "order_id": "608a3291-6064-44a2-b352-5816d0471469",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "ref": "VENDDOR_608A3291",
  "status": "cancelado",
  "serie": "1",
  "created_at": "2026-10-11T14:00:00Z",
  "updated_at": "2026-10-11T14:00:00Z",
  "chave_nfe": "35261012345678000199550010000001241234567891",
  "numero": "124",
  "xml_url": "/files/nfe/124.xml",
  "danfe_url": "/files/nfe/124.pdf",
  "issued_at": "2026-10-11T14:00:20Z",
  "items": [
    {
      "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "nfe_id": "b7a76302-e926-4988-a015-789e8f225c60",
      "description": "Camiseta Básica Preta M",
      "ncm_code": "61091000",
      "cfop_code": "5102",
      "quantity": 2,
      "unit_value": 4990,
      "total_value": 9980,
      "icms_base": 9980,
      "icms_rate": 1800,
      "icms_value": 1796,
      "icms_cst": "00",
      "icms_csosn": "",
      "ipi_rate": 0,
      "ipi_value": 0,
      "ipi_cst": "",
      "pis_rate": 165,
      "pis_value": 165,
      "pis_cst": "01",
      "cofins_rate": 760,
      "cofins_value": 758,
      "cofins_cst": "01",
      "created_at": "2026-10-11T14:00:00Z"
    }
  ],
  "cancel_reason": "Venda cancelada a pedido do cliente.",
  "canceled_at": "2026-10-11T15:00:00Z"
}

Campos da resposta

iduuid
Id interno da nota.
order_iduuid
Pedido.
vendor_iduuid
Seller da nota; ausente na nota do marketplace.
refstring
Referência única enviada à FocusNFe.
statusstring
processandoautorizadoerrodenegadocancelado
processando, autorizado, erro, denegado ou cancelado.
chave_nfestring
Chave de acesso de 44 dígitos. Só após autorizar.
numerostring
Número da nota na série.
seriestring
Série.
xml_urlstring
Caminho do XML na FocusNFe. Só após autorizar.
danfe_urlstring
Caminho do DANFE. Só após autorizar.
error_msgstring
Códigos de rejeição da SEFAZ concatenados. Só em erro.
error_messagestring
Motivo legível da rejeição. Só em erro.
cancel_reasonstring
Justificativa do cancelamento.
canceled_atstring
Quando foi cancelada (RFC 3339).
issued_atstring
Quando foi autorizada (RFC 3339).
created_atstring
Criação.
updated_atstring
Última atualização (webhook ou consulta).
itemsarray
Itens com a tabela de impostos (ncm_code, cfop_code, quantity, unit_value, total_value, icms_*, ipi_*, pis_*, cofins_*). Valores em centavos, alíquotas em pontos-base. Só no detalhe (GET por id).

Erros

StatusQuandoCorpo de exemplo
400Justificativa ausente ou fora de 15 a 255 caracteres.{"error":"justification must be between 15 and 255 characters","detail":"..."}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_nfe nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]}
403O módulo focusnfe está desligado na loja.{"error":"module_disabled","module":"focusnfe"}
404Nota inexistente.{"error":"NF-e not found"}
409Nota já cancelada, ou em status que não permite cancelar.{"error":"NF-e is already canceled"}
422Provedor fiscal sem configuração.{"error":"fiscal provider is not configured"}
502Provedor inacessível, ou recusou (por exemplo, prazo de 24 h vencido). A mensagem é a do provedor, em português.{"error":"fiscal provider is unreachable","detail":"..."}
Cancelar uma nota não cancela o pedido

A rota só desfaz o documento fiscal. O status do pedido e o estorno do pagamento seguem os fluxos do pedido.

Cancelar pela rota antiga

Mesma regra do cancelamento acima, mantida por compatibilidade. A diferença é a resposta: 204 sem corpo, em vez da nota atualizada. Mesmo sendo DELETE, exige corpo JSON com a justificativa. Em integrações novas prefira o POST .../cancel.

DELETE/api/v1/admin/nfe/{id}Admin

Cancela uma NF-e (rota antiga)

Parâmetros de caminho

iduuidobrigatório
Id interno da nota.

Corpo da requisição

justificationstringobrigatório
Motivo, de 15 a 255 caracteres.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/nfe/b7a76302-e926-4988-a015-789e8f225c60" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "justification": "Venda cancelada a pedido do cliente."
  }'

Resposta

204Cancelada (sem corpo)

Resposta vazia.

Erros

StatusQuandoCorpo de exemplo
400Justificativa ausente ou fora de 15 a 255 caracteres, ou corpo vazio.{"error":"justification is required (15-255 characters)"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_nfe nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]}
403O módulo focusnfe está desligado na loja.{"error":"module_disabled","module":"focusnfe"}
404Nota inexistente.{"error":"NF-e not found"}
409Já cancelada ou sem condição de cancelar.{"error":"NF-e cannot be canceled in its current status"}
502Provedor inacessível ou recusou.{"error":"fiscal provider is unreachable"}

Enviar carta de correção (CC-e)

A CC-e corrige informações de texto de uma nota autorizada (por exemplo, dados adicionais). Nunca corrige valores, impostos, quantidades ou o destinatário. Cada nota aceita até 20 cartas.

POST/api/v1/admin/nfe/{id}/cceAdmin

Envia uma carta de correção

Parâmetros de caminho

iduuidobrigatório
Id interno da nota.

Corpo da requisição

correcaostringobrigatório
Texto da correção, de 15 a 1000 caracteres.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/nfe/b7a76302-e926-4988-a015-789e8f225c60/cce" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "correcao": "Onde se lê transportadora Alfa, leia-se transportadora Beta, conforme romaneio."
  }'

Resposta

200Carta registrada
json
{
  "id": "2d3e4f5a-6b7c-4d8e-9f01-a2b3c4d5e6f7",
  "nfe_id": "b7a76302-e926-4988-a015-789e8f225c60",
  "ref": "VENDDOR_608A3291",
  "sequence_number": 1,
  "correcao": "Onde se lê transportadora Alfa, leia-se transportadora Beta, conforme romaneio.",
  "status": "autorizado",
  "protocol_number": "135260000000001",
  "created_at": "2026-10-11T15:10:00Z"
}

Campos da resposta

sequence_numberinteger
Número da carta (1 a 20).
statusstring
Resultado devolvido pela FocusNFe.
protocol_numberstring
Protocolo da SEFAZ.
error_msgstring
Erro, quando rejeitada.
iduuid
Id da carta.
nfe_iduuid
Nota corrigida.
correcaostring
Texto enviado.

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_nfe nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]}
403O módulo focusnfe está desligado na loja.{"error":"module_disabled","module":"focusnfe"}
422Texto fora de 15 a 1000 caracteres, nota que não está autorizado, limite de 20 cartas atingido ou falha do provedor.{"error":"texto da correção deve ter entre 15 e 1000 caracteres"}

Inutilizar números

Declara à SEFAZ que a faixa de números de uma série não será usada. Use somente para números que não viraram nota autorizada.

POST/api/v1/admin/nfe/inutilizeAdmin

Inutiliza uma faixa de números

Corpo da requisição

seriestringobrigatório
Série, normalmente 1.
number_startintegerobrigatório
Primeiro número, positivo.
number_endintegerobrigatório
Último número, maior ou igual ao primeiro.
justificationstringobrigatório
Motivo, de 15 a 255 caracteres.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/nfe/inutilize" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serie": "1",
    "number_start": 100,
    "number_end": 105,
    "justification": "Numeracao pulada por erro de sistema."
  }'

Resposta

201Faixa inutilizada
json
{
  "id": "3e4f5a6b-7c8d-4e9f-a012-b3c4d5e6f708",
  "serie": "1",
  "number_start": 100,
  "number_end": 105,
  "justification": "Numeracao pulada por erro de sistema.",
  "status": "autorizado",
  "protocol_number": "135260000000002",
  "created_at": "2026-10-11T15:20:00Z",
  "updated_at": "2026-10-11T15:20:00Z"
}

Campos da resposta

statusstring
Resultado da SEFAZ via FocusNFe.
protocol_numberstring
Protocolo.
error_msgstring
Erro, quando recusada.

Erros

StatusQuandoCorpo de exemplo
400serie vazia, números não positivos, início maior que o fim ou justificativa ausente.{"error":"number_start must be <= number_end"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_nfe nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]}
403O módulo focusnfe está desligado na loja.{"error":"module_disabled","module":"focusnfe"}
500Justificativa fora de 15 a 255 caracteres, ou falha do provedor.{"error":"failed to inutilize NF-e range","detail":"justification must be between 15 and 255 characters (got 4)"}
Irreversível

Números inutilizados não podem ser usados depois. Confira a faixa antes de enviar.

Justificativa curta volta 500

Diferente do cancelamento, o tamanho da justificativa aqui é conferido só no serviço e aparece como 500, não 400.

Veja também

  • NF-e
Anterior
Arquivos da NF-e (XML e DANFE)
Próxima
Impostos (ICMS, ISS, IPI)
Nesta página
  • Cancelar uma nota
  • Exemplo de requisição
  • Resposta
  • Erros
  • Cancelar pela rota antiga
  • Exemplo de requisição
  • Resposta
  • Erros
  • Enviar carta de correção (CC-e)
  • Exemplo de requisição
  • Resposta
  • Erros
  • Inutilizar números
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também