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

# Contingência

> Como funciona a emissão em contingência na Spedy.

Contingência é o mecanismo previsto na legislação para manter a emissão
funcionando quando a **SEFAZ está temporariamente indisponível**
(instabilidade, sobrecarga em datas de pico, manutenção programada). Em vez
de a nota falhar, ela é emitida por um caminho alternativo até que a
autoridade volte a operar.

<Note>
  **Você não aciona a contingência.** A Spedy monitora a disponibilidade da
  SEFAZ e decide automaticamente quando entrar e sair desse modo — não há
  parâmetro na requisição de emissão para forçá-la, e o gatilho é o mesmo
  para todas as empresas de uma UF. Sua integração continua chamando os
  mesmos endpoints (`/orders`, `/product-invoices`, `/consumer-invoices`),
  com o mesmo payload.
</Note>

Contingência se aplica a **NF-e** e **NFC-e**, que dependem de autorização
síncrona da SEFAZ. **NFS-e não tem esse conceito** — o processamento é feito
pelas prefeituras, cada uma com seu próprio comportamento em caso de
indisponibilidade (normalmente, a Spedy reenvia a solicitação até que o
serviço da prefeitura volte, sem um modo de contingência formal como o da
SEFAZ).

## NF-e em contingência (SVC)

Quando a SEFAZ autorizadora da UF está indisponível, a autorização de NF-e
passa a ser feita por um **ambiente de contingência da própria SEFAZ** — o
SVC (Sistema Virtual de Contingência). Na prática, isso é **transparente
para a integração**: a nota continua sendo autorizada de forma síncrona, com
validade plena, apenas por um servidor alternativo. O `status` segue
normalmente o fluxo até `authorized`, e o DANFE é gerado identificado como
emitido em contingência.

A forma de emissão fica registrada no campo `InvoiceIssueType`, cujos
valores relevantes para NF-e são:

| Valor    | Significado                                                                               |
| -------- | ----------------------------------------------------------------------------------------- |
| `normal` | Emissão normal — SEFAZ disponível, sem contingência.                                      |
| `svcan`  | Contingência SVC-AN — SEFAZ Virtual de Contingência do Ambiente Nacional.                 |
| `svcrs`  | Contingência SVC-RS — SEFAZ Virtual de Contingência do Rio Grande do Sul.                 |
| `epec`   | Contingência EPEC — Declaração Prévia de Emissão em Contingência.                         |
| `fsia`   | Contingência FS-IA — DANFE em formulário de segurança, com impressão no verso.            |
| `fsda`   | Contingência FS-DA — DANFE em formulário de segurança, sem impressão no verso.            |
| `scan`   | Contingência SCAN — Sistema de Contingência do Ambiente Nacional (modalidade desativada). |

<Note>
  `InvoiceIssueType` também inclui valores que não são de contingência de
  NF-e: `offLine` (contingência offline de NFC-e, ver abaixo), `website` e
  `alt` (canais de emissão de NFS-e) e `annfs` (Ambiente Nacional da NFS-e —
  veja [Reforma Tributária](/pages/guides/reforma-tributaria)). Qual
  modalidade de contingência de NF-e é usada em cada situação é decidido
  pela Spedy/SEFAZ, não pelo integrador.
</Note>

## NFC-e em contingência (offline)

Para NFC-e, o caminho de contingência é a **emissão offline**: a nota é
válida no momento da emissão, sem depender de autorização síncrona da SEFAZ.

<Warning>
  **Pré-requisito: `allowOfflineContingency`.** A emissão offline só é usada
  se a empresa tiver a contingência offline habilitada. O campo
  `allowOfflineContingency`, no bloco `consumerInvoice` das configurações da
  empresa (`PUT /v1/companies/{id}/settings`), exige `tokenId`/`csc` válidos
  configurados. Sem essa habilitação, a NFC-e segue o fluxo normal de
  retentativa enquanto a SEFAZ estiver indisponível — sem contingência
  offline. Habilitar o campo apenas autoriza a capacidade; **quando** ela é
  usada continua sendo decidido automaticamente pela Spedy.
</Warning>

| Momento           | O que acontece                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Emissão**       | A nota é emitida em contingência e assume `status: inContingent`. O DANFE-NFC-e e o XML já ficam disponíveis — a venda se completa imediatamente. |
| **Regularização** | Quando a SEFAZ volta a operar, a Spedy transmite a nota automaticamente para autorização definitiva. Nenhuma ação do integrador é necessária.     |
| **Conclusão**     | Autorizada, a nota passa a `authorized` (evento `invoice.authorized`). Em rejeição definitiva, passa a `rejected` (evento `invoice.rejected`).    |

<Warning>
  Uma nota `inContingent` é juridicamente válida desde a emissão — a
  regularização apenas registra a autorização na SEFAZ. Enquanto estiver
  `inContingent`, o **cancelamento fica indisponível** até a autorização
  definitiva. Veja [Cancelamento, correção e
  inutilização](/pages/guides/cancelamento-correcao-inutilizacao).
</Warning>

## O que o integrador precisa observar

* **Nenhuma mudança na chamada de emissão.** Contingência é decidida pela
  Spedy; seu código não precisa (e não deve tentar) escolher o modo de
  emissão.
* **NF-e:** a mudança é transparente — acompanhe o `status` normalmente, sem
  lógica especial. A única diferença visível é o `InvoiceIssueType` da nota
  autorizada.
* **NFC-e:** trate `inContingent` como um estado intermediário legítimo — a
  venda já está completa (DANFE e XML disponíveis) mesmo antes da
  autorização definitiva chegar. Não bloqueie a operação esperando
  `authorized`.
* **Cancelamento:** não tente cancelar uma NFC-e enquanto ela estiver
  `inContingent` — a chamada será rejeitada até a autorização definitiva.
* **Webhooks:** a entrada em contingência é sinalizada pelo evento
  `invoice.contingency`, além das transições normais de status. Veja
  [Eventos e payload](/pages/webhooks/eventos-e-payload) para o formato — a
  própria página de eventos documenta uma divergência entre a prosa da API e
  o schema `WebhookEditingDto` quanto à assinatura desse evento
  especificamente; enquanto isso, `invoice.status_changed` cobre a transição
  para `inContingent` de qualquer forma.

## Próximos passos

* Estados da nota, incluindo `inContingent`: [Ciclo de vida da nota](/pages/guides/ciclo-de-vida-da-nota)
* Formato do evento `invoice.contingency` e demais eventos: [Eventos e payload](/pages/webhooks/eventos-e-payload)
* Cancelamento, correção e inutilização: [Cancelamento, correção e inutilização](/pages/guides/cancelamento-correcao-inutilizacao)
* Configurar `tokenId`/`csc`/`allowOfflineContingency`: [Configuração inicial](/pages/guides/configuracao-inicial)