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

# Ciclo de vida

> Emissão assíncrona, estados e acompanhamento — para cada tipo de nota (NF-e e NFS-e).

As duas APIs emitem de forma **assíncrona**: o `POST` persiste e enfileira a nota, retornando `201` com a situação `pendente`. O que muda é o destino fiscal e como o resultado é acompanhado. Cada tipo de nota tem seu próprio ciclo abaixo.

## NF-e — Nota de Produto

### Emissão é assíncrona

`POST /notas` **não** emite a NF-e de forma síncrona. A nota é persistida e enfileirada para autorização junto à SEFAZ; a resposta é `201 Created` com `situacao: "pendente"`. O `uuid` e a `chave_acesso` já voltam **estáveis** nessa resposta (são gerados na criação).

Para acompanhar o resultado, há duas opções:

<CardGroup cols={2}>
  <Card title="Polling" icon="rotate">
    Consulte `GET /notas/{uuid}` até a `situacao` mudar.
  </Card>

  <Card title="Webhooks" icon="webhook">
    Assine os eventos `nfe_*`. Veja [Webhooks](/webhooks).
  </Card>
</CardGroup>

<Note>
  O **próximo** webhook após `nfe_solicitacao_autorizacao` é o **veredito terminal** (`nfe_autorizada`, `nfe_rejeitada` ou `nfe_denegada`). Não existe evento intermediário `em_processamento`.
</Note>

### Estados (`situacao`)

| Estado             | Significado                                     |
| ------------------ | ----------------------------------------------- |
| `pendente`         | Criada e enfileirada; ainda não transmitida.    |
| `em_processamento` | Lote enviado, aguardando o protocolo da SEFAZ.  |
| `autorizada`       | Autorizada pela SEFAZ. XML e DANFE disponíveis. |
| `rejeitada`        | Rejeitada pela SEFAZ (veja a mensagem de erro). |
| `denegada`         | Denegada pela SEFAZ.                            |
| `cancelada`        | Cancelamento autorizado (evento 110111).        |
| `inutilizada`      | Numeração inutilizada.                          |

### Cancelamento

`DELETE /notas/{uuid}/cancel` solicita o cancelamento (evento 110111) de uma nota **autorizada**, com `justificativa` de 15–255 caracteres. O processamento é **assíncrono**: retorna `202` e o resultado chega via webhook (`nfe_cancelamento_autorizado` / `nfe_cancelamento_rejeitado`) ou polling.

<Warning>
  A janela consultiva de cancelamento é de **24h** após a autorização. Notas não autorizadas não podem ser canceladas (`422`).
</Warning>

### Inutilização é síncrona

`POST /inutilizacoes` (inutilização de **faixa** de numeração) é a única operação que chama a SEFAZ de forma inline — uma chamada SOAP curta, veredito imediato: retorna `200` (inutilizada) ou `422` (rejeitada).

### Documentos

Após a autorização, baixe os documentos fiscais pelas rotas autenticadas:

* `GET /notas/{uuid}/xml` — XML autorizado (nfeProc), `application/xml`.
* `GET /notas/{uuid}/danfe` — DANFE, `application/pdf` (gerado sob demanda no primeiro acesso).

## NFS-e — Nota de Serviço

### Emissão é assíncrona (via RPS)

`POST /notas` **não** emite a NFS-e de forma síncrona. A nota é persistida e um **RPS** (Recibo Provisório de Serviços) é gerado e enfileirado para envio **em lote** à prefeitura. A resposta é `201 Created` com `rps.situacao: "pendente"` e `nfse.situacao: "pendente"`. O `id` já volta estável nessa resposta.

<Note>
  A resposta tem **duas máquinas de estado**: o **RPS** é o veículo (o envio do recibo à prefeitura) e a **NFS-e** é o resultado (a nota de serviço efetivamente emitida). Em uso normal acompanhe `nfse.situacao`; consulte `rps.situacao` para diagnosticar uma falha de envio.
</Note>

O acompanhamento é por **polling**:

<Card title="Polling" icon="rotate">
  Consulte `GET /notas/{id}` até `nfse.situacao` virar `emitida` (com `nfse.numero` e `codigo_verificacao`) ou o RPS falhar (`rps.situacao: "processado_com_erro"`).
</Card>

<Note>
  A API de NFS-e **não** emite webhooks (diferente da NF-e) — acompanhe por polling. As notificações por e-mail da conta seguem normalmente.
</Note>

### Estados da NFS-e (`nfse.situacao`)

| Estado        | Significado                                                                |
| ------------- | -------------------------------------------------------------------------- |
| `pendente`    | Criada e enfileirada; aguardando emissão pela prefeitura.                  |
| `emitida`     | Emitida pela prefeitura. `nfse.numero` e `codigo_verificacao` disponíveis. |
| `cancelada`   | Cancelamento autorizado pela prefeitura.                                   |
| `substituida` | Substituída por outra nota.                                                |

### Estados do RPS (`rps.situacao`)

Diagnóstico do envio do lote à prefeitura:

| Estado                   | Significado                                          |
| ------------------------ | ---------------------------------------------------- |
| `pendente`               | Ainda não transmitido.                               |
| `nao_recebido`           | Lote não recebido pela prefeitura.                   |
| `nao_processado`         | Recebido; processamento ainda pendente.              |
| `processado_com_erro`    | Rejeitado pela prefeitura (veja a mensagem de erro). |
| `processado_com_sucesso` | Lote processado; a NFS-e foi emitida.                |

### Cancelamento

`DELETE /notas/{id}/cancel` solicita o cancelamento de uma nota **emitida**, com `motivo_cancelamento` obrigatório. O processamento é **assíncrono**: retorna `202` e a `nfse.situacao` passa a `cancelada` quando a prefeitura confirma — acompanhe por polling. Apenas notas com `nfse.situacao: "emitida"` podem ser canceladas (`422` caso contrário).

<Note>
  A NFS-e não tem inutilização de faixa nem download de XML/DANFE — a comprovação da nota é o `codigo_verificacao`, conferível no portal da prefeitura.
</Note>