Skip to main content

Troubleshooting

Guia de resolução para os erros mais comuns na emissão de NFS-e através do Sistema Nacional (ADN).

Erros de Autenticação​

E4007 - Não foi possível obter o certificado de cliente​

Mensagem: Não foi possível obter o certificado de cliente.

Causa: Falha na autenticação mTLS (mutual TLS). O servidor não conseguiu validar o certificado digital.

Soluções:

  1. Confirme que a senha do certificado está correta
  2. Verifique se o certificado não está expirado
  3. Certifique-se de que o certificado possui a cadeia completa de certificação
# Verificar validade do certificado
import base64
from cryptography import x509
from cryptography.hazmat.backends import default_backend

pfx_b64 = "MIIOOwIBAzCC..."  # Seu certificado
pfx_bytes = base64.b64decode(pfx_b64)

# Se usar openssl para verificar:
# openssl pkcs12 -in certificado.pfx -info -nokeys

Erros de Ambiente​

E0006 - Ambiente diverge​

Mensagem: Ambiente informado diverge do ambiente de recebimento para o qual o emitente enviou a DPS.

Causa: O campo tp_amb não corresponde ao ambiente configurado no conector.

Solução: O conector computa tp_amb automaticamente. Não passe este campo nos parâmetros:

# ERRADO - não passe tp_amb
params = {
    "inf_dps": {
        "tp_amb": "1",  # Remova esta linha
        ...
    }
}

# CORRETO - deixe o conector calcular
params = {
    "inf_dps": {
        # tp_amb será calculado com base no environment da conexão
        ...
    }
}

E0037 - Município inexistente no convênio​

Mensagem: O código do município emissor informado na DPS é inexistente no cadastro de convênio municipal do sistema nacional.

Causa: O município não está conveniado ao Sistema Nacional NFS-e.

Solução: Verifique se o município está conveniado:

result = run_connection_action(
    "adn-nfse",
    "get_by_codigo_municipio_convenio",
    {"codigoMunicipio": "3304557"}
)

if result["data"]["parametros_convenio"]["aderente_ambiente_nacional"] != 1:
    print("Município não está conveniado ao Sistema Nacional!")

Nota: O ambiente producao-restrita (homologação) pode ter mais municípios conveniados do que o ambiente producao.

Erros de Código de Tributação​

E0310 - Código não existe​

Mensagem: O código de tributação nacional informado não existe conforme a lista de serviços nacional do Sistema Nacional NFS-e.

Causa: O código c_trib_nac não é um código válido na lista nacional.

Solução:

  1. Use códigos de 6 dígitos no formato AABBCC
  2. Consulte a lista oficial de códigos
# Códigos válidos (exemplos)
codigos_validos = [
    "010101",  # Análise e desenvolvimento de sistemas
    "010601",  # Consultoria em informática
    "170101",  # Assessoria ou consultoria
    "171901",  # Contabilidade
]

E0312 - Código não administrado pelo município​

Mensagem: O código de tributação nacional informado não está administrado pelo município de incidência do ISSQN na data de competência informada na DPS, conforme a lista de serviços nacional do Sistema Nacional NFS-e.

Causa: O código de tributação existe, mas o município não o parametrizou/administra.

Soluções:

  1. Entre em contato com a prefeitura do município para verificar quais códigos estão habilitados
  2. Use um código diferente que seja administrado pelo município
  3. Aguarde o município fazer a parametrização no Painel Administrativo Municipal
# Consultar alíquota para verificar se código está parametrizado
result = run_connection_action(
    "adn-nfse",
    "get_by_codigo_municipio_by_codigo_servico_by_competencia_aliquota",
    {
        "codigoMunicipio": "3304557",
        "codigoServico": "01.01.01.000",
        "competencia": "2025-12"
    }
)

if result.get("status") == "error" and "404" in result.get("message", ""):
    print("Código não está parametrizado para este município")

Importante: Este erro é muito comum porque a parametrização depende de cada município. Em ambiente de homologação, a disponibilidade de códigos pode ser diferente do ambiente de produção.

Erros de Data/Hora​

E0008 - Data de emissão futura​

Mensagem: A data de emissão da DPS não pode ser posterior à data do seu processamento.

Causa: O campo dh_emi tem data/hora no futuro.

Solução: O conector calcula dh_emi automaticamente. Não passe este campo:

# ERRADO
params = {
    "inf_dps": {
        "dh_emi": "2025-12-31T10:00:00-03:00",  # Data futura
        ...
    }
}

# CORRETO - deixe o conector calcular
params = {
    "inf_dps": {
        # dh_emi será a data/hora atual
        ...
    }
}

E0009 - Data de emissão muito antiga​

Mensagem: A data de emissão da DPS não pode ser anterior a X dias da data atual.

Causa: O campo dh_emi tem data muito antiga.

Solução: Emita a NFS-e com data atual. O limite geralmente é de 10 dias retroativos.

Erros de Formato​

Padrão de campo inválido​

Mensagem: inf_dps..serv..c_serv..c_trib_nac does not match pattern [0-9]{6}

Causa: Campo não segue o formato esperado.

Soluções por campo:

CampoFormatoExemplo
c_trib_nac6 dígitos numéricos010101
c_nbs9 dígitos numéricos115011000
cnpj14 dígitos numéricos12345678000199
cpf11 dígitos numéricos12345678901
c_loc_emi7 dígitos (código IBGE)3304557
serieNumérico1
n_dpsNumérico1

Erros de Comunicação​

RNG6159 - Não foi possível identificar a mensagem​

Mensagem: Não foi possível identificar a mensagem de requisição.

Causa: Problema no formato do payload JSON ou na compressão GZIP/Base64.

Solução: Este erro geralmente indica problema interno do conector. Se ocorrer:

  1. Verifique se todos os campos obrigatórios estão presentes
  2. Confirme que os valores estão em formato string quando esperado
  3. Tente novamente após alguns minutos (pode ser instabilidade da API)

Timeout ou Connection Reset​

Causa: Problemas de rede ou indisponibilidade temporária da API.

Soluções:

  1. Verifique sua conexão com a internet
  2. Tente novamente após alguns minutos
  3. Verifique o status do serviço no portal da NFS-e

Erros de Assinatura Digital​

Assinatura inválida​

Causa: Problema na geração da assinatura XMLDSig.

Soluções:

  1. Verifique se o certificado é válido e não está expirado
  2. Confirme que o certificado possui a chave privada
  3. Certifique-se de que o certificado é ICP-Brasil com "Autenticação do Cliente"

Dicas Gerais​

1. Use ambiente de homologação primeiro​

Configure environment: "producao-restrita" para testar antes de ir para produção.

2. Verifique o município antes de emitir​

# Verificar convênio
result = run_connection_action(
    "adn-nfse",
    "get_by_codigo_municipio_convenio",
    {"codigoMunicipio": codigo_municipio}
)

3. Simplifique o payload​

Comece com o mínimo de campos obrigatórios e vá adicionando conforme necessário.

4. Consulte a documentação oficial​

5. Analise o erro completo​

O campo message do erro contém o JSON completo da resposta da API, incluindo código e descrição detalhada:

import json

result = run_connection_action("adn-nfse", "post_nfse", params)

if result.get("status") == "error":
    message = result.get("message", "")
    if "HTTP 400:" in message:
        json_str = message.split("HTTP 400:")[1].strip()
        error_data = json.loads(json_str)
        for erro in error_data.get("erros", []):
            print(f"Código: {erro['Codigo']}")
            print(f"Descrição: {erro['Descricao']}")