# 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](08-webhooks.md)).

| Método | Rota | Para quê |
|---|---|---|
| `GET` | `/nfe/{ref}` | estado atual da nota, com chave, protocolo, links e eventos |
| `GET` | `/nfe/{ref}/xml` | XML autorizado (`nfeProc`) |
| `GET` | `/nfe/{ref}/danfe` | DANFE em PDF |
| `DELETE` | `/nfe/{ref}` | cancelar |
| `POST` | `/nfe/{ref}/carta_correcao` | carta de correção (CC-e) |
| `GET` | `/nfe/{ref}/eventos/{id}/xml` | XML de um evento registrado |
| `POST` | `/nfe/inutilizacao` | inutilizar uma faixa de numeração |
| `GET` | `/nfe/inutilizacoes` | histórico de inutilizações |
| `GET` | `/nfe/inutilizacoes/{id}/xml` | XML de uma inutilização registrada |

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](05-emitir-nfe.md#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](10-producao.md#acompanhar-a-nota)).

## 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:

<!-- exemplo:cancelar -->
```json
{ "justificativa": "Cliente desistiu da compra antes do envio", "confirmo": true }
```

| Campo | Regra |
|---|---|
| `justificativa` | de 15 a 255 caracteres |
| `confirmo` | obrigatório e `true`: você afirma que a **mercadoria não saiu**. Cancelar uma venda já despachada é irregular (o caminho certo é devolução ou estorno, com o contador) |

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

```json
{
  "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:

```json
{
  "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.

```json
{ "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.

<!-- exemplo:correcao -->
```json
{ "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):

<!-- exemplo:inutilizar -->
```json
{
  "cnpj": "11222333000181",
  "serie": 1,
  "numero_inicial": 1,
  "numero_final": 2,
  "justificativa": "Numeros reservados para notas rejeitadas e abandonadas",
  "confirmo": true
}
```

| Campo | Regra |
|---|---|
| `cnpj` (ou `cnpj_emitente`) | a empresa. Dispensável se a conta tem uma só |
| `serie`, `numero_inicial`, `numero_final` | a faixa (contínua, até 1000 números, de **um só ano**) |
| `justificativa` | de 15 a 255 caracteres |
| `confirmo` | obrigatório e `true`: você afirma que os números **não foram usados em nenhuma NF-e**, inclusive em outro sistema de emissão |

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`:

```json
{
  "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.