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_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.

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. BrasilAPI, with partial state coverage
2. National NFe Portal, public lookup without authentication
3. Partial fields extracted from the access key itself

consultar_status_servico async

consultar_status_servico(uf, ambiente='producao')

Look up the SEFAZ service status for a state.

BrasilAPI acts as a proxy for the state SEFAZ webservice.

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.

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.

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.