> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engineapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# SEFAZ e webservices
> Como funciona a SEFAZ, seus ambientes, estabilidade e como a engineAPI abstrai a comunicação fiscal.
A SEFAZ (Secretaria de Estado da Fazenda) é o órgão responsável por **autorizar e registrar** todos os documentos fiscais eletrônicos no Brasil. Cada estado tem sua própria SEFAZ com webservices independentes.
***
## Como a engineAPI se Comunica
Você envia JSON. Nós fazemos tudo o mais:
```
Seu app (JSON)
↓
engineAPI
├── Valida campos obrigatórios
├── Converte JSON → XML NF-e (ABRASF / SEFAZ)
├── Assina XML com seu certificado A1 (RSA SHA-256)
├── Transmite via SOAP para o webservice SEFAZ do estado
├── Recebe resposta XML da SEFAZ
└── Converte resposta XML → JSON limpo
↓
Seu app (JSON) + Webhook
```
***
## Ambientes
| Ambiente | Código | Uso | URL |
| --------------- | ------ | ------------------------------ | ---------------------------- |
| **Produção** | `1` | Documentos com validade fiscal | Webservice real do estado |
| **Homologação** | `2` | Testes sem efeito fiscal | Webservice de teste da SEFAZ |
O endpoint da engineAPI é **sempre o mesmo** (`https://api.engineapi.com.br`). O ambiente é definido no cadastro da empresa emissora com o campo `ambienteFiscal`.
***
## Webservices por Estado (Produção)
Os principais estados e seus webservices:
| Estado | SEFAZ Responsável | Notas |
| ------------------------------------------------------ | ------------------------ | ------------------------------- |
| SP | SEFAZ-SP | Maior volume de emissão do país |
| RJ | SEFAZ-RJ | N/A |
| MG | SEFAZ-MG | N/A |
| RS, SC, PR | SEFAZ Virtual RS | Ambiente compartilhado |
| BA, CE, GO, MA, MT, MS, PA, PE, PI, RN, RO, SE, TO, DF | SEFAZ Virtual AN (SVCAN) | Ambiente compartilhado |
***
## Consultando o Status da SEFAZ
Verifique se o webservice do estado está operacional antes de emitir:
```bash theme={null}
curl https://api.engineapi.com.br/v1/nfe/sefaz-status/SP \
-H "Authorization: Bearer SEU_TOKEN"
```
```json theme={null}
{
"data": {
"uf": "SP",
"status": "UNKNOWN",
"message": "Serviço em Operação",
"responseTimeMs": 245,
"checkedAt": "2026-02-10T18:00:00.000Z",
"cStat": 107
},
"meta": { "requestId": "req_abc123", "timestamp": "2026-07-06T12:00:00.000Z" }
}
```
Para consultar todas as UFs de uma vez (cache de 5 minutos): `GET /v1/nfe/sefaz-status`.
| Status | Significado | Ação |
| --------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `UP` | Consulta real (com certificado) confirmou SEFAZ operacional | Emite normal |
| `DOWN` | Consulta real confirmou SEFAZ fora do ar (ou a consulta falhou) | A engineAPI já reroteia sozinha para a contingência SVC |
| `UNKNOWN` | Sem consulta real (sem certificado de um emissor) | Informativo: `message`/`cStat` ainda vêm do provider; não indica se a próxima emissão será normal ou SVC |
`GET /v1/nfe/sefaz-status[/:uf]` (as rotas públicas de consulta) nunca usa o
certificado de um emissor, então `status` sai sempre `UNKNOWN`. É desenho deliberado:
sem consulta real (cert-backed), a engineAPI nunca fabrica "no ar"/"fora do ar" pro
dev. `UP`/`DOWN` só aparecem na decisão interna de contingência (abaixo), que roda com
o certificado do emissor no momento da emissão.
***
## Contingência
Quando a SEFAZ da UF do emissor está `DOWN` (consulta real, com o certificado do
emissor, feita a cada `POST /v1/nfe`), a engineAPI reroteia automaticamente a
transmissão para a **SEFAZ Virtual de Contingência (SVC-AN ou SVC-RS)**. O mapa de
qual SVC atende cada UF é decidido pela engineAPI, sem nenhuma ação do parceiro.
A engineAPI implementa contingência via **SVC**, não via **EPEC**. Notas emitidas em
contingência **não** ganham um status separado tipo `CONTINGENCY`: o `Invoice` chega
a `AUTHORIZED` (ou `REJECTED`) do mesmo jeito que uma emissão normal, só que
autorizada pela SVC. O único jeito de identificar é inspecionar `tpEmis` no XML
autorizado (`1` = normal, `6` = SVC-AN, `7` = SVC-RS). Quando a SEFAZ da UF volta a
ficar `UP`, a próxima emissão já transmite normal de novo, sem retransmissão manual.
Ver também [Contingência SVC](/guides/emitir-nfe#contingncia-svc).
***
## Situação do documento / resposta perdida
Uma conexão pode cair depois que a SEFAZ autorizou a NF-e ou NFC-e e antes de a
resposta chegar à engineAPI. Nessa situação, retransmitir às cegas é inseguro:
o documento já pode existir e a segunda tentativa pode voltar como duplicidade.
A engineAPI persiste a chave de acesso antes da transmissão. Se a resposta do
worker se perde, consulta a situação dessa chave na SEFAZ antes de qualquer
retransmissão:
| Situação consultada | Ação da engineAPI |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| Autorizada | Atualiza para `AUTHORIZED`, grava protocolo/data quando devolvidos e envia o webhook que faltou |
| Não encontrada | A mesma emissão pode ser tentada novamente, mantendo número e chave |
| Cancelada | Atualiza para `CANCELED`; não retransmite |
| Denegada ou rejeitada | Atualiza para `REJECTED`; não retransmite |
`GET /v1/nfe/{id}` e `GET /v1/nfce/{id}` também reconciliam documentos antigos
em `CREATED`, `TRANSMITTING` ou `ERROR` antes de responder. Documentos finais
(`AUTHORIZED`, `REJECTED` e `CANCELED`) nunca provocam nova consulta.
***
## Veja também
Códigos de rejeição SEFAZ e como resolver
Ambiente de homologação para testes