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.

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.

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.

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

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.