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

# Fluxo de emissão

> Visão geral do fluxo de emissão de documentos fiscais.

Este guia dá a visão geral de como uma nota fiscal nasce e chega até a
autorização — do payload enviado até o retorno da SEFAZ ou da prefeitura —
e como isso se conecta com vendas (`orders`). Para os detalhes de cada
modelo de nota, veja [Emissão de NF-e](/pages/guides/emissao-nfe), [Emissão
de NFC-e](/pages/guides/emissao-nfce) e [Emissão de
NFS-e](/pages/guides/emissao-nfse).

## Duas formas de emitir

Há duas formas de emitir uma nota, escolhidas conforme **quanto dado
tributário você quer enviar**:

| Forma             | Endpoint                                                                       | Quando usar                                                                                                                                                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Por venda**     | `POST /v1/orders`                                                              | A mais simples: você envia apenas os dados da venda (data, cliente, itens e valor total) e a Spedy resolve a tributação a partir da configuração da empresa no backoffice. **Não é preciso enviar nenhuma informação tributária** (códigos, impostos, retenções). |
| **Nota completa** | `POST /v1/product-invoices`, `/v1/consumer-invoices` ou `/v1/service-invoices` | Você envia os dados tributários completos, conforme o modelo da nota. Indicada para cenários mais complexos — ou quando o cliente final não deve acessar o backoffice da Spedy para configurar nada.                                                              |

Em ambas, a nota entra no mesmo fluxo de processamento assíncrono descrito
abaixo.

<Note>
  Na emissão **por venda**, a tributação vem da configuração da empresa
  (grupos de tributação e naturezas de operação), feita no backoffice da Spedy
  — não pela API.
</Note>

## Emissão a partir de uma venda

Ao criar uma venda (`POST /v1/orders`), o campo `autoIssueMode` decide o que
acontece com a nota:

| Valor                  | Comportamento                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| `immediately` (padrão) | A nota é emitida automaticamente assim que a venda é criada.                             |
| `afterPayment`         | A emissão é disparada quando a venda é marcada como paga (`PUT /v1/orders/{id}/status`). |
| `afterWarrency`        | A emissão é disparada após o prazo de garantia (`warrantyDate`) da venda.                |
| `disabled`             | A emissão não é automática — você dispara explicitamente.                                |

Independentemente do modo, você também pode emitir (ou reemitir) as notas de
uma venda a qualquer momento chamando:

```bash cURL theme={null}
curl -X POST https://sandbox-api.spedy.com.br/v1/orders/{id}/invoices/issue \
  -H "X-Api-Key: sua-chave-de-api" \
  -H "Content-Type: application/json" \
  -d '{}'
```

O corpo aceita `effectiveDate`, opcional, para definir a data de competência
da nota — se omitido, usa a data original da venda.

## Do payload à autorização

```mermaid theme={null}
sequenceDiagram
    participant App as Seu sistema
    participant Spedy as API Spedy
    participant Sefaz as SEFAZ / Prefeitura

    App->>Spedy: POST da venda (/v1/orders) ou da nota completa (/v1/product-invoices, ...)
    Spedy-->>App: 2xx — aceito (status: created/enqueued)
    Spedy->>Sefaz: Envia lote para autorização
    Sefaz-->>Spedy: Autoriza, rejeita ou não responde (contingência)
    Spedy-->>App: Webhook invoice.status_changed (ou consulta de status)
```

Como mostra o diagrama, a resposta HTTP inicial e o resultado fiscal
acontecem em momentos diferentes — veja [Síncrono vs
assíncrono](/pages/guides/sincrono-vs-assincrono) para o porquê disso e
[Ciclo de vida da nota](/pages/guides/ciclo-de-vida-da-nota) para a máquina
de estados completa que a nota percorre entre o `created` e o resultado
final (`authorized`, `rejected`, `denied` ou `inContingent`).

## Caminhos por tipo de nota

O payload e as regras de validação variam por modelo de nota:

<CardGroup cols={3}>
  <Card title="NF-e" icon="file-invoice" href="/pages/guides/emissao-nfe">
    Nota Fiscal Eletrônica (modelo 55), para operações com produtos.
  </Card>

  <Card title="NFC-e" icon="receipt" href="/pages/guides/emissao-nfce">
    Nota Fiscal de Consumidor Eletrônica (modelo 65), para venda a consumidor final.
  </Card>

  <Card title="NFS-e" icon="file-signature" href="/pages/guides/emissao-nfse">
    Nota Fiscal de Serviço Eletrônica, com regras específicas por município.
  </Card>
</CardGroup>

<Note>
  Uma mesma venda pode gerar mais de um modelo de nota (por exemplo, produto
  e serviço na mesma operação) se
  `general.allowMultipleInvoiceModelsPerOrder` estiver habilitado nas
  [configurações da empresa](/pages/guides/configuracao-inicial).
</Note>