> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spedy.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Ciclo de vida da nota

> Os estados e transições de uma nota fiscal na Spedy.

Emitir uma nota pela API da Spedy é uma operação **assíncrona**: a resposta
`2xx` do `POST` que cria a nota confirma apenas que a solicitação foi **aceita
para processamento** — não que a nota foi autorizada pela SEFAZ ou pela
prefeitura. Entre a criação e a autorização, a nota passa por uma sequência
de estados, e o tempo entre um estado e outro varia de segundos a, em
contingência, horas ou dias.

Há dois caminhos de entrada, que diferem em **quando** a nota é enfileirada:

* **POST direto na nota** (`/v1/product-invoices`, `/v1/consumer-invoices`,
  `/v1/service-invoices`): a nota **já é enfileirada para emissão no próprio
  POST** — não existe um passo de emissão separado.
* **Via venda** (`POST /v1/orders`): a emissão segue o `autoIssueMode` da venda —
  pode ser imediata ou ficar **aguardando** (`created`) até um gatilho (ex.:
  `afterPayment`). Veja [Fluxo de emissão](/pages/guides/fluxo-de-emissao).

Saber em qual estado a nota está — e o que fazer em cada um — é o que
permite ao seu sistema decidir quando liberar a mercadoria, emitir o
DANFE/DANFSE ou notificar o cliente, em vez de assumir que "a chamada
respondeu 200, então a nota está pronta".

## Estados e transições

O campo `status` (`InvoiceStatus`) de uma nota — NF-e, NFC-e ou NFS-e —
segue a máquina de estados abaixo:

```mermaid theme={null}
stateDiagram-v2
    [*] --> created
    created --> enqueued: enfileirada para emissão
    created --> removed: nota removida antes do envio
    created --> disabled: inutilização de numeração
    enqueued --> received
    received --> authorized
    received --> rejected
    received --> inContingent
    received --> denied
    inContingent --> authorized: autoridade volta a operar e autoriza
    inContingent --> rejected: autoridade volta a operar e rejeita
    authorized --> canceled: cancelamento dentro do prazo legal
```

<Note>
  `authorized`, `rejected`, `denied` e `canceled` são estados terminais para
  aquela numeração — uma nota rejeitada ou denegada não "vira" autorizada
  depois; você corrige o problema e emite uma **nova** nota. A exceção é
  `inContingent`, que é sempre transitório: assim que a autoridade volta a
  operar e o lote é reprocessado, a nota é reclassificada como `authorized`
  ou `rejected`.
</Note>

### O que cada status significa

| `status`       | Significado                                                                                                                                                                                                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `created`      | Criada, ainda não enfileirada. No POST direto da nota esse estado é praticamente instantâneo — ela já segue para `enqueued`. Fica de fato **aguardando** quando a nota vem de uma venda com `autoIssueMode` diferido (ex.: `afterPayment`), até o gatilho ocorrer. Nada foi enviado à SEFAZ/prefeitura ainda. |
| `enqueued`     | Enfileirada para processamento junto à SEFAZ ou à Prefeitura. A Spedy já aceitou a solicitação e está preparando ou enviando o lote.                                                                                                                                                                          |
| `received`     | Recebida pela autoridade fiscal. O lote foi entregue e aguarda o retorno do processamento — ainda não há veredito.                                                                                                                                                                                            |
| `authorized`   | Autorizada. A nota foi validada e aprovada — é o estado que permite gerar o DANFE/DANFSE e considerar a operação fiscal concluída.                                                                                                                                                                            |
| `inContingent` | Em contingência. A SEFAZ/prefeitura estava indisponível e a nota foi emitida nesse modo; o resultado definitivo (`authorized` ou `rejected`) só chega quando o ambiente volta e o lote é reprocessado. Veja [Contingência](/pages/guides/contingencia).                                                       |
| `rejected`     | Rejeitada. A autoridade fiscal recusou a nota por erro de validação (dados, schema, regra de negócio). Veja [Erros e rejeições](/pages/reference/erros-e-rejeicoes) para tratar a causa e reemitir.                                                                                                           |
| `canceled`     | Cancelada. Uma nota **autorizada** foi cancelada dentro do prazo legal. Veja [Cancelamento, correção e inutilização](/pages/guides/cancelamento-correcao-inutilizacao).                                                                                                                                       |
| `denied`       | Denegada. A autoridade recusa a autorização — a nota não é validada, mas a numeração é considerada consumida.                                                                                                                                                                                                 |
| `removed`      | Removida do fluxo antes de ser enviada à autoridade fiscal (por exemplo, quando o registro de origem é cancelado enquanto a nota ainda está `created`).                                                                                                                                                       |
| `disabled`     | Inutilizada. A faixa de numeração foi formalmente inutilizada junto à SEFAZ/prefeitura. Veja [Cancelamento, correção e inutilização](/pages/guides/cancelamento-correcao-inutilizacao).                                                                                                                       |

<Warning>
  **`InvoiceStatus` não é `InvoiceProcessingStatus`.** São dois campos
  diferentes e é fácil confundir os dois:

  * **`InvoiceStatus`** (`status`) é o estado **fiscal** da nota — os valores
    da tabela acima (`created`, `authorized`, `rejected` etc.).
  * **`InvoiceProcessingStatus`** é o estado **interno de processamento** de
    um evento na fila: `processing` (aguardando execução), `success`
    (o evento foi executado) ou `failed` (falha interna de infraestrutura ao
    processar o evento).

  `success` em `InvoiceProcessingStatus` **não significa nota autorizada** —
  significa que a Spedy conseguiu executar aquele passo do fluxo (enviar o
  lote, receber a resposta da SEFAZ, atualizar o status). Uma nota
  **rejeitada** também tem `InvoiceProcessingStatus` igual a `success`,
  porque o processamento funcionou normalmente; só o resultado fiscal foi
  negativo. Para saber se a nota foi autorizada, olhe sempre o
  `InvoiceStatus` — nunca o `InvoiceProcessingStatus`.
</Warning>

## Como acompanhar as transições

Não faça polling apertado esperando a nota "ficar pronta" logo após criá-la.
Use um dos dois mecanismos abaixo.

### Webhooks (recomendado)

A forma mais eficiente de saber que o `status` mudou é configurar um
webhook: a Spedy notifica seu sistema a cada transição relevante (recebida,
autorizada, rejeitada, cancelada etc.), sem que você precise consultar a
API. Veja [Visão geral de webhooks](/pages/webhooks/visao-geral) e
[Eventos e payload](/pages/webhooks/eventos-e-payload) para o formato de
cada evento.

### Obter a nota fiscal (GET por ID)

Se você não usa webhooks, obtenha a nota (`GET .../{id}`) para ler o
`status` atual guardado pela Spedy — essa leitura não aciona a SEFAZ.

### Reconciliar com a SEFAZ (`check-status`)

O endpoint `check-status` consulta a nota **diretamente na
SEFAZ/prefeitura** e reconcilia o resultado no seu registro. Use-o apenas
para destravar ou reconciliar uma nota cujo status no Spedy pode estar
desatualizado — por exemplo, uma nota marcada como `rejected` que na
verdade consta autorizada na SEFAZ, ou um acompanhamento automático que
esgotou as tentativas. Enquanto a nota ainda está `enqueued` (não enviada à
autoridade), esse endpoint responde erro — ele não serve para "furar a
fila" e forçar uma emissão imediata.