Ciclo de Vida e Fluxo Assíncrono

Por que 2xx significa aceito na fila, estados no banco e transições.

A autorização de documentos fiscais eletrônicos no Brasil depende de servidores governamentais (SEFAZ estaduais e Receita Federal) que apresentam oscilações de latência e instabilidades momentâneas. Por essa razão, a arquitetura do NFER é fundamentada no modelo assíncrono resiliente.

Resposta HTTP 2xx = Aceito, não Autorizado

Quando a API retorna status 201 Created ou 202 Accepted, isso significa que seu payload foi validado com sucesso e enfileirado para envio. A autorização jurídica perante a SEFAZ ocorre de forma assíncrona através de workers dedicados.

Estados do Documento Fiscal

Ao longo do seu processamento, a nota percorre os seguintes estados no banco de dados:

Status	Tipo	Significado & Comportamento
`rascunho`	Transitório	Nota salva e validada no NFER, com número e série reservados. Pode ser editada ou cancelada antes da transmissão à SEFAZ.
`processando`	Transitório	Nota na fila de processamento. O worker assina o XML com o Certificado A1 e transmite ao Web Service da SEFAZ.
`autorizada`	Final	A SEFAZ autorizou o documento fiscal (cStat 100/150). O XML com protocolo e o DANFE em PDF ficam disponíveis para download.
`erro`	Intermediário	A SEFAZ rejeitou o XML (ex.: cStat 539 duplicidade, cStat 696 indFinal). O rascunho pode ser corrigido e retransmitido.
`contingencia`	Operacional	Autorizada na SEFAZ Virtual (SVC) ou emitida em contingência offline (NFC-e). A mercadoria pode circular com DANFE.
`cancelada`	Final	Cancelamento homologado na SEFAZ (cStat 135) após solicitação formal com justificativa dentro do prazo legal.
`denegada`	Final	A SEFAZ denegou o uso por irregularidade fiscal grave do emitente ou destinatário. O número não pode ser reutilizado.
`inutilizada`	Final	Número formalmente inutilizado na SEFAZ devido a salto ou falha irrecuperável na sequência da série.

Diagrama de Transições

  [ POST /nfe ] ──> rascunho ──> [ POST /send ] ──> processando
                                                          │
                       ┌──────────────────────────────────┴──────────────────────────────────┐
                       │                                  │                                  │
                       ▼                                  ▼                                  ▼
                  autorizada                            erro                            contingencia
                       │                          (corrige e reenvia)                        │
             ┌─────────┴─────────┐                        │                                  │
             ▼                   ▼                        ▼                                  ▼
         cancelada           denegada                inutilizada                    retransmissão normal
      (cStat 135 SEFAZ)   (irregularidade)      (POST /inutilization)               (probe em background)

Como Acompanhar a Autorização

Existem duas formas de receber a chave de acesso, o protocolo e os links de impressão:

1. Webhook em Tempo Real (Recomendado)

Assim que a SEFAZ processa o documento, o NFER envia um POST HTTPS para seu servidor com o evento nfe.autorizada ou nfe.erro. Latência média de 1 a 2 segundos.

2. Polling Prudente (Fallback)

Se seu sistema não puder receber webhooks, faça consultas periódicas via GET /v1/nfe/:id com intervalo de 3 a 5 segundos até que o status mude para um estado final.

Próximos Passos

Aprenda sobre o funcionamento da contingência em Contingência Automática.
Consulte o catálogo de eventos em Webhooks.