SDK Python¶

MCP Fiscal Brasil - SDK para integração direta em aplicações Python.

Permite usar todas as funcionalidades fiscais como biblioteca Python, sem precisar rodar o servidor MCP.

Uso básico:

from mcp_fiscal_brasil import FiscalBrasil

fiscal = FiscalBrasil()

# Consultar CNPJ
empresa = await fiscal.consultar_cnpj("00.000.000/0001-91")
print(empresa.razao_social)

# Validar CPF
válido = fiscal.validar_cpf("123.456.789-09")

# Status SEFAZ
status = await fiscal.status_sefaz("SP")

Uso como context manager (recomendado para múltiplas consultas):

async with FiscalBrasil() as fiscal:
    empresa = await fiscal.consultar_cnpj("33.000.167/0001-01")
    simples = await fiscal.consultar_simples("33.000.167/0001-01")

FiscalBrasil ¶

FiscalBrasil()

Interface unificada para consultas fiscais brasileiras.

Encapsula todos os clientes do pacote (CNPJ, NFe, Simples Nacional, eSocial, SPED, NFSe) em um único ponto de entrada.

Pode ser usada como context manager assíncrono para garantir o encerramento correto de recursos de rede:

async with FiscalBrasil() as fiscal:
    empresa = await fiscal.consultar_cnpj("33000167000101")

Ou instanciada diretamente quando o ciclo de vida é gerenciado externamente (ex: variável de módulo em FastAPI):

fiscal = FiscalBrasil()
empresa = await fiscal.consultar_cnpj("33000167000101")

fechar `async` ¶

fechar()

Encerra recursos de rede (conexões HTTP). Opcional quando usado como variável global.

consultar_cnpj `async` ¶

consultar_cnpj(cnpj)

Consulta os dados de um CNPJ na Receita Federal.

Tenta BrasilAPI primeiro; em caso de falha, usa ReceitaWS como fallback automático.

Parameters:

Name	Type	Description	Default
`cnpj`	`str`	CNPJ com ou sem máscara (ex: "33.000.167/0001-01" ou "33000167000101").	required

Returns:

Type	Description
`CNPJResponse`	CNPJResponse com razão social, endereço, CNAE, QSA e mais.

Raises:

Type	Description
`ValueError`	Se o CNPJ for inválido.
`Exception`	Se todas as APIs externas falharem.

Exemplo

empresa = await fiscal.consultar_cnpj("33.000.167/0001-01") print(empresa.razao_social) # "PETROLEO BRASILEIRO S A PETROBRAS"

validar_cnpj ¶

validar_cnpj(cnpj)

Valida o dígito verificador de um CNPJ (offline, sem chamada de API).

Parameters:

Name	Type	Description	Default
`cnpj`	`str`	CNPJ com ou sem máscara.	required

Returns:

Type	Description
`bool`	True se o CNPJ for matematicamente válido, False caso contrário.

Exemplo

fiscal.validar_cnpj("33.000.167/0001-01") # True fiscal.validar_cnpj("11.111.111/1111-11") # False

validar_cpf ¶

validar_cpf(cpf)

Valida o dígito verificador de um CPF (offline, sem chamada de API).

A Receita Federal não disponibiliza API pública para consulta de CPF. Esta validação verifica apenas o cálculo do dígito verificador.

Parameters:

Name	Type	Description	Default
`cpf`	`str`	CPF com ou sem máscara (ex: "529.982.247-25" ou "52998224725").	required

Returns:

Type	Description
`bool`	True se o CPF for matematicamente válido, False caso contrário.

Exemplo

fiscal.validar_cpf("529.982.247-25") # True fiscal.validar_cpf("111.111.111-11") # False (sequência repetida)

consultar_nfe `async` ¶

consultar_nfe(chave)

Consulta os dados de uma NFe pela chave de acesso de 44 dígitos.

Cadeia de fallback automática

BrasilAPI
Portal Nacional NFe (SEFAZ federal)
Dados parciais extraídos da própria chave

Parameters:

Name	Type	Description	Default
`chave`	`str`	Chave de acesso da NFe com 44 dígitos numéricos.	required

Returns:

Type	Description
`NFeResponse`	NFeResponse com emitente, destinatário, itens, totais e situação.

Raises:

Type	Description
`ValueError`	Se a chave de acesso for inválida.

Exemplo

nfe = await fiscal.consultar_nfe("35230112345678901234550010000000011000000018") print(nfe.situacao)

validar_chave_nfe ¶

validar_chave_nfe(chave)

Valida e extrai os campos estruturais de uma chave de acesso NFe/NFCe.

A validação verifica o dígito verificador pelo módulo 11 (offline). A extração decodifica os campos embutidos na chave (UF, CNPJ, série, etc.).

Parameters:

Name	Type	Description	Default
`chave`	`str`	Chave de acesso com 44 dígitos numéricos.	required

Returns:

Type	Description
`dict[str, Any]`	Dicionário com campos extraídos:
`dict[str, Any]`	válida (bool): Se o dígito verificador é correto.
`dict[str, Any]`	uf (str): UF de emissão.
`dict[str, Any]`	ano_mes (str): Ano/mês de emissão no formato MM/AAAA.
`dict[str, Any]`	cnpj_emitente (str): CNPJ do emitente (14 dígitos).
`dict[str, Any]`	modelo (str): Modelo do documento ("55"=NFe, "65"=NFCe).
`dict[str, Any]`	serie (str): Série da nota.
`dict[str, Any]`	número (str): Número da nota fiscal.

Exemplo

info = fiscal.validar_chave_nfe("35230112345678901234550010000000011000000018") print(info["uf"]) # "SP" print(info["cnpj_emitente"]) # "12345678901234"

status_sefaz `async` ¶

status_sefaz(uf, ambiente='producao')

Consulta o status do serviço SEFAZ de uma UF.

Usa BrasilAPI como proxy para o webservice do SEFAZ estadual. Em caso de falha, retorna status "Indisponível".

Parameters:

Name	Type	Description	Default
`uf`	`str`	Sigla do estado (ex: "SP", "RJ", "MG"). Não diferencia maiúsculas.	required
`ambiente`	`str`	"producao" ou "homologacao" (padrão: "producao").	`'producao'`

Returns:

Type	Description
`StatusSEFAZResponse`	StatusSEFAZResponse com status, descrição e código de retorno.

Exemplo

status = await fiscal.status_sefaz("SP") print(status.status) # "Em Operação"

consultar_simples `async` ¶

consultar_simples(cnpj)

Consulta a situação de um CNPJ no Simples Nacional e MEI.

Parameters:

Name	Type	Description	Default
`cnpj`	`str`	CNPJ com ou sem máscara.	required

Returns:

Type	Description
`SimplesStatus`	SimplesStatus com optante_simples, optante_mei e datas de opção/exclusão.

Raises:

Type	Description
`ValueError`	Se o CNPJ for inválido.

Exemplo

simples = await fiscal.consultar_simples("33.000.167/0001-01") print(simples.simples_nacional) # False (Petrobras não é optante) print(simples.mei) # False

analisar_sped `async` ¶

analisar_sped(conteudo, nome_arquivo=None)

Analisa um arquivo SPED e extrai informações estruturais.

Suporta EFD-ICMS/IPI, EFD-Contribuições, ECD e ECF. O arquivo deve ser passado como string (conteúdo completo no formato pipe-delimitado).

Parameters:

Name	Type	Description	Default
`conteudo`	`str`	Conteúdo do arquivo SPED como string.	required
`nome_arquivo`	`str \| None`	Nome do arquivo (opcional, usado apenas para log).	`None`

Returns:

Type	Description
`dict[str, Any]`	Dicionário com:
`dict[str, Any]`	tipo_sped (str): Tipo identificado ("EFD-ICMS-IPI", "EFD-Contribuições", etc.)
`dict[str, Any]`	abertura (dict \| None): Dados do registro 0000 (empresa, CNPJ, UF).
`dict[str, Any]`	resumo (dict): Período, total de registros e contagem por tipo.
`dict[str, Any]`	erros (list[str]): Erros encontrados na estrutura.
`dict[str, Any]`	avisos (list[str]): Avisos sobre o arquivo.

Exemplo

with open("sped.txt") as f: conteudo = f.read() resultado = await fiscal.analisar_sped(conteudo) print(resultado["tipo_sped"]) # "EFD-ICMS-IPI"

portal_nfse `async` ¶

portal_nfse(municipio, uf)

Retorna o portal de consulta de NFSe para um município.

NFSe não possui padrão nacional único; cada município tem seu sistema (ABRASF, ISS.net, Betha, Curitiba, etc.). Este método localiza o portal correto para o município informado e, quando não encontrado, retorna o Portal Nacional ABRASF como alternativa.

Parameters:

Name	Type	Description	Default
`municipio`	`str`	Nome do município (ex: "São Paulo", "Belo Horizonte").	required
`uf`	`str`	Sigla do estado (ex: "SP", "MG").	required

Returns:

Type	Description
`dict[str, str]`	Dicionário com:
`dict[str, str]`	portal_municipio (str): URL do portal de consulta.
`dict[str, str]`	sistema_nfse (str): Sistema utilizado (ABRASF, ISS.net, etc.)
`dict[str, str]`	alternativa (str): Alternativa para integração automatizada.
`dict[str, str]`	status (str): "consulta_manual_necessaria".

Exemplo

portal = await fiscal.portal_nfse("São Paulo", "SP") print(portal["portal_municipio"]) # URL da prefeitura de SP print(portal["sistema_nfse"]) # "ABRASF"

listar_eventos_esocial `async` ¶

listar_eventos_esocial(grupo=None)

Lista os eventos do eSocial, com opção de filtro por grupo.

Parameters:

Name	Type	Description	Default
`grupo`	`str \| None`	Filtrar por grupo do evento. Valores válidos: "Tabelas", "Não Periodicos", "Periodicos", "Exclusao", "Totalizadores". Se None, retorna todos os 45+ eventos catalogados.	`None`

Returns:

Type	Description
`list[dict[str, Any]]`	Lista de dicionários com campos:
`list[dict[str, Any]]`	código (str): Código do evento (ex: "S-2200").
`list[dict[str, Any]]`	nome (str): Nome completo do evento.
`list[dict[str, Any]]`	grupo (str): Grupo ao qual pertence.
`list[dict[str, Any]]`	descrição (str): Descrição do propósito do evento.

Exemplo

eventos = await fiscal.listar_eventos_esocial("Periodicos") for e in eventos: print(f"{e['código']}: {e['nome']}")

consultar_cnpj_sync ¶

consultar_cnpj_sync(cnpj)

Versão síncrona de consultar_cnpj. Útil em contextos não-async (Django, scripts).

Não use dentro de um event loop já ativo (ex: FastAPI, Jupyter). Prefira o método assíncrono nesses casos.

Parameters:

Name	Type	Description	Default
`cnpj`	`str`	CNPJ com ou sem máscara.	required

Returns:

Type	Description
`CNPJResponse`	CNPJResponse com os dados da empresa.

consultar_simples_sync ¶

consultar_simples_sync(cnpj)

Versão síncrona de consultar_simples. Útil em contextos não-async.

Parameters:

Name	Type	Description	Default
`cnpj`	`str`	CNPJ com ou sem máscara.	required

Returns:

Type	Description
`SimplesStatus`	SimplesNacionalResponse com situação no Simples Nacional.

status_sefaz_sync ¶

status_sefaz_sync(uf, ambiente='producao')

Versão síncrona de status_sefaz. Útil em contextos não-async.

Parameters:

Name	Type	Description	Default
`uf`	`str`	Sigla do estado.	required
`ambiente`	`str`	"producao" ou "homologacao".	`'producao'`

Returns:

Type	Description
`StatusSEFAZResponse`	StatusSEFAZResponse com status do serviço.

SDK Python¶

FiscalBrasil ¶

fechar async ¶

consultar_cnpj async ¶

validar_cnpj ¶

validar_cpf ¶

consultar_nfe async ¶

validar_chave_nfe ¶

status_sefaz async ¶

consultar_simples async ¶

analisar_sped async ¶

portal_nfse async ¶

listar_eventos_esocial async ¶

consultar_cnpj_sync ¶

consultar_simples_sync ¶

status_sefaz_sync ¶

fechar `async` ¶

consultar_cnpj `async` ¶

consultar_nfe `async` ¶

status_sefaz `async` ¶

consultar_simples `async` ¶

analisar_sped `async` ¶

portal_nfse `async` ¶

listar_eventos_esocial `async` ¶