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

# Emissão síncrona vs assíncrona

> Diferenças entre emissão síncrona e assíncrona de notas fiscais.

Um dos erros mais comuns ao integrar com a Spedy é tratar a resposta `2xx`
de um endpoint de emissão como "nota emitida". A API da Spedy é
**assíncrona**: a resposta HTTP confirma apenas que a solicitação foi aceita
para processamento, não que a nota foi autorizada pela SEFAZ ou pela
prefeitura.

<Warning>
  Um `200 OK` (ou `201 Created`) em `POST /v1/orders/{id}/invoices/issue` ou
  em `POST /v1/product-invoices`, `/v1/consumer-invoices`,
  `/v1/service-invoices` significa apenas que a Spedy **aceitou** a
  solicitação e a enfileirou. A nota pode, minutos depois, ser rejeitada
  pela SEFAZ. Nunca libere mercadoria, feche a venda para o cliente ou dê a
  operação fiscal por concluída só porque a chamada retornou 2xx.
</Warning>

## Por que é assíncrono

Autorizar uma nota fiscal depende de um sistema fora da Spedy — a SEFAZ do
estado ou a prefeitura do município — que pode levar de alguns segundos a,
em cenários de indisponibilidade (contingência), horas ou dias para
responder. Se a API da Spedy segurasse a conexão HTTP até ter esse
resultado, qualquer lentidão ou instabilidade do lado da autoridade fiscal
travaria sua integração. Por isso a emissão funciona em duas fases
desacopladas:

1. **Aceite da solicitação** — resposta HTTP imediata (2xx), confirmando
   que os dados foram recebidos e a nota entrou na fila de processamento.
2. **Processamento fiscal** — a Spedy envia o lote à SEFAZ/prefeitura,
   aguarda o retorno e atualiza o status da nota de forma assíncrona,
   independente da chamada HTTP original.

Os estados possíveis nessa segunda fase — `created`, `enqueued`, `received`,
`authorized`, `rejected`, `inContingent`, `denied`, `canceled` — e as
transições entre eles estão documentados em [Ciclo de vida da
nota](/pages/guides/ciclo-de-vida-da-nota).

## Como acompanhar o resultado

Como a resposta HTTP não carrega o veredito final, seu sistema precisa de
uma forma de saber quando a nota chegou a um estado terminal. Há dois
mecanismos, e eles não são intercambiáveis:

| Mecanismo              | Quando usar                                                                                                                                                                                                                                                                                                                                               |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Webhook**            | Forma recomendada e mais eficiente: a Spedy notifica seu sistema a cada mudança de status (`invoice.status_changed`, `invoice.authorized`, `invoice.rejected`, `invoice.canceled`), sem que você precise consultar a API. Veja [Eventos e payload](/pages/webhooks/eventos-e-payload).                                                                    |
| **Consulta de status** | `GET` na nota (ex.: `/v1/product-invoices/{id}`) retorna o `status` atual guardado pela Spedy — leitura simples, não aciona a SEFAZ. O endpoint `check-status` é diferente: consulta a nota diretamente na SEFAZ/prefeitura para reconciliar um registro que pode estar desatualizado. Veja [Ciclo de vida da nota](/pages/guides/ciclo-de-vida-da-nota). |

<Note>
  Não faça polling apertado logo após o `issue` esperando a nota "ficar
  pronta". Prefira webhooks para ser notificado no momento da mudança de
  status; use consulta de status apenas quando precisar do estado atual sob
  demanda.
</Note>

## Resumo

* **Síncrono** é só o aceite HTTP: confirma que a Spedy recebeu a
  solicitação, nada além disso.
* **Assíncrono** é o processamento fiscal real: pode levar segundos ou, em
  contingência, muito mais — veja [Contingência](/pages/guides/contingencia).
* O único jeito confiável de saber se uma nota foi autorizada é observar o
  `status` via webhook ou consulta — nunca o código HTTP da chamada de
  emissão.