nfse¶
Modulo NFSe: consulta de Notas Fiscais de Servico Eletronicas.
consultar_nfse
async
¶
Consulta dados de uma NFSe (Nota Fiscal de Serviço Eletrônica).
IMPORTANTE: NFSe não possui padrão nacional. Cada município tem seu próprio sistema (ABRASF, ISS.net, Betha, Curitiba, etc.). Esta ferramenta fornece orientações sobre como consultar a NFSe no município informado.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
numero
|
str
|
Número da NFSe |
required |
municipio
|
str
|
Nome do município (ex: 'São Paulo', 'Belo Horizonte') |
required |
uf
|
str
|
Sigla do estado (ex: 'SP', 'MG') |
required |
cnpj_prestador
|
str | None
|
CNPJ do prestador de serviço (opcional) |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
Dicionário com orientações de consulta para o município. |
circuit_breaker ¶
Circuit breaker para a API Nacional NFS-e (ADN).
Protege contra falhas de disponibilidade da ADN (5xx, timeout, erro de rede), que sao representadas por NFSeNacionalUnavailableError. Respostas de negocio como 404 (nota nao encontrada) nao contam como falha de disponibilidade.
Estados: - CLOSED: circuito fechado, chamadas passam normalmente. - OPEN: circuito aberto, chamadas sao curto-circuitadas sem tocar a rede. - HALF_OPEN: cooldown expirou, permite 1 tentativa de teste. - Sucesso -> CLOSED (zera contadores). - Falha -> OPEN (cooldown reinicia).
CircuitState ¶
Bases: Enum
Estados possiveis do circuit breaker.
CircuitBreaker ¶
CircuitBreaker(failure_threshold=_DEFAULT_FAILURE_THRESHOLD, window_seconds=_DEFAULT_WINDOW_SECONDS, cooldown_seconds=_DEFAULT_COOLDOWN_SECONDS)
Circuit breaker de tres estados para servicos externos com falhas transientes.
Uso tipico
cb = CircuitBreaker() if cb.is_open: raise NFSeNacionalUnavailableError("circuito aberto") try: resultado = await _chamar_api() cb.record_success() except NFSeNacionalUnavailableError: cb.record_failure() raise
record_failure ¶
Registra uma falha de disponibilidade e abre o circuito se necessario.
Em HALF_OPEN: qualquer falha reabre o circuito imediatamente. Em OPEN: sem efeito (circuito ja esta aberto). Em CLOSED: incrementa contador; abre o circuito ao atingir o limiar.
record_success ¶
Registra uma requisicao bem-sucedida.
Em HALF_OPEN: fecha o circuito e zera todos os contadores. Em CLOSED/OPEN: sem efeito significativo (nao altera estado).
client ¶
Cliente para a API Nacional NFS-e (Sistema Nacional NFS-e - adn.nfse.gov.br).
IMPORTANTE: A API Nacional exige certificado digital ICP-Brasil com mTLS. Sem certificado configurado, todas as chamadas retornam None (nota nao encontrada) ou levantam NFSeNacionalUnavailableError (5xx, timeout, falha de rede).
Referência: https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/apis-prod-restrita-e-producao
NFSeNacionalUnavailableError ¶
Bases: RuntimeError
Levantada quando a API Nacional NFS-e está indisponível (5xx, timeout, rede).
Distinto de retorno None (404 - nota não encontrada), esta exceção sinaliza que o serviço está temporariamente inacessível e o fallback deve ser acionado com motivo de indisponibilidade.
NFSeNacionalClient ¶
Cliente para consulta de NFS-e na API Nacional (adn.nfse.gov.br).
Contratos: - Retorna None quando a nota não é encontrada (HTTP 404). - Levanta NFSeNacionalUnavailableError para 5xx, timeout e erros de rede.
Isso permite que a camada superior distinga "nota não encontrada" de "API indisponível" ao montar o api_nacional_motivo no fallback.
Circuit breaker integrado: - Abre após 5 falhas de disponibilidade em janela de 60s. - Cooldown de 120s antes do half-open (1 tentativa de teste). - Respostas 404 nao contam como falha de disponibilidade.
consultar_por_chave
async
¶
Consulta uma NFS-e pela chave de acesso.
Endpoint: GET /nfse/{chaveAcesso}
A chave é codificada com urllib.parse.quote para evitar injecao de caracteres de controle de rota (/, ?, #) no segmento de URL.
Retorna None se a nota não for encontrada (HTTP 404). Levanta NFSeNacionalUnavailableError se a API estiver indisponível ou se o circuit breaker estiver aberto.
tools ¶
Ferramentas MCP para NFSe.
consultar_nfse
async
¶
Consulta dados de uma NFSe (Nota Fiscal de Serviço Eletrônica).
IMPORTANTE: NFSe não possui padrão nacional. Cada município tem seu próprio sistema (ABRASF, ISS.net, Betha, Curitiba, etc.). Esta ferramenta fornece orientações sobre como consultar a NFSe no município informado.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
numero
|
str
|
Número da NFSe |
required |
municipio
|
str
|
Nome do município (ex: 'São Paulo', 'Belo Horizonte') |
required |
uf
|
str
|
Sigla do estado (ex: 'SP', 'MG') |
required |
cnpj_prestador
|
str | None
|
CNPJ do prestador de serviço (opcional) |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
Dicionário com orientações de consulta para o município. |