# Montar uma busca

Escolha os filtros de [`/v1/buscar`](https://fonteza.com.br/docs/referencia/buscar.md) e copie a requisição pronta em curl, Python ou JavaScript. Campos vazios ficam fora da requisição, e valores iguais ao padrão da API também.

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();
```

## Como ler a requisição

- `-G` com `--data-urlencode` envia cada filtro na query string já codificado: acentos e espaços, como em `municipio=São Paulo`, chegam corretos.
- Informe `q`, `cnae` ou os dois. Os demais filtros só refinam o resultado.
- No campo `cnae`, digite a atividade (restaurante, dentista) e escolha uma sugestão: o construtor consulta [`/v1/cnaes`](https://fonteza.com.br/docs/referencia/cnaes.md), rota pública que não usa chave nem cota, e preenche os códigos. Até 10 códigos, separados por vírgula. Filtrar por CNAE usa o índice e é mais rápido e preciso que procurar a palavra em `q`.
- A resposta traz `meta.plano`: `varredura_ampla` diz se a busca lê uma parte grande da base. Sem `cnae`, uma varredura ampla responde `409` com `cnaes_sugeridos`; repita com um desses códigos ou confirme com `confirmar_varredura=true`.
- `tem_telefone` e `tem_email` aceitam `true` (exige o contato) ou `false` (exige a ausência). Sem eles, tanto faz.
- Para o município, envie também `uf`. Um nome desconhecido ou fora da UF devolve `422` com sugestões.
- Cada execução é uma chamada e conta na cota da chave, mesmo quando termina em erro. Veja [Autenticação e cota](https://fonteza.com.br/docs/autenticacao.md).

## Executar no painel

No [painel](https://fonteza.com.br/app), o Console da API monta a mesma requisição e a executa com a chave do painel, sem copiar nenhuma chave. As execuções contam na cota diária dessa chave e aparecem em Uso.