SEFAZ lenta ou instável

A emissão de documentos fiscais pela API é assíncrona: o POST de emissão devolve um recibo, e o resultado deve ser acompanhado pela consulta (GET .../{recibo}). Na operação normal, a SEFAZ autoriza em poucos segundos.

Em alguns momentos (instabilidade ou lentidão da SEFAZ), a autorização pode levar mais de 15 segundos. Nessa janela, enquanto a SEFAZ ainda não deu uma resposta definitiva, a consulta do recibo devolve o status de processamento:

{
  "status": "003",
  "descricao": "A nota está em processo de emissão."
}

Status 003 = ainda processando (pendente), não é falha

Enquanto a SEFAZ não conclui, a consulta do recibo devolve status: "003" (em processo de emissão) — um estado pendente. Continue consultando o mesmo recibo; não reemita. Nosso sistema corrige automaticamente o status assim que a SEFAZ responder (veja abaixo).

A regra de ouro: 003 é pendente; só reemita em rejeição definitiva

status	Significado	Ação do integrador
003	Em processamento — SEFAZ ainda não respondeu (inclui lentidão/instabilidade)	Aguardar e seguir consultando o mesmo recibo — não reemitir
004	Autorizada (protocolo e XML disponíveis)	Concluir a venda / imprimir DANFE
010	Cancelada	—
900	Rejeição definitiva da SEFAZ	Corrigir o dado apontado em sefaz.mensagem e emitir uma nova nota

Salvaguarda: se você receber 900 com sefaz.codigo 217 ou 105

O fluxo normal reporta o processamento como 003. Como salvaguarda defensiva, se em algum momento você receber status: "900" acompanhado de sefaz.codigo 217 ou 105, trate também como pendente (SEFAZ ainda processando) — não reemita. Só trate 900 como definitivo quando sefaz.codigo não for 217/105.

O que o nosso sistema faz automaticamente

Você não precisa (e não deve) reenviar a nota. Nosso sistema possui reconciliação automática: um processo interno re-consulta a situação da nota diretamente na SEFAZ (pela chave de acesso) e atualiza o resultado assim que houver resposta definitiva:

• Se a SEFAZ autorizou → a consulta do recibo passa a devolver status: "004", com protocolo de autorização e XML definitivo — como em qualquer emissão normal.
• Se a SEFAZ rejeitou de fato → a consulta passa a devolver status: "900" com sefaz.codigo/sefaz.mensagem refletindo a rejeição real, para correção e reenvio.

Na maioria dos casos a situação se resolve em poucos minutos. A janela de reconciliação automática cobre até 3 horas.

Ação necessária do integrador

1. Continue consultando o mesmo recibo enquanto o status for 003 (ou, na salvaguarda, 900 com sefaz.codigo 217/105), até obter um resultado definitivo (004 autorizada ou 900 com código de rejeição real). Sugestão de polling: a cada 2–5 s no primeiro minuto; depois a cada 30–60 s.
2. Nunca reenvie a mesma venda enquanto o status for 003 (nem, na salvaguarda, 900 com 217/105). A nota pode já ter sido autorizada na SEFAZ — reenviar gera duplicidade de documento fiscal (duas notas válidas para a mesma venda).
3. Só considere a venda concluída (impressão de DANFE, baixa no seu sistema) quando obtiver status: "004" (autorizada).
4. Se receber uma rejeição definitiva (900 com sefaz.codigo ≠ 217/105, ex.: erro cadastral ou tributário), corrija o dado apontado em sefaz.mensagem e aí sim emita uma nova nota.
5. Se uma nota permanecer em 003 (ou 900+217/105) por mais de 3 horas, não reemita por conta própria — acione o suporte informando o recibo e a chave de acesso, para verificação manual.

Resumo por situação

Situação	status	sefaz.codigo	Ação
Em processamento (SEFAZ lenta / sem retorno)	003	—	Aguardar e repetir a consulta — não reemitir
Autorizada	004	100	Concluir a venda / imprimir DANFE
Rejeição definitiva	900	≠ 100/217/105	Corrigir o dado e emitir nova nota
Cancelada	010	—	—
Salvaguarda: 900 transitório	900	217 (ou 105)	Tratar como pendente — aguardar, não reemitir
Pendente por mais de 3h	003 (ou 900+217/105)	—	Contatar o suporte com recibo + chave — não reemitir

Checando isso no código do seu cliente

Trate 003 (e 001/002) como pendente. Como salvaguarda, se receber 900, verifique data.sefaz.codigo antes de tratar como terminal — 217/105 continuam sendo transitórios:

const SEFAZ_TRANSITORIO = ['217', '105'];

function classificar(json: { status: string; data?: { sefaz?: { codigo?: string } } }) {
  const codigoSefaz = json.data?.sefaz?.codigo;

  // 001/002/003 = em processamento => pendente, continue consultando
  if (['001', '002', '003'].includes(json.status)) return 'pendente';

  // salvaguarda: 900 com codigo transitorio ainda NAO é definitivo
  if (json.status === '900' && codigoSefaz && SEFAZ_TRANSITORIO.includes(codigoSefaz)) {
    return 'pendente';
  }

  if (['004', '010'].includes(json.status)) return 'sucesso';
  if (['500', '900', '999'].includes(json.status)) return 'falha';
  return 'falha';
}

Veja também Fluxo assíncrono para o exemplo completo de polling com backoff.