Catálogo de ferramentas

O servidor MCP expõe 21 ferramentas: 13 gratuitas (sem chave) e 8 com chave. Esta página é gerada a partir do próprio servidor (o mesmo tools/list que o seu cliente MCP recebe) — o snapshot bruto está em /docs/mcp/tools.json.

Gratuitas · offline (sem chave, sem rede)

Puro cálculo local — o dado nunca sai do processo. Ideal para validar em lote.

Interstate ICMS aliquot by UF pair (offline)

Ferramenta: nfeio_consultar_aliquota_icms · somente leitura · offline

Retorna a alíquota INTERESTADUAL padrão de ICMS entre duas UFs pela regra da Resolução do Senado Federal nº 22/1989 (7% ou 12%), 100% offline. Escopo deliberadamente limitado ao interestadual.

Regra: 7% quando a origem é Sul/Sudeste (exceto ES) e o destino é Norte/Nordeste/Centro-Oeste ou ES; 12% nos demais casos interestaduais. Operação intraestadual (origem = destino) devolve operacao 'intraestadual' e aliquota_interestadual null.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
uf_origem	string	sim	UF de origem da operação (sigla de 2 letras, ex.: 'SP', 'RJ'). Normalizada para maiúsculas; deve ser uma das 27 UFs.
uf_destino	string	sim	UF de destino da operação (sigla de 2 letras, ex.: 'RJ', 'BA'). Normalizada para maiúsculas; deve ser uma das 27 UFs.

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Retorna a alíquota INTERESTADUAL padrão de ICMS entre duas UFs pela regra da Resolução do Senado Federal nº 22/1989 (7% ou 12%), 100% offline. Escopo deliberadamente limitado ao interestadual.

Regra: 7% quando a origem é Sul/Sudeste (exceto ES) e o destino é Norte/Nordeste/Centro-Oeste ou ES; 12% nos demais casos interestaduais. Operação intraestadual (origem = destino) devolve operacao 'intraestadual' e aliquota_interestadual null.

Use when:
  - Estimar a alíquota interestadual padrão de uma operação entre UFs, ou confirmar que uma operação é intraestadual.

Do NOT use when:
  - Você precisa da alíquota INTERNA da UF, do DIFAL, do FECP, de ST, da alíquota de 4% de importados ou da alíquota por produto — nada disso é coberto (não há fonte oficial machine-readable estável da interna; ela varia por UF/produto e muda com frequência). Para o valor fiscal definitivo, use a emissão (que consome a chave) e a legislação da UF.

Args:
  - uf_origem (string, obrigatório): sigla da UF (allowlist das 27).
  - uf_destino (string, obrigatório): sigla da UF (allowlist das 27).

Returns JSON:
  {
    "uf_origem": string,
    "uf_destino": string,
    "operacao": "interestadual" | "intraestadual",
    "aliquota_interestadual": 7 | 12 | null,   // null em intraestadual
    "atualizado_em": string,
    "fonte": string,
    "observacao": string   // delimita o escopo (só interestadual)
  }

Errors:
  - uf_origem ou uf_destino fora das 27 UFs → erro de validação, sem rede.

Validate & decode NFe access key (offline)

Ferramenta: nfeio_validar_chave_nfe · somente leitura · offline

Validate the check digit (cDV) of a Brazilian NFe/NFC-e access key by mod-11 (NT 2011.002) AND decode its positional layout, fully offline — no network, no NFE.io API key.

This is ARITHMETIC + STRUCTURAL validation, NOT a SEFAZ query. valido: true means only that the 44th digit matches mod-11 — it does NOT mean the invoice exists, was authorized, or is not cancelled. The decoded fields (modelo, série, tpEmis, ...) are positional and informative; they do not imply an authorized document. There is no download of XML/DANFE and no SEFAZ consultation here (those require credentials).

Parâmetros

Campo	Tipo	Obrigatório	Descrição
chave	string	sim	44-digit NFe/NFC-e access key (chave de acesso) to validate and decode. Accepts with or without separators (spaces, dots) — non-digits are stripped before validation. Example: '3520 0714 2001 6600 0187 5500 1000 0000 0710 0000 0077'.

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Validate the check digit (cDV) of a Brazilian NFe/NFC-e access key by mod-11 (NT 2011.002) AND decode its positional layout, fully offline — no network, no NFE.io API key.

This is ARITHMETIC + STRUCTURAL validation, NOT a SEFAZ query. `valido: true` means only that the 44th digit matches mod-11 — it does NOT mean the invoice exists, was authorized, or is not cancelled. The decoded fields (modelo, série, tpEmis, ...) are positional and informative; they do not imply an authorized document. There is no download of XML/DANFE and no SEFAZ consultation here (those require credentials).

Use when:
  - You need to reject a corrupted/mistyped access key before using it.
  - You want to read where a key was issued from (UF, emitter CNPJ, model, series, number) for diagnostics.

Do NOT use when:
  - You need the invoice status at the SEFAZ (authorized/cancelled) or its XML/DANFE — not available offline.

Args:
  - chave (string, required): 44-digit access key, with or without separators.

Returns JSON with shape:
  {
    "chave_formatada": string | null,  // grouped in blocks of 4 when 44 digits, else null
    "valido": boolean,                 // dv_ok (the 44th digit checks out)
    "dv_ok": boolean,
    "normalizado": string,             // digits-only value
    "decodificado": {                  // present when 44 digits (even if dv_ok is false); null otherwise
      "uf": string | null,             // UF sigla from the cUF (IBGE); null if cUF unknown
      "cuf": string, "aamm": string, "cnpj": string, "modelo": string,
      "serie": string, "numero": string, "tp_emis": string,
      "codigo_numerico": string, "cdv": string
    } | null,
    "motivo": string | null
  }

Errors:
  - A malformed key is NOT an error: it returns valido:false with a motivo. Only a schema-invalid call (missing/empty chave) is a tool error.

Validate Brazilian CNPJ (offline, numeric + alphanumeric)

Ferramenta: nfeio_validar_cnpj · somente leitura · offline

Validate a Brazilian CNPJ by its check digits (mod-11), fully offline — no network, no NFE.io API key. Supports BOTH the classic numeric CNPJ and the new alphanumeric CNPJ (IN RFB 2.229/2024).

This is ARITHMETIC validation, NOT an existence/registration check. valido: true means only that the two check digits are mathematically correct — the CNPJ may not exist at the Receita Federal.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
cnpj	string	sim	CNPJ to validate — numeric or the new alphanumeric format (IN RFB 2.229/2024). Accepts with or without mask; dots, slash, dashes and spaces are stripped and letters are upper-cased before validation. Example: '11.222.333/0001-81' or '12ABC34501DE35'.

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Validate a Brazilian CNPJ by its check digits (mod-11), fully offline — no network, no NFE.io API key. Supports BOTH the classic numeric CNPJ and the new alphanumeric CNPJ (IN RFB 2.229/2024).

This is ARITHMETIC validation, NOT an existence/registration check. `valido: true` means only that the two check digits are mathematically correct — the CNPJ may not exist at the Receita Federal.

Use when:
  - You need to reject a malformed CNPJ before saving, building an invoice payload, or spending a paid lookup.
  - You are cleaning a batch/spreadsheet and want a per-row pass/fail with a reason.
  - You need to accept alphanumeric CNPJs: naive validators reject valid ones.

Do NOT use when:
  - You need to know whether the CNPJ actually exists, its razão social, status or address — use nfeio_lookup_cnpj for existence and registration data.

Alphanumeric rule (IN RFB 2.229/2024): each of the first 12 characters contributes ord(c) − 48 (digits 0–9 → 0–9; letters A–Z → 17–42). The two check digits are ALWAYS numeric — a letter in either DV position fails validation.

Args:
  - cnpj (string, required): 14-character CNPJ (numeric or alphanumeric), with or without mask.

Returns JSON with shape:
  {
    "cnpj_formatado": string | null,  // masked form when 14 chars, else null
    "valido": boolean,
    "dv_ok": boolean,
    "normalizado": string,            // 14-char value used in the calculation (letters preserved, upper-cased)
    "alfanumerico": boolean,          // true when a letter appears among the first 12 characters
    "motivo": string | null
  }

Errors:
  - A malformed CNPJ is NOT an error: it returns valido:false with a motivo. Only a schema-invalid call (missing/empty cnpj) is a tool error.

Validate Brazilian CPF (offline)

Ferramenta: nfeio_validar_cpf · somente leitura · offline

Validate a Brazilian CPF by its check digits (mod-11), fully offline — no network, no NFE.io API key.

This is ARITHMETIC validation, NOT an existence/registration check. valido: true means only that the two check digits are mathematically correct — the CPF may not exist at the Receita Federal. There is NO public source to confirm CPF existence, so this local check is the only verification possible for CPF.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
cpf	string	sim	CPF to validate. Accepts with or without mask — dots, dashes and spaces are stripped before validation. Example: '529.982.247-25' or '52998224725'.

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Validate a Brazilian CPF by its check digits (mod-11), fully offline — no network, no NFE.io API key.

This is ARITHMETIC validation, NOT an existence/registration check. `valido: true` means only that the two check digits are mathematically correct — the CPF may not exist at the Receita Federal. There is NO public source to confirm CPF existence, so this local check is the only verification possible for CPF.

Use when:
  - You need to reject a malformed CPF before saving it, building an invoice payload, or spending a paid lookup.
  - You are cleaning a spreadsheet/batch and want a per-row pass/fail with a reason.

Do NOT use when:
  - You need to know whether the CPF actually exists or its registration status — there is no public CPF existence service (unlike CNPJ, where nfeio_lookup_cnpj exists).

Args:
  - cpf (string, required): 11-digit CPF, with or without mask.

Returns JSON with shape:
  {
    "cpf_formatado": string | null,   // masked form when 11 digits, else null
    "valido": boolean,                // length ok AND not a repeated sequence AND dv_ok
    "dv_ok": boolean,                 // the two check digits match mod-11
    "normalizado": string,            // digits-only value used in the calculation
    "motivo": string | null           // pt-BR reason when invalid, null when valid
  }

Errors:
  - A malformed CPF is NOT an error: it returns valido:false with a motivo (so batch scans continue). Only a schema-invalid call (missing/empty cpf) is a tool error.

Validate CST / CSOSN / PIS-COFINS / IPI code (offline)

Ferramenta: nfeio_validar_cst · somente leitura · offline

Valida e descreve um código CST/CSOSN (ICMS), CST PIS/COFINS ou CST IPI, 100% offline — sem rede, sem chave. Roteia automaticamente pela combinação regime + tributo e devolve o veredito + a descrição oficial.

Roteamento:

• tributo=icms + regime=simples → CSOSN (3 dígitos)
• tributo=icms + regime=normal → CST ICMS (3 dígitos = origem [1] + tributação [2], decompostos na resposta)
• tributo=pis ou cofins → CST PIS/COFINS (2 dígitos; mesma tabela para os dois)
• tributo=ipi → CST IPI (2 dígitos, entrada/saída)

Parâmetros

Campo	Tipo	Obrigatório	Descrição
codigo	string	sim	Código a validar. ICMS regime normal: 3 dígitos (origem + tributação, ex.: '000', '060'). Simples (CSOSN): 3 dígitos (ex.: '101', '500'). PIS/COFINS ou IPI: 2 dígitos (ex.: '01', '50'). Aceita com zeros à esquerda e pontuação — é normalizado (só dígitos, zero-fill).
regime	simples · normal	sim	Regime tributário do emitente. 'simples' roteia ICMS para a tabela CSOSN; 'normal' roteia ICMS para CST ICMS. Não afeta PIS/COFINS/IPI (determinados por 'tributo').
tributo	icms · pis · cofins · ipi	não	Tributo do código. 'icms' (com regime='simples' vira CSOSN). 'pis'/'cofins' usam a mesma tabela 4.3.x do SPED. 'ipi' usa a tabela de entrada/saída.

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Valida e descreve um código CST/CSOSN (ICMS), CST PIS/COFINS ou CST IPI, 100% offline — sem rede, sem chave. Roteia automaticamente pela combinação regime + tributo e devolve o veredito + a descrição oficial.

Roteamento:
  - tributo=icms + regime=simples → CSOSN (3 dígitos)
  - tributo=icms + regime=normal → CST ICMS (3 dígitos = origem [1] + tributação [2], decompostos na resposta)
  - tributo=pis ou cofins → CST PIS/COFINS (2 dígitos; mesma tabela para os dois)
  - tributo=ipi → CST IPI (2 dígitos, entrada/saída)

Use when:
  - Validar um CST/CSOSN informado e obter a descrição oficial antes de montar a nota.

Do NOT use when:
  - Você quer que o sistema ESCOLHA o CST pela operação — isso é decisão tributária; esta tool apenas valida/descreve um código fornecido.

Args:
  - codigo (string, obrigatório): com ou sem zeros à esquerda/pontuação.
  - regime (enum 'simples'|'normal', obrigatório): roteia o ICMS.
  - tributo (enum 'icms'|'pis'|'cofins'|'ipi', padrão 'icms').

Returns JSON:
  {
    "codigo": string,           // normalizado
    "valido": boolean,
    "descricao": string | null, // null quando inválido
    "tabela": "CSOSN" | "CST ICMS" | "CST PIS/COFINS" | "CST IPI",
    "fonte": string,
    "atualizado_em": string,
    "origem": { "codigo": string, "descricao": string } | null,     // só em CST ICMS
    "tributacao": { "codigo": string, "descricao": string } | null, // só em CST ICMS
    "motivo": string | null     // preenchido quando valido:false
  }

Errors:
  - código fora da tabela roteada → valido:false com descricao:null e motivo (NÃO é erro de tool).
  - input que não normaliza para o comprimento da tabela → erro de validação.

Gratuitas · referência pública (sem chave)

Consultam fontes públicas (IBGE, Banco Central). Sem chave e sem custo.

Search CNAE subclasses by text

Ferramenta: nfeio_buscar_cnae · somente leitura

Descobre subclasses CNAE 2.0 por texto (ex.: "software" → desenvolvimento de programas de computador), via a API pública de CNAE do IBGE. Sem chave, sem custo.

A busca é feita LOCALMENTE sobre a descrição e as atividades de cada subclasse (o parâmetro de busca do IBGE não filtra), então "software" também encontra CNAEs cuja descrição não contém a palavra mas cujas atividades sim.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
busca	string	sim	Texto livre para descobrir subclasses CNAE 2.0 pela descrição/atividades. Ex.: 'software', 'restaurante', 'consultoria em tecnologia'. Busca case- e acento-insensível aplicada localmente.
limite	integer	não	Número máximo de resultados (1–50, padrão 20). Aplicado localmente para conter o tamanho da resposta.

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Descobre subclasses CNAE 2.0 por texto (ex.: "software" → desenvolvimento de programas de computador), via a API pública de CNAE do IBGE. Sem chave, sem custo.

A busca é feita LOCALMENTE sobre a descrição e as atividades de cada subclasse (o parâmetro de busca do IBGE não filtra), então "software" também encontra CNAEs cuja descrição não contém a palavra mas cujas atividades sim.

Use when:
  - O usuário descreve uma atividade e quer descobrir o(s) CNAE(s) correspondente(s).

Do NOT use when:
  - Você já tem o código — use nfeio_consultar_cnae para a descrição oficial.
  - Você quer os CNAEs de uma EMPRESA — use nfeio_lookup_cnpj (lookup pago).

Args:
  - busca (string, obrigatório): termo (1–200 caracteres após trim).
  - limite (number, opcional, padrão 20, máx 50): teto de resultados.

Returns JSON:
  { "busca": string, "total": number, "resultados": [ { "id": string, "descricao": string } ] }
  Sem correspondência → resultados: [] com total 0 (NÃO é erro).

Errors:
  - termo vazio (após trim) ou > 200 caracteres → erro de validação, sem rede.
  - IBGE indisponível/timeout → erro acionável nomeando o IBGE.

PTAX exchange rate by date and currency

Ferramenta: nfeio_cambio_ptax · somente leitura

Retorna a cotação oficial PTAX (compra e venda) de uma moeda estrangeira numa data, via o serviço público Olinda/OData do Banco Central. Sem chave, sem custo.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
data	string	sim	Data da cotação no formato dd/MM/yyyy. Exemplo: '27/06/2025'. PTAX só existe em dia útil com fechamento; finais de semana e feriados retornam vazio.
moeda	string	não	Código ISO-4217 da moeda estrangeira (3 letras maiúsculas). Exemplos: 'USD', 'EUR', 'GBP'. Validado por regex antes de interpolar na URL OData.

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Retorna a cotação oficial PTAX (compra e venda) de uma moeda estrangeira numa data, via o serviço público Olinda/OData do Banco Central. Sem chave, sem custo.

Use when:
  - O usuário precisa da taxa de câmbio oficial PTAX de uma data (conversão de operação internacional, fechamento de câmbio, valor em reais de fatura em moeda estrangeira).

Do NOT use when:
  - O usuário quer cotação comercial em tempo real ou intraday — PTAX é o fechamento oficial do BCB, não cotação de mercado ao vivo.

Args:
  - data (string, obrigatório): dd/MM/yyyy (convertida internamente para MM-dd-yyyy só na chamada PTAX).
  - moeda (string, opcional, padrão 'USD'): código ISO-4217 de 3 letras maiúsculas.

Returns JSON:
  { "moeda": string, "data": "dd/MM/yyyy", "cotacaoCompra": number, "cotacaoVenda": number, "dataHoraCotacao": string }
  Lido de .value[0] da resposta OData.

Errors:
  - moeda fora de ^[A-Z]{3}$ → erro de validação, sem rede.
  - data em fim de semana/feriado (resposta .value vazia) → erro de tool orientando "verifique se é dia útil".
  - Banco Central indisponível/timeout → erro acionável nomeando o serviço.

Get CNAE subclass description by code

Ferramenta: nfeio_consultar_cnae · somente leitura

Retorna a descrição oficial de uma subclasse CNAE 2.0 (7 dígitos) e sua hierarquia (classe/grupo/divisão/seção), via a API pública de CNAE do IBGE. Sem chave, sem custo.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
codigo	string	sim	Código da subclasse CNAE 2.0 com 7 dígitos. Aceita entrada formatada ('6201-5/01') — pontos, traços, barras e espaços são removidos antes da consulta, resultando em '6201501'.

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Retorna a descrição oficial de uma subclasse CNAE 2.0 (7 dígitos) e sua hierarquia (classe/grupo/divisão/seção), via a API pública de CNAE do IBGE. Sem chave, sem custo.

Use when:
  - Você tem um código CNAE e quer a descrição oficial, ou quer validar se um código de 7 dígitos existe.

Do NOT use when:
  - Você descreve a atividade por texto e quer descobrir o código — use nfeio_buscar_cnae.
  - Você quer os CNAEs de uma EMPRESA — use nfeio_lookup_cnpj (o lookup pago já os devolve).

Args:
  - codigo (string, obrigatório): subclasse CNAE de 7 dígitos, com ou sem formatação.

Returns JSON:
  { "id": string, "descricao": string, "classe"?, "grupo"?, "divisao"?, "secao"? } — cada nível como { id, descricao } quando presente.

Errors:
  - código que não resulta em 7 dígitos → erro de validação, sem rede.
  - subclasse inexistente → erro "não encontrado" acionável (sugere conferir o código ou usar nfeio_buscar_cnae).
  - IBGE indisponível/timeout → erro acionável nomeando o IBGE.

Get IBGE state (UF) by sigla

Ferramenta: nfeio_consultar_estado · somente leitura

Retorna os dados de uma UF (código IBGE, nome por extenso e região) a partir da sigla, via a API pública de Localidades do IBGE. Sem chave, sem custo.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
uf	string	sim	Sigla da UF (2 letras) a consultar, validada contra a allowlist das 27 UFs antes da rede. Aceita minúscula/espaços (normalizado). Ex.: 'RJ'.

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Retorna os dados de uma UF (código IBGE, nome por extenso e região) a partir da sigla, via a API pública de Localidades do IBGE. Sem chave, sem custo.

Use when:
  - O usuário quer o código IBGE da UF, o nome por extenso ou a região de uma sigla.

Do NOT use when:
  - Você quer a lista de municípios — use nfeio_consultar_municipios.
  - Você quer dados de uma empresa — use nfeio_lookup_cnpj (lookup pago).

Args:
  - uf (string, obrigatório): sigla da UF (allowlist das 27).

Returns JSON:
  { "id": number, "sigla": string, "nome": string, "regiao": { "id": number, "sigla": string, "nome": string } | null }

Errors:
  - uf fora da allowlist → erro de validação, sem rede.
  - IBGE indisponível/timeout → erro acionável nomeando o IBGE.

List IBGE municipalities of a state (offline of billing)

Ferramenta: nfeio_consultar_municipios · somente leitura

Lista os municípios de uma UF (nome + código IBGE de 7 dígitos), via a API pública de Localidades do IBGE. Sem chave, sem custo de lookup.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
uf	string	sim	Sigla da Unidade Federativa (2 letras) cujos municípios serão listados. OBRIGATÓRIO e validado contra a allowlist das 27 UFs ANTES de qualquer chamada de rede — sem este filtro a API nacional retornaria ~5.570 municípios numa só resposta e estouraria o limite. Ex.: 'SP'.
busca	string	não	Filtro textual opcional, aplicado localmente sobre o nome do município (case- e acento-insensível). Ex.: 'campin' localiza 'Campinas'. Use para reduzir a resposta de UFs grandes (SP, MG).

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Lista os municípios de uma UF (nome + código IBGE de 7 dígitos), via a API pública de Localidades do IBGE. Sem chave, sem custo de lookup.

Use when:
  - O usuário quer os municípios de um estado, ou você precisa resolver nome → código IBGE para preencher/validar uma cidade (ex.: "emitir para Campinas-SP" precisa do código 3509502).

Do NOT use when:
  - Você já tem o código IBGE (não há o que resolver).
  - Você quer dados cadastrais/fiscais de uma EMPRESA — use nfeio_lookup_cnpj (o lookup pago de CNPJ já devolve o código IBGE do município da empresa). Estas tools são navegação/busca independentes, não enriquecem o lookup pago.

Args:
  - uf (string, obrigatório): sigla da UF (allowlist das 27). Aceita minúscula/espaços (normalizado).
  - busca (string, opcional): filtro local por nome (acento-insensível).

Returns JSON:
  { "uf": string, "total": number, "municipios": [ { "id": number, "nome": string } ] }
  ("id" é o código IBGE de 7 dígitos.) Resposta truncada em 25000 caracteres — use "busca" para estreitar UFs grandes.

Errors:
  - uf fora da allowlist (ou ausente) → erro de validação, sem rede.
  - IBGE indisponível/timeout → erro acionável nomeando o IBGE.

Monetary correction by Selic/IPCA (compound factor)

Ferramenta: nfeio_corrigir_valor · somente leitura

Corrige (atualiza) um valor monetário entre duas datas pela Selic ou pelo IPCA, usando as séries públicas do SGS/Banco Central. Aplica o fator ACUMULADO (produtório de (1 + variação/100) sobre todas as observações do período), não a soma dos percentuais. Sem chave, sem custo.

Este é um fator de ATUALIZAÇÃO monetária, não uma previsão. Para débitos federais a Receita ainda aplica multa e outros encargos, que esta ferramenta NÃO calcula.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
valor	number	sim	Valor monetário original a ser corrigido, em reais. Exemplo: 1000.00
indice	IPCA · SELIC	sim	Índice de correção. 'IPCA' usa a série mensal SGS id=433; 'SELIC' usa a série diária SGS id=11 (fator diário acumulado).
dataInicial	string	sim	Data inicial da correção (dd/MM/yyyy) — marco a partir do qual o valor passa a ser corrigido. Exemplo: '01/01/2020'.
dataFinal	string	sim	Data final da correção (dd/MM/yyyy) — data em que o valor é trazido a valor presente. Deve ser maior ou igual a dataInicial.

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Corrige (atualiza) um valor monetário entre duas datas pela Selic ou pelo IPCA, usando as séries públicas do SGS/Banco Central. Aplica o fator ACUMULADO (produtório de (1 + variação/100) sobre todas as observações do período), não a soma dos percentuais. Sem chave, sem custo.

Este é um fator de ATUALIZAÇÃO monetária, não uma previsão. Para débitos federais a Receita ainda aplica multa e outros encargos, que esta ferramenta NÃO calcula.

Use when:
  - O usuário quer atualizar/corrigir um valor entre duas datas pela Selic ou IPCA (dívida, contrato, valor de nota, aluguel).

Do NOT use when:
  - O usuário quer a série bruta de índices — use nfeio_indexador_selic / nfeio_indexador_ipca.
  - O usuário quer câmbio — use nfeio_cambio_ptax.

Args:
  - valor (number, obrigatório, > 0): valor original em reais.
  - indice (enum 'IPCA' | 'SELIC', obrigatório).
  - dataInicial, dataFinal (string dd/MM/yyyy, obrigatórios): dataFinal >= dataInicial.

Returns JSON:
  { "indice": string, "dataInicial": string, "dataFinal": string, "valorOriginal": number, "fatorAcumulado": number, "valorCorrigido": number, "percentualAcumulado": number, "observacoesUsadas": number }
  fatorAcumulado = Π (1 + valor_i/100); valorCorrigido = valorOriginal × fatorAcumulado (2 casas); percentualAcumulado = (fatorAcumulado - 1) × 100.

Errors:
  - período invertido (dataFinal < dataInicial) → erro de validação, sem rede.
  - série vazia no período → erro de tool explícito ("não há observações publicadas") — NUNCA fator 1 silencioso.
  - Banco Central indisponível/timeout → erro acionável nomeando o serviço.

IPCA monthly variation series (SGS 433)

Ferramenta: nfeio_indexador_ipca · somente leitura

Retorna a série do IPCA (variação % mensal, SGS id=433) do Banco Central para um período, via a API pública do SGS. Sem chave, sem custo.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
dataInicial	string	sim	Data inicial do período no formato dd/MM/yyyy. Exemplo: '01/01/2025'. O IPCA é mensal (SGS id=433); o BCB indexa cada observação pelo primeiro dia do mês de referência.
dataFinal	string	sim	Data final do período no formato dd/MM/yyyy. Exemplo: '30/06/2025'. Deve ser maior ou igual a dataInicial.

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Retorna a série do IPCA (variação % mensal, SGS id=433) do Banco Central para um período, via a API pública do SGS. Sem chave, sem custo.

Use when:
  - O usuário pede a série mensal do IPCA de um período, ou quer inspecionar a variação mês a mês.

Do NOT use when:
  - O objetivo é CORRIGIR um valor pelo IPCA acumulado — use nfeio_corrigir_valor.
  - O usuário quer a taxa Selic — use nfeio_indexador_selic.

Args:
  - dataInicial (string, obrigatório): dd/MM/yyyy.
  - dataFinal (string, obrigatório): dd/MM/yyyy; deve ser >= dataInicial.

Returns JSON:
  { "serie": "IPCA (variação % mensal)", "sgsId": 433, "dataInicial": string, "dataFinal": string, "observacoes": number, "dados": [ { "data": "dd/MM/yyyy", "valor": number } ] }
  O "valor" é a variação percentual do mês, já convertida de string com vírgula para número.

Errors:
  - período invertido (dataFinal < dataInicial) → erro de validação, sem rede.
  - período sem observações → erro de tool; um mês recente pode ainda não ter sido divulgado (o IPCA fechado sai por volta do dia 10 do mês seguinte), o que é esperado e não é erro de formato.
  - Banco Central indisponível/timeout → erro acionável nomeando o serviço.

Selic daily rate series (SGS 11)

Ferramenta: nfeio_indexador_selic · somente leitura

Retorna a série da taxa Selic diária (% ao dia, SGS id=11) do Banco Central para um período, via a API pública do SGS. Sem chave, sem custo.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
dataInicial	string	sim	Data inicial do período no formato dd/MM/yyyy. Exemplo: '01/01/2025'. A série Selic diária (SGS id=11) só retorna dias úteis.
dataFinal	string	sim	Data final do período no formato dd/MM/yyyy. Exemplo: '30/06/2025'. Deve ser maior ou igual a dataInicial.

Descrição completa (texto que o agente lê)

[Gratuito — sem chave] Retorna a série da taxa Selic diária (% ao dia, SGS id=11) do Banco Central para um período, via a API pública do SGS. Sem chave, sem custo.

Use when:
  - O usuário pede a taxa Selic diária de um período, ou precisa da série para auditar/cruzar com cálculo de juros.

Do NOT use when:
  - O usuário quer CORRIGIR um valor monetário pela Selic — use nfeio_corrigir_valor (que já faz o produtório do fator).
  - O usuário quer a variação do IPCA — use nfeio_indexador_ipca.

Args:
  - dataInicial (string, obrigatório): dd/MM/yyyy.
  - dataFinal (string, obrigatório): dd/MM/yyyy; deve ser >= dataInicial.

Returns JSON:
  { "serie": "Selic (taxa diária)", "sgsId": 11, "dataInicial": string, "dataFinal": string, "observacoes": number, "dados": [ { "data": "dd/MM/yyyy", "valor": number } ] }
  O "valor" é o percentual diário já convertido de string com vírgula para número. Períodos amplos podem ser truncados na saída — prefira janelas menores.

Errors:
  - período invertido (dataFinal < dataInicial) → erro de validação, sem rede.
  - período sem observações (só fim de semana/feriado, ou data recente ainda sem publicação) → erro de tool distinguindo "sem observações" de erro de formato.
  - Banco Central indisponível/timeout → erro acionável nomeando o serviço.

Requerem chave de API NFE.io

Consomem a API da NFE.io. Envie sua chave no header — ver Autenticação.

Create NFE.io company (issuer)

Ferramenta: nfeio_create_company · ⚠️ destrutiva

Create a new company (issuer/emitente) on your NFE.io account via companies.create.

Creates the company "shell": its registration data, tax regime and address. The company is created but does NOT issue any fiscal document until a digital certificate (A1/.pfx) is uploaded — and certificate upload is intentionally NOT exposed as a tool (the .pfx file and its password must never travel through the LLM context). Point the user to the NFE.io dashboard (https://app.nfe.io) for the certificate step.

NOT idempotent — the NFE.io API does NOT deduplicate by CNPJ: calling this twice with the same federalTaxNumber creates TWO separate companies (it does NOT error on a duplicate). If uniqueness matters, check nfeio_list_companies first, and do not blindly retry on a timeout.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
name	string	sim	Razão social da empresa (nome legal registrado).
federalTaxNumber	integer	sim	CNPJ como NÚMERO (14 dígitos, sem pontuação), ex.: 12345678000190. É number, não string.
taxRegime	None · LucroReal · LucroPresumido · SimplesNacional · SimplesNacionalExcessoSublimite · MicroempreendedorIndividual · Isento	sim	Regime tributário da empresa (obrigatório).
address	object	sim	Endereço completo da empresa (obrigatório). Pré-preencha via nfeio_lookup_cnpj (a partir do CNPJ) ou nfeio_lookup_address (a partir do CEP — devolve inclusive o código IBGE do município).
tradeName	string	não	Nome fantasia (opcional).
municipalTaxNumber	string	não	Inscrição municipal / CCM (opcional).
email	string	não	E-mail de contato da empresa (opcional).

Descrição completa (texto que o agente lê)

[Requer chave de API NFE.io] Create a new company (issuer/emitente) on your NFE.io account via companies.create.

Creates the company "shell": its registration data, tax regime and address. The company is created but does NOT issue any fiscal document until a digital certificate (A1/.pfx) is uploaded — and certificate upload is intentionally NOT exposed as a tool (the .pfx file and its password must never travel through the LLM context). Point the user to the NFE.io dashboard (https://app.nfe.io) for the certificate step.

NOT idempotent — the NFE.io API does NOT deduplicate by CNPJ: calling this twice with the same federalTaxNumber creates TWO separate companies (it does NOT error on a duplicate). If uniqueness matters, check nfeio_list_companies first, and do not blindly retry on a timeout.

Use when:
  - Onboarding a new company/tenant programmatically (SaaS/marketplace), or a user finishing their own company setup.
  - You already have the company's legal data (razão social, CNPJ, tax regime, full address).

Do NOT use when:
  - You only want to look up an existing company — use nfeio_list_companies / nfeio_get_company.
  - You need to upload or manage a digital certificate — not supported here by design; use the dashboard.
  - You want to update an existing company — not available yet (update is a full replace / PUT and comes in a later wave).

Prefill tips (compose with the free/lookup tools to build the payload):
  - nfeio_lookup_cnpj → razão social, nome fantasia and address from the CNPJ.
  - nfeio_lookup_address → street, district and the IBGE city.code from a CEP.
  - nfeio_consultar_municipios → the IBGE city.code if you only have the municipality name.

Args:
  - name (string): razão social.
  - federalTaxNumber (number): CNPJ as a NUMBER, 14 digits, no punctuation.
  - taxRegime (enum): "None" | "LucroReal" | "LucroPresumido" | "SimplesNacional" | "SimplesNacionalExcessoSublimite" | "MicroempreendedorIndividual" | "Isento".
  - address (object): { state (UF alfa-2), city { code (IBGE 7 díg), name }, district, street, number ("S/N" if none), postalCode (CEP), country (alfa-3, default "BRA"), additionalInformation? }.
  - tradeName (string, optional): nome fantasia.
  - municipalTaxNumber (string, optional): inscrição municipal.
  - email (string, optional): contact e-mail.

Returns JSON — the created company as the NFE.io API returns it, plus an "orientacao" field reminding you that a certificate must be uploaded in the dashboard before the company can issue:
  {
    "id": string,
    "name": string,
    "federalTaxNumber": number,
    "taxRegime": string,
    "address": { ... },
    ...,
    "orientacao": string   // pt-BR next-step notice about the certificate
  }

Errors:
  - Instructive key error if called with no NFE.io credential (set NFE_API_KEY / X-NFE-API-Key).
  - Validation error if required fields are missing/malformed (taxRegime and the full address — including address.city.code, the 7-digit IBGE code — are required; a missing city.code returns HTTP 400).
  - No duplicate-CNPJ error: the API accepts a CNPJ that already exists and creates another company (see the non-idempotency note above).

Get NFE.io company detail

Ferramenta: nfeio_get_company · somente leitura

Retrieve the full detail of one company (issuer) registered on your NFE.io account via companies.retrieve.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
companyId	string	não	NFE.io company UUID. Optional: if omitted, the environment/session default is used (NFE_COMPANY_ID env var or X-NFE-Company-Id header). If neither is set, the tool returns an instructive error pointing you to nfeio_list_companies. Discover ids with nfeio_list_companies.

Descrição completa (texto que o agente lê)

[Requer chave de API NFE.io] Retrieve the full detail of one company (issuer) registered on your NFE.io account via companies.retrieve.

Returns the fields an agent typically needs before issuing an invoice: tax regime, municipal registration (inscrição municipal / CCM), state registration (IE), issuance environment (Production vs Test), and ISS rate for Simples Nacional. The payload is returned as the API sends it — the SDK's Company type is intentionally open-ended, so treat any field beyond the documented ones as best-effort.

Use when:
  - You have a companyId (or a configured default) and need the company's tax setup, registrations, or issuance environment.
  - You need to confirm a company's certificate/environment before issuing.

Do NOT use when:
  - You don't yet know which company — use nfeio_list_companies first.
  - You want the invoices of a company — use nfeio_list_service_invoices.

Args:
  - companyId (string, optional): company UUID. If omitted, the context default (NFE_COMPANY_ID / X-NFE-Company-Id) is used.

Returns JSON — the company object as the NFE.io API returns it, e.g.:
  {
    "id": string,
    "name": string,
    "tradeName": string | null,
    "federalTaxNumber": number,          // CNPJ/CPF as a NUMBER (not a string)
    "email": string | null,
    "taxRegime": string,                 // e.g. "SimplesNacional" | "LucroPresumido" | ...
    "municipalTaxNumber": string | null, // inscrição municipal (CCM)
    "regionalTaxNumber": number | null,  // inscrição estadual (IE)
    "environment": string,               // issuance environment
    "address": { ... } | null,
    ...
  }
When the context default is used (companyId omitted), the response also carries a top-level "resolvedCompanyId" so you can see which company was actually read.

Errors:
  - Instructive key error if called with no NFE.io credential.
  - Instructive company error if no companyId and no default is configured (points to nfeio_list_companies).
  - "Resource not found" (404) if the companyId does not exist on the account.

Get NFS-e processing status

Ferramenta: nfeio_get_invoice_status · somente leitura

Check the processing status of a specific NFS-e (service invoice).

Parâmetros

Campo	Tipo	Obrigatório	Descrição
companyId	string	não	NFE.io company UUID that owns the invoice. Optional: if omitted, the environment/session default is used (NFE_COMPANY_ID env var or X-NFE-Company-Id header). If neither is set, the tool returns an instructive error pointing to nfeio_list_companies.
invoiceId	string	sim	NFE.io invoice ID returned by nfeio_issue_service_invoice or nfeio_list_service_invoices.

Descrição completa (texto que o agente lê)

[Requer chave de API NFE.io] Check the processing status of a specific NFS-e (service invoice).

Use when:
  - A previous issue_service_invoice call timed out or returned async; you need to know whether the invoice was ultimately issued, failed, or is still processing.
  - The user asks "what's the status of invoice X".

Do NOT use when:
  - You only need invoice business data (use list_service_invoices or a dedicated retrieve tool instead).

Args:
  - companyId (string, required): company UUID.
  - invoiceId (string, required): invoice ID.

Returns JSON with shape:
  {
    "flowStatus": "Issued" | "IssueFailed" | "Cancelled" | "CancelFailed" | "WaitingSend" | "WaitingReturn" | "WaitingDownload" | "WaitingCalculateTaxes" | "WaitingDefineRpsNumber" | "WaitingSendCancel" | "PullFromCityHall",
    "isComplete": boolean,    // true when flowStatus is terminal (Issued/IssueFailed/Cancelled/CancelFailed)
    "isFailed": boolean,      // true when flowStatus is IssueFailed or CancelFailed
    "invoice": { ...full invoice object... }
  }

Terminal statuses: Issued, IssueFailed, Cancelled, CancelFailed. Any other value means the invoice is still being processed at the city hall — poll again in a few seconds.

Issue NFS-e (Brazilian service invoice)

Ferramenta: nfeio_issue_service_invoice · ⚠️ destrutiva

Issue a Brazilian Electronic Service Invoice (NFS-e) for a company registered in NFE.io.

By default this tool waits (polls) until the municipality returns a terminal state — "Issued" (success) or "IssueFailed" (rejected). Set waitForCompletion=false to return immediately after submission (you can then poll with nfeio_get_invoice_status).

IMPORTANT:

• Federal tax number (CPF or CNPJ) must be passed as a NUMBER, not a string.
• cityServiceCode is municipal — ask the user or use an existing invoice for the same city to infer it.
• The issuing company must already have an A1 digital certificate uploaded via the NFE.io dashboard.
• This is a DESTRUCTIVE operation — it emits a real fiscal document with legal and tax effects. Confirm intent with the user before calling in production.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
companyId	string	não	NFE.io company UUID (the issuer that will emit the invoice). Optional: if omitted, the environment/session default is used (NFE_COMPANY_ID env var or X-NFE-Company-Id header). If neither is set, the tool returns an instructive error pointing to nfeio_list_companies. Because issuance is destructive, the effective issuer is echoed as resolvedCompanyId when the default is used.
cityServiceCode	string	sim	Municipal service code (codigo de servico). Specific to the city hall; e.g. '2690' or '10677'.
description	string	sim	Human-readable description of the service rendered.
servicesAmount	number	sim	Total service amount in BRL (R$). Example: 1500.00
borrower	object	sim
deductions	number	não
discountConditionedAmount	number	não
discountUnconditionedAmount	number	não
issRate	number	não	ISS rate as a fraction (e.g. 0.05 = 5%)
issTaxAmount	number	não
irAmountWithheld	number	não
pisAmountWithheld	number	não
cofinsAmountWithheld	number	não
csllAmountWithheld	number	não
inssAmountWithheld	number	não
issAmountWithheld	number	não
waitForCompletion	boolean	não	If true (default), polls until the invoice reaches a terminal state (Issued/IssueFailed). If false, returns immediately after submission.
pollTimeoutMs	integer	não	Max time to wait for terminal state when waitForCompletion=true, in ms. Default 300000 (5 min). Some municipalities take >2 min.

Descrição completa (texto que o agente lê)

[Requer chave de API NFE.io] Issue a Brazilian Electronic Service Invoice (NFS-e) for a company registered in NFE.io.

By default this tool waits (polls) until the municipality returns a terminal state — "Issued" (success) or "IssueFailed" (rejected). Set waitForCompletion=false to return immediately after submission (you can then poll with nfeio_get_invoice_status).

IMPORTANT:
  - Federal tax number (CPF or CNPJ) must be passed as a NUMBER, not a string.
  - cityServiceCode is municipal — ask the user or use an existing invoice for the same city to infer it.
  - The issuing company must already have an A1 digital certificate uploaded via the NFE.io dashboard.
  - This is a DESTRUCTIVE operation — it emits a real fiscal document with legal and tax effects. Confirm intent with the user before calling in production.

Use when:
  - The user explicitly asks to issue / emit / "emitir" a service invoice (NFS-e).

Do NOT use when:
  - The user only wants to simulate or calculate taxes — use tax-calculation tools instead.
  - The user wants a product invoice (NF-e) — that uses a different API not exposed in this tool.

Args:
  - companyId (string, required): issuer company UUID.
  - cityServiceCode (string, required): municipal service code.
  - description (string, required).
  - servicesAmount (number, required): value in BRL.
  - borrower (object, required): with federalTaxNumber (number), name, optional email and address.
  - Optional tax/deduction fields: deductions, discountConditionedAmount, discountUnconditionedAmount, issRate, issTaxAmount, irAmountWithheld, pisAmountWithheld, cofinsAmountWithheld, csllAmountWithheld, inssAmountWithheld, issAmountWithheld.
  - waitForCompletion (boolean, default true): poll to terminal state.
  - pollTimeoutMs (number, default 300000): 5 min timeout for polling.

Returns JSON:
  - If waitForCompletion=true: full ServiceInvoiceData (includes id, number, flowStatus, issuedOn, pdfUrl, xmlUrl, etc.).
  - If waitForCompletion=false and result is immediate: ServiceInvoiceData.
  - If waitForCompletion=false and result is async: { "status": "async", "invoiceId": string, "location": string } — use nfeio_get_invoice_status to poll.

Errors:
  - "Invoice processing failed" — municipality rejected; check description, borrower data, cityServiceCode.
  - "Invoice still processing after polling timeout" — use nfeio_get_invoice_status with the returned invoiceId to check again later.

List NFE.io companies (issuers)

Ferramenta: nfeio_list_companies · somente leitura

List the companies (issuers / tenants) registered on your NFE.io account, with offset pagination.

This is the discovery path for companyId: the other fiscal tools (issue/list/status) need a companyId, and this tool is how you find it without leaving the MCP client. Once you know which company you want, either pass its id explicitly or set it as the session default (NFE_COMPANY_ID / X-NFE-Company-Id).

Parâmetros

Campo	Tipo	Obrigatório	Descrição
pageIndex	integer	não	1-based page index (default: 1). First page is 1, next is 2, etc. The API rejects 0.
pageCount	integer	não	Items per page, 2-50 (default: 20). The API rejects 1 and values above 50. Keep it modest — each company serializes to a few hundred bytes of JSON, so large pages can eat a chunk of the context window. Paginate via pageIndex instead of asking for a big page.

Descrição completa (texto que o agente lê)

[Requer chave de API NFE.io] List the companies (issuers / tenants) registered on your NFE.io account, with offset pagination.

This is the discovery path for companyId: the other fiscal tools (issue/list/status) need a companyId, and this tool is how you find it without leaving the MCP client. Once you know which company you want, either pass its id explicitly or set it as the session default (NFE_COMPANY_ID / X-NFE-Company-Id).

Use when:
  - The user asks "which companies do I have", "list my companies", or you need a companyId and none was given.
  - You need to map a company name or CNPJ to its NFE.io UUID before issuing an invoice.

Do NOT use when:
  - You already have the companyId — call nfeio_get_company for the full detail instead.
  - You want the full detail of one known company — use nfeio_get_company.

Args:
  - pageIndex (number, default 1): 1-based page index. First page is 1 (the API rejects 0).
  - pageCount (number, default 20): items per page, 2-50 (the API rejects 1 and values above 50).

Returns JSON with shape:
  {
    "data": [
      {
        "id": string,                    // the companyId to use in other tools
        "name": string,
        "tradeName": string | null,
        "federalTaxNumber": number,      // CNPJ/CPF as a NUMBER (not a string)
        "email": string | null,
        ...
      }
    ],
    "page": { "pageIndex": number, "pageCount": number }
  }

Pagination: 1-based. First page is pageIndex=1, next is pageIndex=2. Response is truncated at 25000 characters — request a smaller pageCount or the next page if truncated.

Errors:
  - Instructive key error if called with no NFE.io credential (set NFE_API_KEY / X-NFE-API-Key).

List NFS-e service invoices

Ferramenta: nfeio_list_service_invoices · somente leitura

List NFS-e (Nota Fiscal de Servico Eletronica) invoices for a company, with optional date filters and offset pagination.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
companyId	string	não	NFE.io company UUID (the tenant that issues the invoices). Optional: if omitted, the environment/session default is used (NFE_COMPANY_ID env var or X-NFE-Company-Id header). If neither is set, the tool returns an instructive error pointing to nfeio_list_companies.
pageIndex	integer	não	1-based page index (default: 1). The NFE.io API rejects 0 with 'page index must be greater then zero'.
pageCount	integer	não	Items per page, 1-100 (default: 10). Keep small (5-20) when called by an AI agent — each invoice serializes to ~300-600 bytes of JSON, so 50 items can eat a large chunk of the context window. Paginate via pageIndex instead of asking for a big page.
issuedBegin	string	não	Filter: issuance date >= this date (YYYY-MM-DD)
issuedEnd	string	não	Filter: issuance date <= this date (YYYY-MM-DD)
createdBegin	string	não	Filter: creation date >= this date (YYYY-MM-DD)
createdEnd	string	não	Filter: creation date <= this date (YYYY-MM-DD)

Descrição completa (texto que o agente lê)

[Requer chave de API NFE.io] List NFS-e (Nota Fiscal de Servico Eletronica) invoices for a company, with optional date filters and offset pagination.

Use when:
  - The user asks to list, count, or browse service invoices for a specific company.
  - You need invoice IDs to then retrieve details, cancel, or download PDFs/XMLs.

Do NOT use when:
  - The user wants NF-e (product) invoices — those use a different endpoint not exposed here.

Args:
  - companyId (string, required): NFE.io company UUID.
  - pageIndex (number, default 1): 1-based page index. The API rejects 0 — first page is 1.
  - pageCount (number, default 10, max 100): items per page. Keep small for AI agents — each invoice is ~300-600 bytes of JSON.
  - issuedBegin / issuedEnd (YYYY-MM-DD, optional): filter by issuance date range.
  - createdBegin / createdEnd (YYYY-MM-DD, optional): filter by creation date range.

Returns JSON with shape:
  {
    "data": [
      {
        "id": string,
        "number": number | null,
        "flowStatus": "Issued" | "IssueFailed" | "Cancelled" | "CancelFailed" | "WaitingSend" | ...,
        "issuedOn": string | null,
        "createdOn": string,
        "servicesAmount": number,
        "borrower": { "federalTaxNumber": number, "name": string, ... },
        ...
      }
    ],
    "totalCount": number,
    "page": { "pageIndex": number, "pageCount": number, ... }
  }

Pagination: 1-based. First page is pageIndex=1, next is pageIndex=2, etc. Response is truncated at 25000 characters — use narrower date ranges or smaller pageCount if truncated.

Lookup Brazilian address by CEP

Ferramenta: nfeio_lookup_address · somente leitura

Lookup a Brazilian postal address by CEP (Codigo de Enderecamento Postal).

Parâmetros

Campo	Tipo	Obrigatório	Descrição
postalCode	string	sim	Brazilian postal code (CEP), 8 digits. Both '01310100' and '01310-100' are accepted.

Descrição completa (texto que o agente lê)

[Requer chave de API NFE.io] Lookup a Brazilian postal address by CEP (Codigo de Enderecamento Postal).

Returns street name, district (bairro), city name, city IBGE code, state (UF), and country. Useful to autofill an invoice borrower's address or validate a CEP supplied by a user.

Use when:
  - The user asks to look up an address, CEP, or ZIP code in Brazil.
  - You need city.code (IBGE) to fill a NFS-e borrower address.

Do NOT use when:
  - You need a free-text address search — the NFE.io API only supports lookup by CEP (postal code).

Args:
  - postalCode (string): 8-digit CEP, with or without dash.

Returns JSON with shape (a single flat address object):
  {
    "state": string,            // UF, e.g. "SP"
    "city": { "code": string, "name": string },  // IBGE code + city name
    "district": string,
    "street": string,
    "streetSuffix": string,     // e.g. "Avenida", "Rua"
    "number": string,           // may be a textual range, e.g. "de 612 a 1510 - lado par"
    "additionalInformation": string,
    "postalCode": string,       // formatted WITH hyphen, e.g. "01310-100"
    "country": string           // ISO 3166-1 alpha-3, e.g. "BRA"
  }

Errors:
  - "Resource not found" if CEP does not exist in the database.
  - "invalid data" if format is wrong.

Lookup Brazilian CNPJ

Ferramenta: nfeio_lookup_cnpj · somente leitura

Lookup Brazilian company data by CNPJ (Cadastro Nacional da Pessoa Juridica) via the NFE.io data service.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
cnpj	string	sim	Brazilian CNPJ (14 digits, numbers only, no dots/slashes/dashes). Example: '12345678000190'
updateAddress	boolean	não	If true (default), enrich/normalize address data from postal service records. Set to false for raw Receita Federal address.

Descrição completa (texto que o agente lê)

[Requer chave de API NFE.io] Lookup Brazilian company data by CNPJ (Cadastro Nacional da Pessoa Juridica) via the NFE.io data service.

Returns official Receita Federal information: legal name (razao social), trade name (nome fantasia), registration status (Active/Suspended/Cancelled/Unabled/Null), tax regime (SimplesNacional/MEI/Normal), size (ME/EPP/DEMAIS), opening date, address, phones, economic activities (CNAE), and partners.

Use when:
  - The user asks to verify, validate, or enrich CNPJ data (e.g. "check if CNPJ 11222333000181 is active").
  - You need to validate a company before issuing an invoice to it.
  - You need to discover a company's address or legal name from its CNPJ.

Do NOT use when:
  - The user has a CPF (natural person) — use the CPF lookup service (not exposed yet).
  - You need state tax registrations (Inscricoes Estaduais); use the dedicated state-tax lookup instead.

Args:
  - cnpj (string): 14-digit CNPJ, numbers only.
  - updateAddress (boolean, default true): enrich address from postal service.

Returns JSON with shape:
  {
    "legalEntity": {
      "federalTaxNumber": string,
      "name": string,
      "tradeName": string | null,
      "status": "Active" | "Suspended" | "Cancelled" | "Unabled" | "Null" | "Unknown",
      "taxRegime": "SimplesNacional" | "MEI" | "Normal" | "Unknown",
      "size": "ME" | "EPP" | "DEMAIS",
      "unit": "Headoffice" | "Subsidiary",
      "openingDate": string | null,
      "email": string | null,
      "address": { ... } | null,
      "phones": [...],
      "activities": [...],
      "partners": [...]
    }
  }

Errors:
  - "Resource not found" if CNPJ does not exist in Receita Federal records.
  - "invalid data" if the CNPJ format is wrong.