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 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:

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.

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.

Comece aqui

Emissão

Tributação

Erros e operação

IA e automação

Conceitos

Migração

Perguntas frequentes

SEFAZ e webservices

Como a engineAPI se Comunica

Ambientes

Webservices por Estado (Produção)

Consultando o Status da SEFAZ

Contingência

Situação do documento / resposta perdida

Veja também

Erros e Rejeições

Sandbox

​Como a engineAPI se Comunica

​Ambientes

​Webservices por Estado (Produção)

​Consultando o Status da SEFAZ

​Contingência

​Situação do documento / resposta perdida

​Veja também

Erros e Rejeições

Sandbox

Como a engineAPI se Comunica

Ambientes

Webservices por Estado (Produção)

Consultando o Status da SEFAZ

Contingência

Situação do documento / resposta perdida

Veja também