nfe

Modulo NFe: consulta, validação de chave e status SEFAZ.

NFeResponse

Bases: BaseResponse

Dados de uma NFe consultada.

StatusSEFAZResponse

Bases: BaseResponse

Status do serviço SEFAZ de uma UF.

consultar_nfce async

consultar_nfce(chave_acesso)

Look up NFC-e (Nota Fiscal de Consumidor Eletronica, modelo 65) data by access key.

A NFC-e e a nota do varejo ao consumidor final. A cobertura completa depende do provedor premium opcional cpfcnpj.com.br (pacote 102), habilitado por token.

Parameters:

Name	Type	Description	Default
chave_acesso	str	44 digit NFC-e access key, accepted with or without spaces.	required

Returns:

Type	Description
NFeResponse	NFeResponse with issuer, recipient and totals (layout compartilhado com a NF-e).

Raises:

Type	Description
FiscalValidationError	If the access key is invalid.
FiscalHTTPError	If the upstream provider fails.

consultar_nfe async

consultar_nfe(chave_acesso)

Look up NFe (Nota Fiscal Eletrônica) data by access key.

The access key has 44 digits and is printed on the DANFE document.

Parameters:

Name	Type	Description	Default
chave_acesso	str	44 digit NFe access key, accepted with or without spaces.	required

Returns:

Type	Description
NFeResponse	NFeResponse with issuer, recipient, items and totals.

Raises:

Type	Description
FiscalValidationError	If the access key is invalid.
FiscalNotFoundError	If the NFe is not found.
FiscalHTTPError	If SEFAZ or an upstream API fails.

consultar_status_sefaz async

consultar_status_sefaz(uf)

Look up the current SEFAZ service status for a state.

Checks whether the SEFAZ NFe issuance webservice is operational.

Parameters:

Name	Type	Description	Default
uf	str	State abbreviation, for example 'SP', 'MG' or 'RJ'.	required

Returns:

Type	Description
StatusSEFAZResponse	StatusSEFAZResponse with current status and description.

Raises:

Type	Description
FiscalValidationError	If the state abbreviation is invalid.

validar_chave_nfe async

validar_chave_nfe(chave_acesso)

Validate the format and check digit of an NFe access key.

This does not call external APIs. It only verifies the modulo 11 check digit.

Parameters:

Name	Type	Description	Default
chave_acesso	str	44 digit access key.	required

Returns:

Type	Description
dict[str, object]	Dictionary with validity and decoded fields when valid.

assinatura

Validacao de assinatura digital XMLDSig em documentos NF-e (ICP-Brasil).

AssinaturaResult dataclass

AssinaturaResult(assinatura_valida, motivo=None, titular=None, cnpj_cpf=None, validade_inicio=None, validade_fim=None, ac_emissora=None)

Resultado da validacao de assinatura digital XMLDSig de uma NF-e.

assinatura_valida instance-attribute

assinatura_valida

True se a assinatura criptografica e a integridade do digest forem validas.

motivo class-attribute instance-attribute

motivo = None

Descricao do erro caso assinatura_valida seja False, None se valida.

titular class-attribute instance-attribute

titular = None

CN (Common Name) do certificado assinante, normalmente razao social + CNPJ.

cnpj_cpf class-attribute instance-attribute

cnpj_cpf = None

CNPJ ou CPF extraido do CN do certificado, se presente.

validade_inicio class-attribute instance-attribute

validade_inicio = None

Inicio da validade do certificado.

validade_fim class-attribute instance-attribute

validade_fim = None

Fim da validade do certificado.

ac_emissora class-attribute instance-attribute

ac_emissora = None

DN do emissor (Autoridade Certificadora) do certificado.

validar_assinatura_nfe

validar_assinatura_nfe(xml_content, ca_bundle=None)

Valida a assinatura digital XMLDSig de uma NF-e.

Verifica a integridade do Reference/DigestValue e a assinatura criptografica do elemento Signature presente em infNFe. Extrai dados do certificado assinante.

Parameters:

Name	Type	Description	Default
xml_content	str | bytes	Conteudo XML da NF-e (str ou bytes). Todo XML externo e parseado via parse_xml() (anti-XXE).	required
ca_bundle	str | bytes | None	Opcional. PEM com cadeia ICP-Brasil para validar o emissor do certificado. - str: caminho de arquivo PEM no sistema de arquivos. O arquivo deve existir e ser legivel; caso contrario, levanta FiscalValidationError com mensagem clara. - bytes: conteudo PEM diretamente em memoria. - None: valida a assinatura sem exigir cadeia confiavel (nao falha por ausencia de bundle, mas nao confirma a AC emissora).	None

Returns:

Type	Description
AssinaturaResult	AssinaturaResult com o resultado da validacao e dados do certificado.
AssinaturaResult	NUNCA reporta assinatura invalida como valida.

Raises:

Type	Description
FiscalValidationError	Se ca_bundle for str e o caminho nao existir, ou se o conteudo exceder 1 MB.
XMLParseError	Se o XML for malformado (propagado de parse_xml).

client

NFe lookup client backed by BrasilAPI and the National NFe Portal.

Quando o provedor premium opcional cpfcnpj.com.br esta configurado (token via CPFCNPJ_TOKEN), ele e tentado primeiro na consulta por chave, cobrindo NF-e (modelo 55, pacote 100) e NFC-e (modelo 65, pacote 102) com dados oficiais em tempo real. As fontes gratuitas seguem como fallback. Sem token, o comportamento e identico ao anterior.

NFEClient

Client for NFe lookup flows.

consultar_por_chave async

consultar_por_chave(chave)

Look up NFe data by its 44 digit access key.

Fallback chain

1. cpfcnpj.com.br premium provider, only when a token is configured
2. BrasilAPI, with partial state coverage
3. National NFe Portal, public lookup without authentication
4. Partial fields extracted from the access key itself

consultar_status_servico async

consultar_status_servico(uf, ambiente=None)

Consulta o status real do webservice SEFAZ da UF via NfeStatusServico4 (mTLS).

Exige certificado digital A1 configurado (NFE_CERTIFICADO_PATH / NFE_CERTIFICADO_SENHA) - mTLS é exigência de transporte de todo webservice SEFAZ, inclusive consulta de status. Sem certificado, propaga FiscalConfigurationError; o chamador decide como tratar (api.py, por exemplo, omite a UF da resposta em vez de fabricar um status falso).

danfe

Geracao de DANFE em PDF a partir de XML de NF-e.

Suporte a modelo 55 (NF-e) com namespace do portal fiscal (portalfiscal.inf.br/nfe). Modelo 65 (NFC-e) nao e suportado na versao 1.0.0 da lib brazilfiscalreport.

Seguranca: - Todo XML externo e parseado via parse_xml() (resolve_entities=False, no_network=True) antes de ser entregue a lib brazilfiscalreport. Isso impede XXE e billion-laughs mesmo quando o XML vem de fonte nao confiavel (usuario ou LLM). - A lib brazilfiscalreport usa xml.etree internamente (sem protecao XXE propria); a validacao previa via lxml com _SAFE_PARSER e a barreira de seguranca.

DanfeGenerationError

DanfeGenerationError(field, value, reason)

Bases: FiscalValidationError

Erro ao gerar o DANFE.

DanfeResult

Bases: BaseModel

Resultado da geracao de DANFE em PDF.

pdf_base64 instance-attribute

pdf_base64

Conteudo do PDF codificado em base64.

modelo instance-attribute

modelo

Modelo do documento fiscal: 55 para NF-e.

nome_arquivo instance-attribute

nome_arquivo

Nome de arquivo sugerido para o PDF, incluindo a chave de acesso.

paginas class-attribute instance-attribute

paginas = None

Numero de paginas do PDF (disponivel quando calculavel).

chave_acesso instance-attribute

chave_acesso

Chave de acesso de 44 digitos do documento.

numero class-attribute instance-attribute

numero = None

Numero da nota fiscal extraido do XML.

serie class-attribute instance-attribute

serie = None

Serie da nota fiscal extraida do XML.

gerar_danfe

gerar_danfe(xml_content)

Gera o DANFE em PDF a partir do XML de uma NF-e (modelo 55).

Suporta apenas modelo 55. Modelo 65 (NFC-e) nao e suportado pela brazilfiscalreport 1.0.0 - sera suportado em versao futura da lib.

SEGURANCA: o XML e validado via parse_xml() (anti-XXE) antes de ser entregue a lib brazilfiscalreport, que usa xml.etree sem protecao propria.

O XML pode conter ou nao o involucro de protocolo . Quando o XML nao tiver protocolo de autorizacao, o DANFE e gerado sem o numero de protocolo no rodape (comportamento identico ao da lib).

NAMESPACE OBRIGATORIO: o XML deve conter o namespace do portal fiscal (http://www.portalfiscal.inf.br/nfe) para que a lib possa processar o XML.

Parameters:

Name	Type	Description	Default
xml_content	str | bytes	XML completo da NF-e como string ou bytes. Deve conter o namespace do portal fiscal (http://www.portalfiscal.inf.br/nfe). Aceita XML com ou sem involucro .	required

Returns:

Type	Description
DanfeResult	DanfeResult com o PDF em base64, metadados do documento e nome de
DanfeResult	arquivo sugerido.

Raises:

Type	Description
DanfeGenerationError	Se o XML for invalido, o modelo nao for suportado (65 = nao suportado, ver nota acima), o namespace estiver ausente, ou a geracao do PDF falhar.
XMLParseError	Se o XML estiver malformado (propagado de parse_xml).

distribuicao

Distribuicao de NF-e via NFeDistribuicaoDFe (Ambiente Nacional, mTLS A1).

Suporta os tres modos: - distNSU: busca incremental por ultimo NSU - consNSU: consulta por NSU especifico - consChNFe: consulta por chave de acesso de 44 digitos

Tambem oferece manifestacao do destinatario (eventos 210200/210210/210220/210240).

SEGURANCA: - Senha do .pfx e chave privada NUNCA aparecem em logs, excecoes ou disco persistente. - Arquivos PEM temporarios (quando necessarios) sao criados com permissao 0600 e apagados no bloco finally. - XML externo sempre parseado via parse_xml() (anti-XXE).

DocumentoDistribuicao dataclass

DocumentoDistribuicao(nsu, tipo, schema, chave, resumo, dados_completos)

Documento retornado pela consulta de distribuicao NF-e.

nsu instance-attribute

nsu

Numero Sequencial Unico do documento.

tipo instance-attribute

tipo

Tipo do schema: resNFe (resumo), procNFe ou nfeProc (completo), etc.

schema instance-attribute

schema

Nome do schema (ex: resNFe_v1.01.xsd, procNFe_v4.00.xsd).

chave instance-attribute

chave

Chave de acesso de 44 digitos, se disponivel no documento.

resumo instance-attribute

resumo

Campos principais do resNFe (emitente, valor, situacao), se for resumo.

O campo 'situacao' corresponde a cSitNFe da SEFAZ e pode ser None quando o resNFe nao trouxer esse elemento (nao confundir com digVal, que e o digest).

dados_completos instance-attribute

dados_completos

NFeResponse parseado via parse_nfe_xml, se for procNFe/nfeProc.

DistribuicaoResult dataclass

DistribuicaoResult(ultimo_nsu, max_nsu, documentos)

Resultado de uma consulta NFeDistribuicaoDFe.

ultimo_nsu instance-attribute

ultimo_nsu

Ultimo NSU retornado pela SEFAZ nesta consulta.

max_nsu instance-attribute

max_nsu

Maior NSU disponivel para o ator consultante.

documentos instance-attribute

documentos

Lista de documentos retornados.

ManifestacaoResult dataclass

ManifestacaoResult(sucesso, chave, tipo_evento, numero_protocolo, codigo_retorno, motivo)

Resultado de uma manifestacao do destinatario.

sucesso instance-attribute

sucesso

True se o evento foi recebido pela SEFAZ com sucesso.

chave instance-attribute

chave

Chave de acesso da NF-e manifestada.

tipo_evento instance-attribute

tipo_evento

Codigo do evento (ex: 210200).

numero_protocolo instance-attribute

numero_protocolo

Numero do protocolo retornado pela SEFAZ.

codigo_retorno instance-attribute

codigo_retorno

cStat retornado pela SEFAZ (135 = sucesso).

motivo instance-attribute

motivo

xMotivo retornado pela SEFAZ.

baixar_nfe_distribuicao async

baixar_nfe_distribuicao(caminho_certificado, senha, cnpj_cpf, uf, modo='distNSU', ultimo_nsu='0', nsu=None, chave=None, ambiente='producao', timeout=30.0)

Baixa documentos fiscais via NFeDistribuicaoDFe com mTLS usando certificado A1 local.

A Ciencia da Operacao (evento 210200) e pre-requisito para a SEFAZ liberar o XML completo (procNFe) ao destinatario. Sem ela, apenas o resNFe (resumo) e disponibilizado. Use manifestar_nfe() apos baixar o resNFe para registrar a ciencia e depois consultar novamente para obter o procNFe completo.

Parameters:

Name	Type	Description	Default
caminho_certificado	str	Caminho absoluto para o arquivo .pfx ou .p12.	required
senha	str	Senha do certificado. NUNCA logada ou incluida em excecoes.	required
cnpj_cpf	str	CNPJ (14 dig) ou CPF (11 dig) do autor da consulta.	required
uf	str	Codigo da UF do autor (ex: "35" para SP ou "SP").	required
modo	Literal['distNSU', 'consNSU', 'consChNFe']	"distNSU" (incremental), "consNSU" (NSU especifico), "consChNFe" (por chave).	'distNSU'
ultimo_nsu	str | int	Ultimo NSU recebido (modo distNSU). Default 0 = busca todos.	'0'
nsu	str | int | None	NSU especifico a consultar (modo consNSU).	None
chave	str | None	Chave de acesso de 44 digitos (modo consChNFe).	None
ambiente	Ambiente	"producao" ou "homologacao".	'producao'
timeout	float	Timeout HTTP em segundos.	30.0

Returns:

Type	Description
DistribuicaoResult	DistribuicaoResult com documentos e NSUs.

Raises:

Type	Description
FiscalValidationError	Inputs invalidos ou certificado invalido/senha errada.
FiscalHTTPError	Falha HTTP ou erro retornado pela SEFAZ.

manifestar_nfe async

manifestar_nfe(chave, tipo_evento, caminho_certificado, senha, cnpj_cpf, uf='91', numero_sequencia=1, justificativa=None, ambiente='producao', timeout=30.0)

Manifesta o destinatario em uma NF-e via NFeRecepcaoEvento.

IMPORTANTE: A Ciencia da Operacao (210200) e pre-requisito obrigatorio para a SEFAZ liberar o XML completo (procNFe) ao destinatario. Sem registrar a ciencia primeiro, somente o resNFe (resumo) fica disponivel na distribuicao.

Eventos disponiveis: - 210200: Ciencia da Operacao (sem justificativa) - 210210: Confirmacao da Operacao (sem justificativa) - 210220: Desconhecimento da Operacao (sem justificativa) - 210240: Operacao nao Realizada (justificativa OBRIGATORIA, min. 15 chars)

Parameters:

Name	Type	Description	Default
chave	str	Chave de acesso de 44 digitos da NF-e.	required
tipo_evento	str	Codigo do evento (ex: "210200").	required
caminho_certificado	str	Caminho absoluto para o arquivo .pfx/.p12.	required
senha	str	Senha do certificado A1. NUNCA logada ou incluida em excecoes.	required
cnpj_cpf	str	CNPJ (14 dig) ou CPF (11 dig) do destinatario.	required
uf	str	UF do autor (default "91" = AN - Ambiente Nacional).	'91'
numero_sequencia	int	Numero sequencial do evento para esta chave (1 a 20).	1
justificativa	str | None	Obrigatoria para 210240 (min. 15 chars). Ignorada nos demais.	None
ambiente	Ambiente	"producao" ou "homologacao".	'producao'
timeout	float	Timeout HTTP em segundos.	30.0

Returns:

Type	Description
ManifestacaoResult	ManifestacaoResult com protocolo e codigo de retorno da SEFAZ.

Raises:

Type	Description
FiscalValidationError	Inputs invalidos, certificado invalido ou justificativa ausente.
FiscalHTTPError	Falha HTTP ou erro da SEFAZ.

documento

Tool de parse de documento NF-e/NFC-e a partir de XML bruto.

DocumentoParseError

DocumentoParseError(field, value, reason)

Bases: FiscalValidationError

Erro de validacao ao fazer parse de XML de documento fiscal.

ParseNFeDocumentoResult

Bases: BaseModel

Resultado do parse de documento NF-e/NFC-e.

parse_nfe_documento

parse_nfe_documento(xml_content)

Parseia o XML completo de uma NF-e ou NFC-e e retorna NFeResponse.

Aceita XMLs com ou sem o involucro de protocolo , com ou sem namespace do portal fiscal. Extrai a chave de acesso automaticamente do atributo Id do elemento .

Parameters:

Name	Type	Description	Default
xml_content	str | bytes	XML completo da NF-e ou NFC-e como string ou bytes. Pode conter o involucro ou ser a NF-e nua.	required

Returns:

Type	Description
NFeResponse	NFeResponse com todos os dados do documento fiscal.

Raises:

Type	Description
DocumentoParseError	Se o XML nao for uma NF-e/NFC-e valida ou a chave extraida nao tiver 44 digitos.
XMLParseError	Se o XML estiver malformado (lxml nao conseguir parsear).

schemas

Schemas para dados de NFe.

EnderecoNFe

Bases: Endereco

Endereco especifico do modelo NFe (com CNPJ/CPF).

ItemNFe

Bases: BaseModel

Item (produto ou serviço) de uma NFe.

TotaisNFe

Bases: BaseModel

Totais da NFe.

TotaisReformaNFe

Bases: BaseModel

Totais dos tributos da Reforma Tributária na NF-e (NT 2025.002 - Grupo W03/IBSCBSTot).

NFeResponse

Bases: BaseResponse

Dados de uma NFe consultada.

StatusSEFAZResponse

Bases: BaseResponse

Status do serviço SEFAZ de uma UF.

status_sefaz

Consulta real de status operacional das SEFAZ via NfeStatusServico4.

Cada UF delega a autorizacao de NF-e a um de tres grupos de webservice: - Estado com estrutura propria (AM, BA, GO, MG, MS, MT, PE, PR, RS, SP). - SVRS (Sefaz Virtual do Rio Grande do Sul): AC, AL, AP, CE, DF, ES, PA, PB, PI, RJ, RN, RO, RR, SC, SE, TO. - SVAN (Sefaz Virtual do Ambiente Nacional): MA.

Fonte dos endpoints: config publica mantida pelo projeto sped-nfe (nfephp-org/sped-nfe, storage/wsnfe_4.00_mod55.xml), conferida URL por URL contra o arquivo atual do repositorio antes de aceitar. Uma divergencia real foi corrigida durante essa conferencia: RS tem webservice proprio (nfe.sefazrs.rs.gov.br), distinto do SVRS (nfe.svrs.rs.gov.br, que RS opera para OUTRAS UFs sem infraestrutura propria) - RS nao deve ser tratado como membro do grupo SVRS. Todas as chamadas exigem mTLS com certificado A1 (nao ha consulta de status sem certificado - e uma exigencia da camada de transporte dos webservices SEFAZ, nao apenas de operacoes que gravam dados).

StatusSefazReal dataclass

StatusSefazReal(uf, status, codigo, descricao, data_recebimento, tempo_medio_ms)

Resultado de uma consulta real de status a um webservice SEFAZ.

StatusCertificado dataclass

StatusCertificado(configurado, ambiente, cnpj=None, titular=None, validade_fim=None, valido=None, erro=None)

Estado do certificado digital A1 configurado no servidor fiscal.

consultar_status_real async

consultar_status_real(uf, caminho_certificado, senha, ambiente='producao', timeout=15.0)

Consulta o status real do webservice SEFAZ de uma UF via NfeStatusServico4.

Requer certificado digital A1 configurado (mTLS e exigencia de transporte de todos os webservices SEFAZ, incluindo consulta de status).

Raises:

Type	Description
FiscalConfigurationError	certificado digital A1 nao configurado.
FiscalValidationError	UF sem endpoint mapeado, ou certificado invalido (senha errada, arquivo corrompido).
FiscalHTTPError	falha de rede ou cStat de rejeicao inesperado.

obter_status_certificado

obter_status_certificado(caminho_certificado, senha, ambiente)

Retorna metadados do certificado A1 configurado, sem expor a chave privada.

Usado pelo endpoint GET /v1/fiscal/certificado/status: o chamador so ve "configurado / titular / validade", nunca o arquivo ou a senha.

tools

MCP tools for NFe lookups and validation.

NFeValidationError

NFeValidationError(field, value, reason)

Bases: FiscalValidationError, ValidationError

Validation error compatible with both core and legacy exception hierarchies.

consultar_nfe async

consultar_nfe(chave_acesso)

Look up NFe (Nota Fiscal Eletrônica) data by access key.

The access key has 44 digits and is printed on the DANFE document.

Parameters:

Name	Type	Description	Default
chave_acesso	str	44 digit NFe access key, accepted with or without spaces.	required

Returns:

Type	Description
NFeResponse	NFeResponse with issuer, recipient, items and totals.

Raises:

Type	Description
FiscalValidationError	If the access key is invalid.
FiscalNotFoundError	If the NFe is not found.
FiscalHTTPError	If SEFAZ or an upstream API fails.

consultar_nfce async

consultar_nfce(chave_acesso)

Look up NFC-e (Nota Fiscal de Consumidor Eletronica, modelo 65) data by access key.

A NFC-e e a nota do varejo ao consumidor final. A cobertura completa depende do provedor premium opcional cpfcnpj.com.br (pacote 102), habilitado por token.

Parameters:

Name	Type	Description	Default
chave_acesso	str	44 digit NFC-e access key, accepted with or without spaces.	required

Returns:

Type	Description
NFeResponse	NFeResponse with issuer, recipient and totals (layout compartilhado com a NF-e).

Raises:

Type	Description
FiscalValidationError	If the access key is invalid.
FiscalHTTPError	If the upstream provider fails.

validar_chave_nfe async

validar_chave_nfe(chave_acesso)

Validate the format and check digit of an NFe access key.

This does not call external APIs. It only verifies the modulo 11 check digit.

Parameters:

Name	Type	Description	Default
chave_acesso	str	44 digit access key.	required

Returns:

Type	Description
dict[str, object]	Dictionary with validity and decoded fields when valid.

consultar_status_sefaz async

consultar_status_sefaz(uf)

Look up the current SEFAZ service status for a state.

Checks whether the SEFAZ NFe issuance webservice is operational.

Parameters:

Name	Type	Description	Default
uf	str	State abbreviation, for example 'SP', 'MG' or 'RJ'.	required

Returns:

Type	Description
StatusSEFAZResponse	StatusSEFAZResponse with current status and description.

Raises:

Type	Description
FiscalValidationError	If the state abbreviation is invalid.

xml_parser

Parser de XML de NFe (versão 4.00).

extrair_chave_nfe

extrair_chave_nfe(xml_content)

Extrai a chave de acesso de 44 digitos do atributo Id do infNFe.

Remove o prefixo "NFe" se presente. Retorna None se o elemento infNFe nao for encontrado ou se o Id nao contiver 44 digitos.

Parameters:

Name	Type	Description	Default
xml_content	str | bytes	Conteudo XML da NF-e ou NFC-e.	required

Returns:

Type	Description
str | None	Chave de 44 digitos ou None se nao encontrada.

extrair_modelo_nfe

extrair_modelo_nfe(xml_content)

Extrai o codigo de modelo do documento fiscal (55=NF-e, 65=NFC-e) do XML.

Retorna 55 como padrao quando o elemento / nao for encontrado ou contiver valor nao numerico.

Parameters:

Name	Type	Description	Default
xml_content	str | bytes	Conteudo XML do documento fiscal.	required

Returns:

Type	Description
int	Numero do modelo (55 ou 65 tipicamente).

parse_nfe_xml

parse_nfe_xml(xml_content, chave)

Parseia o XML de uma NFe e retorna NFeResponse.

Suporta NFe versão 4.00 com namespace do portal fiscal.