# PontoFato — referência completa da API > Gerada do catálogo em https://pontofato.com · build `dev` > 1 endpoints · 2 estruturas · fatia `/api/sugerir` > Índice curto: https://pontofato.com/llms.txt · Spec: https://pontofato.com/openapi.json · MCP: https://pontofato.com/mcp > Referência completa para consultar endereços, empresas no CEP e vizinhança. - [Também disponível na PayAPI Market](https://payapi.market/api/pontofato) ## Serviços grátis e pagos - [Franquias e preços vigentes](https://pontofato.com/api/pricing) - [Meios e condições de pagamento](https://pontofato.com/api/billing) - [Primeira chamada e recuperação de pagamento](https://pontofato.com/skill.md) ## Como ler - Cada endpoint traz caminho, auth, parâmetros, corpo, estrutura da resposta, erros e uma chamada que roda. - `Pagina` é referência: os campos estão em **Estruturas**, no fim, uma vez só. - `(opcional)` num campo quer dizer que ele pode não vir; `(pode ser null)` quer dizer que vem com valor nulo. - Se uma rota ou tool falhar ou devolver erro inesperado, avise o operador por `POST /api/contact` com `{"tipo":"problema","categoria":"erro_api","contexto":"MÉTODO /api/...","mensagem":"status e erro recebido"}` (sem conta e sem pagamento). - Fatie o que precisa: `https://pontofato.com/llms-full.txt?prefix=/api/` devolve só aquele ramo. ## Autenticação - `none` — Público. - `token` — Token de operador `METRICS_TOKEN` em `Authorization: Bearer` (métricas). - `credito` — Token de crédito em `Authorization: Bearer cred_…` (ou `X-Credito`). Para saldo recuperado de x402, use a credencial de carteira `mmw_…` em Bearer ou `X-Wallet-Token`, emitida por `/api/auth/wallet/agent/start` e `/api/auth/wallet/agent/token`. - `session` — Sessão global em cookie HttpOnly do produto; escritas exigem Origin exato e X-CSRF-Token. ## Endpoints ## Lugar ### `GET /api/sugerir` Sugestões de CEP parcial ou nome de rua, com bairro e cidade. Até oito lugares. CEP aceita prefixo de 3 a 8 dígitos, com hífen opcional após o quinto. Rua usa UF e cidade opcionais. Um endereço representa cada CEP; a consulta completa traz os demais. Referência CNEFE 2022, sem certificar CEP postal vigente. - **URL:** `https://pontofato.com/api/sugerir` - **Auth:** `none` — Público. **Query** - `q` (string, obrigatório) — CEP parcial ou rua, de 3 a 160 caracteres. Ex.: `71915`. - `uf` (string) — Sigla da UF para restringir a busca por rua. - `cidade` (string) — Município para restringir a busca por rua. **Resposta `200`** Estrutura: `SugestoesDeLugares`. - `items` (SugestaoDeLugar[]) — Até oito lugares, sem repetição de CEP na busca numérica. → ver `SugestaoDeLugar` em **Estruturas**. - `incompleto` (bool) — Há outros candidatos; continue digitando. **Erros** - `400` — Termo curto, longo ou prefixo de CEP inválido. - `503` — Sugestões indisponíveis. **Exemplo** ```sh curl -s 'https://pontofato.com/api/sugerir?q=71915' ``` ## Estruturas ### `SugestoesDeLugares` Lista limitada de sugestões. Não consome consulta paga. - `items` (SugestaoDeLugar[]) — Até oito lugares, sem repetição de CEP na busca numérica. → ver `SugestaoDeLugar` em **Estruturas**. - `incompleto` (bool) — Há outros candidatos; continue digitando. ### `SugestaoDeLugar` Lugar sugerido pelo CEP ou pela rua. - `tipo` (string) — `cep` ou `rua`. - `cep8` (string) — Oito dígitos do CEP, ou vazio quando ausente. - `cep` (string) — CEP formatado, ou vazio. - `logradouro` (string) — Rua do endereço representativo. - `bairro` (string) — Bairro cadastrado. - `cidade` (string) — Município. - `uf` (string) — Sigla da UF.