Consultas

Tutorial para consultar NFS-e emitidas e parâmetros municipais através do Sistema Nacional NFS-e (ADN).

Consultar NFS-e por Chave de Acesso

A chave de acesso é um identificador único de 50 caracteres que identifica cada NFS-e emitida.

from abstra.connectors import run_connection_action

result = run_connection_action(
    "adn-nfse",
    "get_nfse_by_chave_acesso",
    {"chaveAcesso": "33251212345678000199550010000000011234567890"}
)

if result.get("status") == "success":
    data = result["data"]
    print(f"NFS-e encontrada!")
    # O XML está disponível em nfse_xml ou nfse_xml_g_zip_b64

Consultar por ID da DPS

Se você tem apenas o ID da DPS (usado na emissão), pode obter a chave de acesso:

result = run_connection_action(
    "adn-nfse",
    "get_dps_by_id",
    {"id": "DPS330455723740545800013000001000000000000001"}
)

if result.get("status") == "success":
    chave_acesso = result["data"].get("chave_acesso")
    print(f"Chave de acesso: {chave_acesso}")

Verificar se NFS-e foi Emitida

Use head_dps_by_id para verificar rapidamente se uma NFS-e já foi emitida para um ID de DPS:

result = run_connection_action(
    "adn-nfse",
    "head_dps_by_id",
    {"id": "DPS330455723740545800013000001000000000000001"}
)

# Retorna status 200 se existe, 404 se não existe

Consultar Parâmetros Municipais

Verificar Convênio do Município

Antes de emitir NFS-e, verifique se o município está conveniado:

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

if result.get("status") == "success":
    params = result["data"]["parametros_convenio"]

    if params["aderente_ambiente_nacional"] == 1:
        print("Município aderente ao ambiente nacional")

    if params["aderente_emissor_nacional"] == 1:
        print("Município permite emissão pelo emissor nacional")

    if params["permite_aproveitameto_de_creditos"]:
        print("Permite aproveitamento de créditos")

Consultar Alíquota de Serviço

Verifique a alíquota de um código de serviço para um município:

result = run_connection_action(
    "adn-nfse",
    "get_by_codigo_municipio_by_codigo_servico_by_competencia_aliquota",
    {
        "codigoMunicipio": "3304557",
        "codigoServico": "01.01.01.000",  # Formato com pontos
        "competencia": "2025-12"
    }
)

if result.get("status") == "success":
    aliquotas = result["data"].get("aliquotas", [])
    for aliquota in aliquotas:
        print(f"Alíquota: {aliquota['aliquota']}%")

Nota: O código de serviço nesta consulta usa formato XX.XX.XX.XXX (com pontos).

Consultar Histórico de Alíquotas

result = run_connection_action(
    "adn-nfse",
    "get_by_codigo_municipio_by_codigo_servico_historicoaliquotas",
    {
        "codigoMunicipio": "3304557",
        "codigoServico": "01.01.01.000"
    }
)

Consultar Regimes Especiais

Verifique os regimes especiais de tributação do município:

result = run_connection_action(
    "adn-nfse",
    "get_by_codigo_municipio_by_codigo_servico_by_competencia_regimes_especiais",
    {
        "codigoMunicipio": "3304557",
        "codigoServico": "01.01.01.000",
        "competencia": "2025-12"
    }
)

Consultar Parâmetros de Retenção

result = run_connection_action(
    "adn-nfse",
    "get_by_codigo_municipio_by_competencia_retencoes",
    {
        "codigoMunicipio": "3304557",
        "competencia": "2025-12"
    }
)

Consultar Benefício Fiscal

result = run_connection_action(
    "adn-nfse",
    "get_by_codigo_municipio_by_numero_beneficio_by_competencia_beneficio",
    {
        "codigoMunicipio": "3304557",
        "numeroBeneficio": "12345",
        "competencia": "2025-12"
    }
)

Distribuição de DF-e

Por NSU (Número Sequencial Único)

Distribui documentos fiscais eletrônicos a partir de um NSU:

result = run_connection_action(
    "adn-nfse",
    "get_dfe_by_nsu",
    {
        "NSU": 12345,
        "lote": True  # Retorna em lote
    }
)

Por Chave de Acesso

Distribui eventos vinculados a uma NFS-e específica:

result = run_connection_action(
    "adn-nfse",
    "get_nfse_by_chave_acesso_eventos",
    {"chaveAcesso": "33251212345678000199550010000000011234567890"}
)

Obter DANFSe

O DANFSe é a representação gráfica (PDF) da NFS-e:

result = run_connection_action(
    "adn-nfse",
    "get_by_chave_acesso",
    {"chaveAcesso": "33251212345678000199550010000000011234567890"}
)

# O resultado contém o PDF em Base64

Códigos de Município IBGE

Alguns códigos IBGE comuns:

Município	Código IBGE
São Paulo	3550308
Rio de Janeiro	3304557
Belo Horizonte	3106200
Brasília	5300108
Salvador	2927408
Fortaleza	2304400
Curitiba	4106902
Recife	2611606
Porto Alegre	4314902
Manaus	1302603

Consulte a tabela completa do IBGE para outros municípios.

Exemplo: Verificar Disponibilidade de Serviço

def verificar_servico_disponivel(codigo_municipio: str, codigo_servico: str):
    """
    Verifica se um código de serviço está disponível para emissão
    em um determinado município.
    """
    from datetime import date

    # 1. Verificar se município está conveniado
    result = run_connection_action(
        "adn-nfse",
        "get_by_codigo_municipio_convenio",
        {"codigoMunicipio": codigo_municipio}
    )

    if result.get("status") != "success":
        return {"disponivel": False, "motivo": "Erro ao consultar convênio"}

    params = result["data"]["parametros_convenio"]
    if params["aderente_ambiente_nacional"] != 1:
        return {"disponivel": False, "motivo": "Município não conveniado"}

    # 2. Verificar se código de serviço está parametrizado
    competencia = date.today().strftime("%Y-%m")
    codigo_formatado = f"{codigo_servico[:2]}.{codigo_servico[2:4]}.{codigo_servico[4:6]}.000"

    result = run_connection_action(
        "adn-nfse",
        "get_by_codigo_municipio_by_codigo_servico_by_competencia_aliquota",
        {
            "codigoMunicipio": codigo_municipio,
            "codigoServico": codigo_formatado,
            "competencia": competencia
        }
    )

    if result.get("status") != "success":
        # 404 significa que não está parametrizado
        if "404" in result.get("message", ""):
            return {
                "disponivel": False,
                "motivo": "Código de serviço não parametrizado para este município"
            }
        return {"disponivel": False, "motivo": "Erro ao consultar alíquota"}

    return {
        "disponivel": True,
        "aliquotas": result["data"].get("aliquotas", [])
    }


# Uso
resultado = verificar_servico_disponivel("3304557", "010101")
if resultado["disponivel"]:
    print("Serviço disponível para emissão!")
else:
    print(f"Indisponível: {resultado['motivo']}")