Consultar a nota e eventos fiscais#

Depois de emitir, tudo se faz pela ref. Os eventos fiscais (cancelamento, carta de correção, inutilização) dependem da SEFAZ e por isso são assíncronos: respondem 202 e o resultado aparece em eventos da nota (e chega por webhook).

Em todas as rotas de /nfe/{ref}, quem tem mais de uma empresa informa ?cnpj_emitente= (na query; no POST/DELETE também vale no corpo). Os links devolvidos pela API (caminho_*) já levam o cnpj_emitente.

Consultar#

GET /nfe/{ref} devolve a nota no mesmo formato da emissão (veja A resposta da nota). 404 nota_nao_encontrada se não houver nota com essa ref na empresa e no ambiente atual.

Acompanhando uma emissão por consulta, repita até o status ser final (autorizado, cancelado, denegado, inutilizado) ou ficar em erro_autorizacao/erro_validacao, que esperam uma correção sua. Comece a cada 2 segundos e aumente (veja boas práticas).

XML e DANFE#

• XML (GET /nfe/{ref}/xml): o documento fiscal, com o protocolo da SEFAZ. Responde application/xml. Disponível enquanto a nota está autorizado e depois de cancelado: a legislação obriga a guardar o XML autorizado e o do cancelamento por 5 anos. Antes da autorização, 404.
• DANFE (GET /nfe/{ref}/danfe): o PDF para impressão ou envio ao cliente. Disponível só enquanto a nota está autorizado.

Guarde o XML no seu sistema assim que a nota for autorizada. Não dependa de buscá-lo só quando alguém pedir.

Cancelar#

DELETE /nfe/{ref} pede o cancelamento de uma nota autorizada. O corpo:

{ "justificativa": "Cliente desistiu da compra antes do envio", "confirmo": true }

Resposta 202: a nota continua autorizado até a SEFAZ registrar; o pedido aparece em eventos com status: "processando":

{
  "ref": "PED-1002", "status": "autorizado", "numero": "2", "chave_nfe": "35261011222333000181550010000000021219954665",
  "eventos": [
    { "id": 1, "tipo": "cancelamento", "sequencia": 1, "status": "processando", "texto": "Cliente desistiu da compra antes do envio",
      "protocolo_sefaz": null, "status_sefaz": null, "mensagem_sefaz": null, "solicitado_em": "2026-10-04T15:50:11+00:00", "caminho_xml": null }
  ]
}

Quando a SEFAZ registra, a nota vira cancelado e o evento registrado, já com o protocolo e o link do XML do evento:

{
  "ref": "PED-1002", "status": "cancelado",
  "caminho_xml_nota_fiscal": "https://srv1839254.hstgr.cloud/api/v2/nfe/PED-1002/xml?cnpj_emitente=11222333000181", "caminho_danfe": null,
  "eventos": [
    { "id": 1, "tipo": "cancelamento", "sequencia": 1, "status": "registrado", "texto": "Cliente desistiu da compra antes do envio",
      "protocolo_sefaz": "135000000000001", "status_sefaz": "135", "mensagem_sefaz": "Evento registrado e vinculado a NF-e",
      "solicitado_em": "2026-10-04T15:50:11+00:00", "caminho_xml": "https://srv1839254.hstgr.cloud/api/v2/nfe/PED-1002/eventos/1/xml?cnpj_emitente=11222333000181" }
  ]
}

Regras e erros (422, com o motivo em erros):

• só se cancela nota autorizado;
• prazo: a SEFAZ aceita o cancelamento por um prazo depois da autorização (24 horas é o padrão nacional; algumas UFs admitem mais). Passou do prazo: a API recusa e orienta falar com o contador (devolução ou estorno);
• não pode haver outro cancelamento ou carta de correção em andamento;
• se a SEFAZ recusar o cancelamento, o evento fica recusado (com status_sefaz e mensagem_sefaz), a nota continua autorizado e você pode corrigir o motivo e pedir de novo.

{ "codigo": "requisicao_invalida", "mensagem": "Confirme que a mercadoria não saiu. ...", "erros": { "confirmo": ["Confirme que a mercadoria não saiu. ..."] } }

Carta de correção (CC-e)#

POST /nfe/{ref}/carta_correcao corrige dados acessórios de uma nota autorizada: complemento de endereço, informações adicionais, dados de transporte e similares.

{ "correcao": "Correcao do complemento do endereco de entrega para Apto 12" }

• correcao: de 15 a 1000 caracteres.
• Não corrige valores, impostos, dados que mudem o destinatário nem datas. Para isso é cancelamento (dentro do prazo) ou nota de devolução/estorno.
• Resposta 202; o evento aparece em eventos com tipo: "carta_correcao" e sequencia (1, 2, 3...). Por prática fiscal, cada nova carta deve repetir as correções anteriores que continuam valendo: a SEFAZ considera a mais recente.
• A SEFAZ aceita até 20 cartas por nota. Não dá para enviar uma carta enquanto a anterior estiver em andamento, nem para nota cancelada.
• Se a SEFAZ recusar, o evento fica recusado e a mesma sequência pode ser usada de novo.

Inutilizar numeração#

Inutilizar é declarar à SEFAZ que uma faixa de números nunca será usada. Serve para números reservados que ficaram sem nota (uma nota rejeitada e abandonada, por exemplo). A plataforma não deixa buracos de propósito, mas notas rejeitadas que você desistiu de corrigir deixam números parados.

POST /nfe/inutilizacao (a mesma rota e os mesmos nomes do Focus NFe):

{
  "cnpj": "11222333000181",
  "serie": 1,
  "numero_inicial": 1,
  "numero_final": 2,
  "justificativa": "Numeros reservados para notas rejeitadas e abandonadas",
  "confirmo": true
}

Só entram na faixa números que nunca existiram na SEFAZ: notas rascunho, rejeitadas ou paradas por pendência. Número de nota autorizada, denegada, cancelada ou em processamento é recusado (422, em erros.faixa). A faixa também não pode passar do último número já gerado na série.

Resposta 202, depois consulte por GET /nfe/inutilizacoes:

{
  "id": 1, "cnpj": "11222333000181", "ambiente": "homologacao", "serie": "1", "numero_inicial": "5", "numero_final": "6",
  "status": "autorizado", "justificativa": "Numeros reservados para notas rejeitadas e abandonadas",
  "protocolo_sefaz": "141260000000001", "status_sefaz": "102", "mensagem_sefaz": "Inutilizacao de numero homologada",
  "solicitado_em": "2026-10-04T15:53:12+00:00", "caminho_xml": "https://srv1839254.hstgr.cloud/api/v2/nfe/inutilizacoes/1/xml?cnpj_emitente=11222333000181"
}

O status da inutilização é processando_autorizacao enquanto espera a SEFAZ, autorizado quando registrada e erro_autorizacao quando recusada (veja status_sefaz e mensagem_sefaz).

Quando a inutilização é registrada, as notas daquela faixa passam a inutilizado (uma para cada ref afetada). Para vender de novo aquele pedido, use uma ref nova: ela recebe um número novo.

O prazo legal para inutilizar é até o dia 10 do mês seguinte ao da emissão; a SEFAZ não barra depois, mas fora do prazo a obrigação acessória fica irregular: fale com o contador.