Tratamento de Erros

Erros de Provedores (NFS-e)

NFS-e não tem um "SEFAZ único" -- cada município usa um provedor de emissão, e cada provedor tem seu próprio formato de erro. A CentralFiscal repassa a mensagem do provedor sem traduzir; não existe hoje um catálogo interno unificando os códigos de todos os provedores.

💡

Foco atual: Ambiente Nacional (Padrão Nacional/ADN), pra onde os municípios estão migrando. É o formato descrito abaixo em detalhe.

Ambiente Nacional

O ADN responde em JSON. Quando a emissão falha, a mensagem chega em mensagem (string única) ou em erros (lista) -- nesse segundo caso a API concatena as mensagens com "; " antes de devolver pra você.

{
  "status": "REJECTED",
  "mensagem": "DPS.infDPS.serie: valor invalido; DPS.infDPS.dCompet: campo obrigatorio",
  "detalhes": { "...": "payload bruto retornado pelo ADN" }
}

Falhas de infraestrutura (endpoint do ADN não configurado pro município, timeout, mTLS) são diferenciadas de rejeições de negócio -- vêm com NFSE_EMISSAO_FALHOU em vez de um NFSE_REJECTED associado a erro de conteúdo do DPS. Na prática, pro seu ERP, o tratamento é o mesmo: mostre mensagem pro usuário e trate como ERROR/REJECTED conforme o campo status.

Provedores municipais legados (ABRASF)

Municípios que ainda não migraram pro Ambiente Nacional usam o padrão ABRASF (retorno em XML). O formato de erro nesse caso é uma lista de <MensagemRetorno>, cada uma com um código próprio do provedor/prefeitura -- a API concatena como "{código}: {mensagem} ({correção})" por item.

⚠️

Esses códigos são definidos por cada prefeitura/provedor, não por um padrão nacional -- o mesmo código numérico pode significar coisas diferentes em municípios diferentes. Não há tradução nem normalização; trate sempre pelo texto, não pelo código. Este é o padrão legado -- fora do foco atual da API (Ambiente Nacional é a prioridade).

Município sem provedor mapeado

Se o município do prestador ainda não tem nenhum provedor configurado nesta API, a emissão falha antes mesmo de contatar qualquer provedor externo, com NFSE_MUNICIPIO_SEM_PROVEDOR. Não é um erro de rejeição -- é um gap de cobertura; fale com o time se isso acontecer com um município que você precisa.