# API CEP Busca — Referência completa

> **Base:** `https://cepbusca.com/api/v1`  
> **Versão:** 1.1 · **Atualizado:** 26/08/2026  
> **Docs interativa:** https://cepbusca.com/desenvolvedores  
> **OpenAPI:** https://cepbusca.com/api/v1/openapi.yaml

API REST pública (somente leitura) para consulta de CEP, municípios e DDD.  
Fontes: **IBGE** (Localidades + CNEFE), **RFB** (estabelecimentos CNPJ) e **Anatel** (PGCN).  
**Não usa Correios.**

---

## 1. Visão geral

| Item | Valor |
|------|--------|
| Protocolo | HTTPS + JSON UTF-8 |
| Métodos | `GET`, `HEAD`, `OPTIONS` |
| Autenticação | Pública por padrão; opcional via API key |
| CORS | `Access-Control-Allow-Origin: *` |
| Rate limit | Por chave (`api_keys.rate_limit` req/min) quando autenticado |

### API keys (opcional)

Gerencie em https://cepbusca.com/pipeline/api-keys.  
Se `api.require_key=true`, endpoints (exceto health/docs/openapi) exigem:

- Header `X-Api-Key: cep_…`, ou
- `Authorization: Bearer cep_…`, ou
- Query `?api_key=cep_…`

Sem chave válida → `401`. Acima do limite → `429`.

### Estado atual da base (26/08/2026)

| Entidade | Quantidade |
|----------|------------|
| Estados | 27 |
| Cidades | 5.571 |
| Cidades com DDD | 5.571 |
| Cidades com coordenadas | 5.571 |
| Bairros | ~120.345 |
| Logradouros | ~2.248.545 |
| CEPs | ~1.293.955 |
| CEPs com lat/lon | ~931.499 |
| DDDs distintos | 67 |

Fontes nos CEPs: `mixed` (CNEFE+RFB), `cnpj_rfb`, `cnefe`.

---

## 2. Endpoints

### `GET /health`

Saúde do serviço, ping no banco e estatísticas.

```bash
curl -s https://cepbusca.com/api/v1/health
```

### `GET /cep/{cep}`

Consulta por CEP. Path deve ter **exatamente 8 dígitos** (sem hífen).

```bash
curl -s https://cepbusca.com/api/v1/cep/01310100
```

**200 — sucesso**

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `cep` | string | Formatado `#####-###` |
| `cep_digits` | string | 8 dígitos |
| `uf` | string | UF |
| `cidade` | string | Nome do município |
| `cidade_ibge` | string | Código IBGE 7 dígitos |
| `ddd` | int\|null | DDD Anatel |
| `gentilico` | string\|null | Gentílico |
| `prefeito` | string\|null | Prefeito (quando disponível) |
| `prefeito_ano` | int\|null | Ano de referência |
| `municipio_latitude` | number\|null | Sede do município |
| `municipio_longitude` | number\|null | Sede do município |
| `bairro` | string\|null | Bairro |
| `logradouro` | string\|null | Logradouro completo |
| `tipo_logradouro` | string\|null | Ex.: RUA, AVENIDA |
| `complemento` | string\|null | Complemento |
| `latitude` / `longitude` | number\|null | Coordenada do CEP (CNEFE quando houver) |
| `fonte` | string | `mixed`, `cnefe` ou `cnpj_rfb` |
| `fontes` | string[] | Lista de fontes (array JSON) |
| `url` | string | Path da página SEO |

**400** — CEP com formato inválido  
**404** — CEP inexistente na base

### `GET /busca`

Busca textual em logradouro, bairro e cidade (`ILIKE`). Se `q` for um CEP de 8 dígitos, faz lookup direto.

| Param | Default | Descrição |
|-------|---------|-----------|
| `q` | (obrigatório) | Texto ou CEP |
| `uf` | — | Filtra por UF (`SP`, `RJ`…) |
| `limit` | 20 | 1–50 |

```bash
curl -s "https://cepbusca.com/api/v1/busca?q=paulista&uf=SP&limit=5"
```

### `GET /estados`

Lista os 27 estados com capital e faixa oficial de CEP.

### `GET /estados/{uf}`

Detalhe do estado + `stats` (`cidades`, `ceps`, `ddds`).

### `GET /estados/{uf}/cidades`

Municípios da UF (payload enxuto: IBGE, nome, DDD, coords, slug).

### `GET /cidades/{ibge}/ceps`

CEPs do município, paginado.

| Param | Default | Descrição |
|-------|---------|-----------|
| `page` | 1 | Página (≥1) |
| `limit` | 50 | 1–200 |

Resposta inclui `total`, `pages`, `count`, `results`.

### `GET /municipios/{ibge}`

Dados municipais enriquecidos (DDD, gentílico, prefeito, lat/lon, regiões).

### `GET /municipios/{ibge}/ddd`

Apenas o DDD (fonte `anatel_pgcn`).

### `GET /ddds`

Lista de DDDs com contagem de municípios, UFs e regiões.

### `GET /ddds/por-estado`

DDDs agrupados por UF.

### `GET /ddds/{ddd}`

Municípios cobertos pelo DDD (ex.: `11`).

### `GET /gerador-cep`

Retorna um CEP **real** aleatório da base (sorteio ponderado por UF quando sem filtro).

```bash
curl -s "https://cepbusca.com/api/v1/gerador-cep?uf=SP"
```

### `GET /validar-ceps`

Valida até **20** CEPs de uma vez. Aceita lista separada por vírgula, espaço ou ponto e vírgula.

Status por item: `valid`, `invalid_format`, `not_found` (ou `unverified` se a consulta falhar).

```bash
curl -s "https://cepbusca.com/api/v1/validar-ceps?ceps=01310100,99999,00000000"
```

### Documentação

| URL | Conteúdo |
|-----|----------|
| `/desenvolvedores` | Página HTML interativa (layout do site) |
| `/api/v1/openapi.yaml` | Spec OpenAPI 3.0 |

---

## 3. Códigos HTTP

| Código | Significado |
|--------|-------------|
| 200 | Sucesso |
| 204 | Resposta a `OPTIONS` |
| 400 | Parâmetro inválido |
| 404 | Recurso não encontrado (`ok: false`) |
| 405 | Método não permitido |
| 500 | Erro interno |

Formato de erro:

```json
{
  "ok": false,
  "error": "CEP não encontrado",
  "status": 404,
  "cep": "99999999"
}
```

---

## 4. Modelo de dados (origem)

```
estados 1───N cidades 1───N ceps
                │
                ├── ddd, gentilico, prefeito, lat/lon (enriquecimento)
                └── Anatel PGCN (DDD)

ceps.source / ceps.sources[] ← cnefe | cnpj_rfb | mixed
```

Implementação PHP: `api/index.php` + `lib/db.php`.

---

## 5. Notas de integração

1. Sempre use **8 dígitos** no path do CEP (não envie hífen na URL).
2. Campo `fontes` é **array JSON** (não string PostgreSQL).
3. Coordenadas de município ≠ coordenadas do logradouro (podem diferir).
4. Alguns CEPs RFB podem ter logradouro genérico ou CEP atípico; priorize `fonte=mixed` quando disponível.
5. Página humana equivalente: `/cep/{digits}`, `/estado/{uf}`, `/estado/{uf}/{slug}`, `/ddd/{n}` (UF minúscula).

---

## 6. Changelog

### 1.1 — 26/08/2026

- Payloads públicos limpos (estados/cidades sem campos internos)
- `fontes` como array JSON
- Paginação com `total`/`pages` em CEPs por cidade
- Novos: `/estados/{uf}`, `/ddds/{ddd}`, `/ddds/por-estado`, `/docs`, OpenAPI
- Busca com filtro `uf`
- Health com status do banco + lista de endpoints
- Erros JSON consistentes (`ok`, `error`, `status`)
- Correção nginx: 404 da API deixa de virar HTML do painel