# API Fonteza

Empresas da Receita Federal, contratações do PNCP e despesas federais do Portal da Transparência em JSON. Somente leitura, com fonte e publicação em cada resposta. Para agentes de IA, as mesmas bases por [MCP](https://fonteza.com.br/docs/agentes.md).

curl:

```bash
curl -G https://api.fonteza.com.br/v1/buscar \
  -H "X-Api-Key: $FONTEZA_KEY" \
  --data-urlencode "q=transportadora" \
  --data-urlencode "uf=SP"
```

Python:

```python
import os
import requests

resposta = requests.get(
    "https://api.fonteza.com.br/v1/buscar",
    params={"q": "transportadora", "uf": "SP"},
    headers={"X-Api-Key": os.environ["FONTEZA_KEY"]},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()
```

JavaScript:

```javascript
const url = new URL("https://api.fonteza.com.br/v1/buscar");
url.search = new URLSearchParams({ q: "transportadora", uf: "SP" });
const resposta = await fetch(url, {
  headers: { "X-Api-Key": process.env.FONTEZA_KEY },
});
if (!resposta.ok) throw new Error(`${resposta.status}: ${await resposta.text()}`);
const dados = await resposta.json();
```

Resposta 200, resumida:

```json
{
  "total": null,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "cnpj": "12345678000190",
      "razao_social": "TRANSPORTADORA EXEMPLO LTDA",
      "nome_fantasia": "EXEMPLO CARGAS",
      "municipio": "CAMPINAS",
      "uf": "SP",
      "cnae_principal": "4930202"
    }
  ],
  "has_more": false,
  "meta": {
    "fonte": [
      "RFB/DadosAbertos"
    ],
    "competencia": "2026-09",
    "snapshot_id": "rfb-2026-09-3f9c2a7d41b8e605",
    "total_calculado": false,
    "modo_busca": "texto",
    "plano": {
      "varredura_ampla": false,
      "custo_estimado": 1834.2,
      "custo_leitura_completa": 1834.2,
      "linhas_estimadas": 412,
      "limite_custo": 100000,
      "exige_confirmacao": true
    },
    "cnaes_sugeridos": [
      {
        "rotulo": "Caminhoneiros e transportadoras",
        "codigos": [
          "4930201",
          "4930202",
          "4930203"
        ],
        "descricoes": [
          "Transporte rodoviário de carga",
          "exceto produtos perigosos e mudanças",
          "municipal",
          "Transporte rodoviário de carga, exceto produtos perigosos e mudanças, intermunicipal, interestadual e internacional",
          "Transporte rodoviário de produtos perigosos"
        ],
        "origem": "categoria",
        "termo": "transportadora",
        "nota": "Maioria MEI: são sobretudo caminhoneiros autônomos."
      }
    ]
  }
}
```

Para trocar os filtros e copiar a requisição pronta, use [Montar uma busca](https://fonteza.com.br/docs/construtor.md).

| | |
| --- | --- |
| URL base | `https://api.fonteza.com.br` |
| Autenticação | `X-Api-Key: fk_...`. [Crie uma chave grátis](https://fonteza.com.br/app/login): 1.000 chamadas por dia. |
| Formato | Só `GET`, JSON em UTF-8. Sem SDK: qualquer cliente HTTP serve. |
| MCP | `https://fonteza.com.br/mcp` com `Authorization: Bearer fk_...`. [Instalar](https://fonteza.com.br/docs/agentes.md). |
| Contrato | [`/openapi.yaml`](https://fonteza.com.br/openapi.yaml), OpenAPI 3.1. Importe no Postman ou gere um cliente. |
| Para LLMs | [`/llms.txt`](https://fonteza.com.br/llms.txt), [`/llms-full.txt`](https://fonteza.com.br/llms-full.txt) e `.md` em qualquer página. |

## Rotas

| Rota | O que faz | Acesso |
| --- | --- | --- |
| [`GET /v1/buscar`](https://fonteza.com.br/docs/referencia/buscar.md) | Buscar empresas | chave |
| [`GET /v1/empresas/{cnpj}`](https://fonteza.com.br/docs/referencia/empresas-cnpj.md) | Obter o cadastro de uma empresa | chave |
| [`GET /v1/oportunidades`](https://fonteza.com.br/docs/referencia/oportunidades.md) | Buscar oportunidades no PNCP | chave |
| [`GET /v1/empresas/{cnpj}/despesas-federais`](https://fonteza.com.br/docs/referencia/empresas-cnpj-despesas-federais.md) | Listar despesas federais de uma empresa | chave |
| [`GET /v1/meta`](https://fonteza.com.br/docs/referencia/meta.md) | Consultar publicações e cobertura | pública |
| [`GET /healthz`](https://fonteza.com.br/docs/referencia/healthz.md) | Verificar o processo | pública |
| [`GET /v1/cnaes`](https://fonteza.com.br/docs/referencia/cnaes.md) | Encontrar códigos CNAE por atividade | pública |

## O que não é óbvio

- `/v1/buscar` só devolve estabelecimentos ativos (situação `02`). Para um CNPJ em qualquer situação, use [`/v1/empresas/{cnpj}`](https://fonteza.com.br/docs/referencia/empresas-cnpj.md).
- Nenhum resultado não quer dizer que não existe: a busca cobre só o período e o recorte publicados, informados em `meta`. Veja [Cobertura e procedência](https://fonteza.com.br/docs/cobertura.md).
- Buscas amplas respondem `409 busca_ampla_requer_confirmacao`. Refine os filtros ou repita com `confirmar_varredura=true`.
- Toda requisição com chave válida a uma rota de dados conta na cota, inclusive as que terminam em erro e as recusadas com `429`. Não há `Retry-After`: a cota renova na virada do dia. [Autenticação e cota](https://fonteza.com.br/docs/autenticacao.md).
- Oportunidades e despesas paginam por cursor preso à publicação. `409 geracao_*_expirada` significa recomeçar sem cursor. [Paginação](https://fonteza.com.br/docs/paginacao.md).
- Trate erros pelo `codigo`, não pela mensagem. Há três formatos de corpo. [Erros](https://fonteza.com.br/docs/erros.md).
- Campos da Receita mantêm o formato da fonte: datas `AAAAMMDD`, capital `150000,00`, códigos de porte e situação.
- Chame a partir do servidor. CORS bloqueia navegadores em outros domínios, e a chave não deve ir para o front-end.