Entenda validações, falhas operacionais e rejeições da SEFAZ com mensagens mais humanas.

Erros e rejeições

A API separa erros de validação, erros operacionais e rejeições fiscais. Quando a SEFAZ devolve uma rejeição conhecida, a camada de tradução tenta devolver uma mensagem mais humana para acelerar o suporte.

{
  "ok": false,
  "message": "Rejeição SEFAZ 533",
  "error": {
    "type": "sefaz_rejection",
    "details": {
      "status": "533",
      "reason": "Total da BC ICMS-ST difere do somatório dos itens",
      "hint": "Revise a base de cálculo ST item a item e o totalizador final da nota."
    }
  }
}

Tipos de erro da v1

Erros de payload e cadastro (antes de chegar à SEFAZ)

São a maior parte das falhas reais de integração. A nota nem chega a ser transmitida: a validação acontece no /build, devolve 422 com validation_error e não consome numeração nem gera risco de duplicidade. O rascunho continua lá para ser corrigido e reenviado.

Cadastro da empresa emissora

Documento

Itens

Mensagem que não parece uma validação? Retornos como Undefined array key "..." ou Return value must be of type DOMElement, null returned não são regra fiscal: são falha interna nossa, e o certo é a API ter devolvido uma mensagem dizendo qual campo faltou. Se aparecer, abra chamado com o public_id do documento — tratamos como defeito, não como configuração do seu payload.

Rejeições SEFAZ comuns e como resolver

Muitas vezes, a API retorna com sucesso técnico, mas o processamento na SEFAZ resulta em uma rejeição regulatória. Abaixo listamos as rejeições mais recorrentes e como seu sistema deve tratá-las:

Rejeições do Sistema Nacional da NFS-e

A NFS-e pelo padrão nacional tem códigos próprios, no formato E0nnn, devolvidos pelo Sefin Nacional e não pela SEFAZ. Os mais recorrentes na integração:

Rejeições de NFS-e com leiaute municipal próprio

Alguns municípios não usam o padrão nacional e mantêm webservice e códigos próprios. Aqui a origem da rejeição é a prefeitura, não o Sefin Nacional — e cada uma tem vocabulário diferente para a mesma ideia.

Quando reenviar e quando não reenviar

A pergunta mais cara do suporte é sempre a mesma. O critério é a natureza da falha, não a pressa:

Validação preventiva de parâmetros fiscais

A API valida parâmetros fiscais antes do envio sempre que a incompatibilidade puder ser identificada com segurança. Dados que alteram a identidade fiscal do documento não são reescritos silenciosamente.

• Série informada pelo integrador: A série recebida é preservada. Na NF-e normal, as faixas 890–899 e 900–999 são rejeitadas antes da criação do rascunho.
• Modelo e emissão: nfe exige modelo 55, nfce exige modelo 65 e a API pública atual aceita apenas tpEmis=1.
• Campos duplicados: se série ou número forem enviados no topo e no payload, os valores devem ser idênticos; a API não escolhe silenciosamente um deles.
• Sem garantia artificial: Validação e transmissão não garantem autorização; a decisão final e as regras fiscais pertencem à SEFAZ ou prefeitura responsável.
• Rastreabilidade: Rejeições e falhas ficam disponíveis no status, histórico de tentativas e eventos do documento.

Leitura prática

• Erros 4xx tendem a indicar payload inválido ou regra de negócio não atendida.
• Rejeições fiscais exigem revisão tributária ou estrutural do documento.
• Falhas transitórias devem ser tratadas pelo fluxo assíncrono e pelos webhooks.

Roteiro rápido para suporte e integração

1. Validar se o token, a empresa e o certificado estao corretos.
2. Checar status, processing_status e requested_action.
3. Ler last_error_code e last_error_message.
4. Se houver retorno SEFAZ, revisar o código e a tradução amigavel.
5. Conferir tentativas, eventos e webhooks no painel da conta.
6. So reenviar quando a causa estiver entendida.