SEFAZ e Webservices
Como funciona a SEFAZ, seus ambientes, estabilidade e como a engineAPI abstrai a comunicação fiscal.
SEFAZ e Webservices
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 environment.
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:
curl https://api.engineapi.com.br/v1/nfe/sefaz-status/SP \
-H "Authorization: Bearer SEU_TOKEN"
{
"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.