shared¶
Modulo compartilhado: utilitarios, clientes HTTP, validadores e schemas base.
APIError ¶
MCPFiscalError ¶
Bases: Exception
Exceção base para todos os erros do MCP Fiscal Brasil.
NotFoundError ¶
RateLimitError ¶
TimeoutError ¶
ValidationError ¶
XMLParseError ¶
BaseResponse ¶
Bases: BaseModel
Resposta base para todas as ferramentas MCP.
ErrorResponse ¶
format_cnpj ¶
Formata um CNPJ com ou sem mascara.
Se remover_mascara=True, retorna apenas os 14 digitos numericos. Caso contrario, retorna no formato XX.XXX.XXX/XXXX-XX.
format_cpf ¶
Formata um CPF com ou sem mascara.
Se remover_mascara=True, retorna apenas os 11 digitos numericos. Caso contrario, retorna no formato XXX.XXX.XXX-XX.
validate_chave_nfe ¶
Valida uma chave de acesso de NFe/NFCe (44 digitos).
A chave e composta por: cUF(2) + AAMM(4) + CNPJ(14) + mod(2) + serie(3) + nNF(9) + tpEmis(1) + cNF(8) + cDV(1) = 44 digitos.
Verifica apenas o digito verificador (modulo 11).
validate_cnpj ¶
Valida um CNPJ brasileiro.
Aceita formatos com ou sem mascara (XX.XXX.XXX/XXXX-XX ou XXXXXXXXXXXXXX).
validate_cpf ¶
Valida um CPF brasileiro.
Aceita formatos com ou sem mascara (XXX.XXX.XXX-XX ou XXXXXXXXXXX). Retorna False para CPFs com todos os digitos iguais (ex: 111.111.111-11).
constants ¶
Constantes fiscais brasileiras: UFs, CFOP, CST, NCM e códigos SEFAZ.
exceptions ¶
http_client ¶
Cliente HTTP assincrono com retry, backoff e integracao com rate limiter.
FiscalHTTPClient ¶
FiscalHTTPClient(base_url, timeout=DEFAULT_TIMEOUT, max_retries=3, backoff_factor=1.5, rate_limiter=None, headers=None)
Cliente HTTP assincrono com: - Retry automático com backoff exponencial - Integracao com SlidingWindowRateLimiter - Mapeamento de erros HTTP para excecoes fiscais - Logging estruturado
rate_limiter ¶
Rate limiter de janela deslizante por endpoint.
SlidingWindowRateLimiter ¶
Implementa um rate limiter de janela deslizante por chave (ex: endpoint).
Permite configurar N requisicoes por janela de tempo (em segundos). Thread-safe via asyncio.Lock.
schemas ¶
validators ¶
Validadores de documentos fiscais brasileiros (CPF, CNPJ, chave NFe) e caminhos de arquivo.
validar_caminho_arquivo ¶
Normaliza e valida um caminho de arquivo contra path traversal e injeção.
Resolve o caminho para seu valor real (sem .., links simbólicos, etc.)
e rejeita entradas com padrões suspeitos de traversal antes de abrir o
arquivo. Não restringe a um diretório fixo - o operador pode apontar
arquivos em qualquer local do sistema - o objetivo é bloquear injeção de
caminho controlada por dados externos não confiáveis (ex: input de LLM).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Caminho informado pelo chamador (string ou Path). |
required |
label
|
str
|
Rótulo descritivo para mensagens de erro (ex: "Arquivo SPED"). |
'Arquivo'
|
Returns:
| Type | Description |
|---|---|
Path
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
Quando o caminho contém componentes suspeitos de traversal ou se o arquivo não existe ou não é legível. |
validate_cpf ¶
Valida um CPF brasileiro.
Aceita formatos com ou sem mascara (XXX.XXX.XXX-XX ou XXXXXXXXXXX). Retorna False para CPFs com todos os digitos iguais (ex: 111.111.111-11).
validate_cnpj ¶
Valida um CNPJ brasileiro.
Aceita formatos com ou sem mascara (XX.XXX.XXX/XXXX-XX ou XXXXXXXXXXXXXX).
validate_cnpj_alfanumerico ¶
Valida um CNPJ alfanumérico (IN RFB 2.229/2024, vigência jul/2026).
As 12 primeiras posições podem conter letras maiúsculas (A-Z) ou dígitos. As 2 últimas são dígitos verificadores numéricos calculados pelo módulo 11, usando o valor ASCII de cada caractere subtraído de 48.
Esta função NÃO aceita máscaras (pontos, barra, traço) nem letras minúsculas. Aceita CNPJs numéricos puros (14 dígitos sem máscara) como caso especial, pois o algoritmo é compatível com ambos os formatos. Para validar qualquer CNPJ com ou sem máscara, use validate_cnpj_qualquer.
validate_cnpj_qualquer ¶
Valida qualquer CNPJ: detecta se é numérico ou alfanumérico e delega.
CNPJs numéricos (somente dígitos, com ou sem máscara) usam validate_cnpj. CNPJs alfanuméricos (contêm letras A-Z, sem máscara) usam validate_cnpj_alfanumerico.
Tratamento de máscara (comportamento intencional e defensivo): - Este dispatcher remove apenas os separadores padrão de CNPJ: ponto, barra e traço. - Outros caracteres como espaços tornam o input inválido (retorna False). - Isso é diferente de normalizar_cnpj, que usa isalnum() e remove qualquer caractere não alfanumérico. A validação rejeita inputs com formato estranho antes de normalizar, mantendo fronteiras de entrada bem definidas. - Para normalizar antes de validar, use normalizar_cnpj() + validate_cnpj_alfanumerico().
normalizar_cnpj ¶
Remove a máscara de um CNPJ (numérico ou alfanumérico) e normaliza para maiúsculas.
Para CNPJs numéricos: remove pontos, barra e traço. Para CNPJs alfanuméricos (IN RFB 2.229/2024): preserva as letras, remove máscara. Não valida o CNPJ - use validate_cnpj_qualquer antes se necessário.
validate_chave_nfe ¶
Valida uma chave de acesso de NFe/NFCe (44 digitos).
A chave e composta por: cUF(2) + AAMM(4) + CNPJ(14) + mod(2) + serie(3) + nNF(9) + tpEmis(1) + cNF(8) + cDV(1) = 44 digitos.
Verifica apenas o digito verificador (modulo 11).
format_cpf ¶
Formata um CPF com ou sem mascara.
Se remover_mascara=True, retorna apenas os 11 digitos numericos. Caso contrario, retorna no formato XXX.XXX.XXX-XX.
format_cnpj ¶
Formata um CNPJ com ou sem mascara.
Se remover_mascara=True, retorna apenas os 14 digitos numericos. Caso contrario, retorna no formato XX.XXX.XXX/XXXX-XX.
format_chave_nfe ¶
Formata uma chave NFe em grupos de 4 digitos para legibilidade.
xml_utils ¶
Utilitarios para parse e geracao de XML fiscal (NFe, NFSe, SPED).
parse_xml ¶
Parseia XML e retorna o elemento raiz.
Usa parser seguro contra XXE (resolve_entities=False, no_network=True). Lanca XMLParseError em caso de XML invalido.
xpath_text ¶
Extrai o texto do primeiro elemento encontrado pelo XPath.
xpath_all_text ¶
Extrai o texto de todos os elementos encontrados pelo XPath.
element_to_dict ¶
Converte um elemento XML para dicionario Python.
Util para serializar partes de NFe para JSON.
strip_namespace ¶
Remove declaracoes de namespace do XML para facilitar parsing simples.
build_soap_envelope ¶
Monta um envelope SOAP para envio a webservices da SEFAZ.
Retorna a string XML completa com o envelope.
extract_soap_body ¶
Extrai o conteudo do Body de uma resposta SOAP.
Lanca XMLParseError se o envelope for invalido.