Fonteza — Referência para desenvolvedores

// 01 · quickstartDo zero à primeira resposta

Pegue sua chave (link no rodapé do site), escolha o transporte e faça a primeira chamada em menos de um minuto.

# MCP — Claude Desktop / Cursor / Codex
{
  "mcpServers": {
    "fonteza": {
      "command": "npx",
      "args": ["-y", "fonteza-mcp"],
      "env": { "FONTEZA_KEY": "sua-chave" }
    }
  }
}

# REST — primeira chamada
curl https://api.fonteza.com.br/v1/buscar \
  -H "Authorization: Bearer $FONTEZA_KEY" \
  --data-urlencode "q=conceicao"

# → 200 OK (recorte)
{
  "total": 2,
  "items": [ { "cnpj": "61685886000149", … } ],
  "meta": { "fonte": ["oficial"],
            "competencia": "2026-07" }
}

Envelope de procedência. Toda resposta — de qualquer endpoint — carrega meta.fonte e meta.competencia. Guarde esses dois campos junto do resultado: são eles que tornam a resposta citável e reprodutível.

// 02 · rest apiEndpoints

Base URL: https://api.fonteza.com.br. Autenticação por Authorization: Bearer <chave> em todas as rotas.

GET /v1/buscar — busca de empresas

Parâmetro	Tipo	Descrição
`q`obrigatório	string ≥ 2	Nome razão, fantasia ou atividade. Busca híbrida: texto exato, variações em português e tolerância a erro de digitação.
`uf`opcional	string(2)	Filtro por estado. Ex.: `SP`.
`municipio`opcional	string	Filtro por município. Ex.: `campinas`.
`cnae`opcional	string	Prefixo ou código CNAE. Ex.: `4930`.
`somente_matriz`opcional	bool	`true` exclui filiais do resultado.
`limit` / `offset`opcional	int	Paginação. Padrão 20, máximo 100.

GET /v1/empresas/{cnpj} — dossiê completo

Aceita CNPJ numérico ou alfanumérico, com ou sem máscara (61.685.886/0001-49 é válido). Retorna cadastro, endereço, CNAEs, porte, capital social, Simples/MEI, sócios com CPF mascarado, sanções conhecidas e o envelope de procedência.

GET /v1/sancoes/{cnpj} — verificação de sanções

Consulta por CNPJ raiz — cobre matriz e todas as filiais de uma vez. Resposta:

{
  "data": {
    "limpo": false,
    "cnpj_basico": "33000167",
    "sancoes": [ {
      "tipo": "…", "orgao": "…",
      "fundamento": "…",
      "inicio": "20230601", "fim": "20260601"
    } ]
  },
  "meta": { "fonte": ["oficial"], "competencia": "2026-07" }
}

GET /v1/meta — saúde da base

Competência vigente, total de estabelecimentos e timestamp da última promoção. É a rota que seu monitor deve pingar.

// 03 · mcpFerramentas para agentes

O server MCP expõe as mesmas operações como ferramentas tipadas — o host do agente faz o parse, você só declara a intenção.

Ferramenta	Argumentos	Equivalente REST
`buscar_empresas`	q, uf?, municipio?, cnae?, somente_matriz?, limit?, offset?	`GET /v1/buscar`
`obter_empresa`	cnpj	`GET /v1/empresas/{cnpj}`
`verificar_sancoes`	cnpj	`GET /v1/sancoes/{cnpj}`

Erros estruturados. Ferramentas nunca estouram exceção crua: CNPJ inválido, não encontrado ou fora da cota volta como JSON {"erro": "…", "codigo": "…"} — o agente consegue reagir em vez de travar.

// 04 · erros & cotasO que pode dar errado

HTTP	Significado	O que fazer
`401`	Chave ausente, inválida ou expirada	Conferir o header `Authorization`
`422`	Parâmetro inválido (ex.: CNPJ com DV errado)	Corrigir o valor; a mensagem diz qual campo
`404`	Não encontrado na base atual	Não é erro de sintaxe — o registro não existe neste recorte
`429`	Cota do plano esgotada	Respeitar o header de retry; upgrade no plano se for recorrente
`503`	Manutenção / troca de base	Retry com backoff; status em tempo real na página de status

Cotas

Plano	Limite	Recarga
Grátis	1.000 chamadas/dia	diária
Pro	30.000 chamadas/mês	mensal
Scale	150.000 chamadas/mês · SLA 99,5%	mensal

Modo aberto no dev local. Rodando o server sem nenhuma chave configurada (ex.: sua instância local), a autenticação fica desligada — útil para desenvolvimento; nunca acontecerá na API de produção.