Skip to main content

NFS-e Nacional (ADN)

O conector ADN NFS-e permite a integração com o Sistema Nacional de NFS-e (Nota Fiscal de Serviço Eletrônica), gerenciado pela Receita Federal em parceria com os municípios brasileiros. Este sistema padroniza a emissão de NFS-e em todo o território nacional.

Configuração​

Para utilizar este conector, você precisará de um Certificado Digital (modelo A1 ou A3) válido emitido por autoridade certificadora ICP-Brasil.

CampoDescrição
EnvironmentAmbiente de execução: producao ou producao-restrita (homologação).
Certificate (PFX/P12)O arquivo do seu certificado digital em Base64.
Certificate PasswordA senha para desbloquear o certificado digital.

Nota: O conector detecta automaticamente a versão do leiaute e o tipo de ambiente (tp_amb) com base na configuração de environment:

  • producao-restrita: Usa versao="1.01" e tp_amb="2"
  • producao: Usa versao="1.00" e tp_amb="1"

Municípios Conveniados​

Nem todos os municípios brasileiros estão conveniados ao Sistema Nacional NFS-e. Antes de utilizar o conector, verifique se o município está aderente consultando a ação get_by_codigo_municipio_convenio.

from abstra.connectors import run_connection_action

# Verificar se município está conveniado
result = run_connection_action(
    "adn-nfse",
    "get_by_codigo_municipio_convenio",
    {"codigoMunicipio": "3304557"}  # Rio de Janeiro
)

if result["data"]["parametros_convenio"]["aderente_ambiente_nacional"] == 1:
    print("Município está conveniado!")

Ações Principais​

post_nfse​

Emite uma NFS-e de forma síncrona a partir de uma DPS (Declaração de Prestação de Serviços).

Campos computados automaticamente:

  • id - ID da DPS (formato: DPS + código município + tipo insc. federal + inscrição federal + série + número)
  • tp_amb - Tipo de ambiente (1=produção, 2=homologação)
  • versao - Versão do leiaute
  • dh_emi - Data/hora de emissão
  • d_compet - Data de competência

get_by_codigo_municipio_convenio​

Consulta os parâmetros do convênio de um município.

get_nfse_by_chave_acesso​

Consulta uma NFS-e pela chave de acesso (50 posições).

get_dps_by_id​

Retorna a chave de acesso da NFS-e a partir do ID da DPS.

post_nfse_by_chave_acesso_eventos​

Registra eventos na NFS-e (cancelamento, substituição, etc.).

Estrutura do XML​

O conector gera automaticamente o XML da DPS assinado digitalmente. A estrutura segue o padrão definido nos schemas XSD da Sefin Nacional:

  • Namespace: http://www.sped.fazenda.gov.br/nfse
  • Elemento raiz: <DPS>
  • Elemento assinado: <infDPS> (referenciado pelo atributo Id)
  • Algoritmos: RSA-SHA1 para assinatura, SHA1 para digest

Compressão​

Os XMLs são comprimidos com GZIP e codificados em Base64 antes do envio, conforme especificação da API.

Observações Importantes​

  1. Código de Tributação Nacional (cTribNac): Deve ser um código de 6 dígitos válido e administrado pelo município de incidência do ISSQN. Consulte a lista de serviços nacional.

  2. Parametrização Municipal: Cada município deve parametrizar os serviços que administra no Painel Administrativo Municipal. Se um código de serviço não estiver parametrizado, a emissão será rejeitada com erro E0312.

  3. Certificado Digital: Use certificado A1 (arquivo PFX) para melhor compatibilidade. Certificados com algoritmos legados (RC2-CBC) são suportados através de conversão automática via OpenSSL.