API para desenvolvedores

01 Introdução

A API REST do CEP Busca entrega, em JSON, os mesmos dados que você vê no site: endereço por CEP, busca textual, estados, municípios e cobertura de DDD. Serve para ERP, checkout, logística, CRM e ferramentas internas.

O que esta API faz (e o que não faz)

Faz: lookup de CEP, busca por texto, listagens geográficas e DDD.
Não faz: rastreio de encomendas, prazo/frete dos Correios ou alteração de cadastro postal.

Fontes públicas

IBGE Localidades (municípios), IBGE CNEFE (endereços/coords), RFB/CNPJ (estabelecimentos) e Anatel PGCN (DDD).

Sem Correios

Zero scraping e zero base proprietária dos Correios. Tudo vem de dados abertos brasileiros.

Disponibilidade

Monitore com GET /api/v1/health: status do banco, versão e contagens aproximadas.

02 Início rápido

Três passos para a primeira consulta. Não precisa de cadastro enquanto a API estiver em modo público.

1
Teste o status
Chame /health (sempre público). Se ok: true e database: "up", a API está operacional.
2
Consulte um CEP
No path, use exatamente 8 dígitos, sem hífen — ex.: /cep/01310100. A resposta já devolve o CEP formatado.
3
Integre no seu sistema
Copie os curls, importe o OpenAPI no Postman/Insomnia ou use o playground abaixo.

Dica

Se a busca for um texto de 8 dígitos (ex.: 01310100), /busca?q= faz lookup direto de CEP automaticamente.

curl · health · público

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

curl · CEP · Avenida Paulista

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

03 Autenticação

Por padrão a API é pública (api.require_key=false). Quando o painel ativar “Exigir API key”, a maioria dos endpoints passa a exigir credencial.

Importante sobre a chave

Nunca coloque a chave no frontend (JavaScript do navegador). Use um backend/proxy. A chave completa aparece só na criação e pode ser revogada a qualquer momento.

Recomendado X-Api-Key: cep_sua_chave

Header dedicado — preferido em clientes HTTP e SDKs.

Alternativa Authorization: Bearer cep_sua_chave

Padrão OAuth-like, útil em gateways e proxies.

Query ?api_key=cep_sua_chave

Só para testes rápidos — evite em produção (aparece em logs/URLs).

Gerencie chaves em /pipeline/api-keys. Sempre públicos: /health, docs e OpenAPI. Rate limit: req/minuto por chave.

04 Playground

Execute uma chamada real neste navegador. Os botões preenchem rotas de exemplo; o painel mostra o status HTTP e o JSON formatado.

Caminho relativo (a partir de CEP Busca)

GET

Ex.: /api/v1/cep/01310100 ou /api/v1/busca?q=centro&uf=RJ&limit=5

Clique em Executar para ver a resposta JSON ao vivo.

05 Formato de resposta

Em sucesso, o corpo é o próprio recurso (objeto CEP, lista, etc.). Em erro, sempre há ok: false, error (mensagem legível) e status (código HTTP).

Campos principais do CEP

cepFormatado #####-###

cep_digits8 dígitos puros

cidade / ufLocalidade

cidade_ibgeCódigo IBGE 7 dígitos

dddCódigo telefônico Anatel

bairro / logradouroEndereço

latitude / longitudeCoords do CEP (quando CNEFE)

fontesArray JSON das origens

Coords do município ≠ coords do logradouro

municipio_latitude/longitude apontam a sede municipal. latitude/longitude do CEP vêm do CNEFE quando disponíveis e podem diferir.

json · sucesso · CEP

{
  "cep": "01310-100",
  "cep_digits": "01310100",
  "uf": "SP",
  "cidade": "São Paulo",
  "cidade_ibge": "3550308",
  "ddd": 11,
  "bairro": "Bela Vista",
  "logradouro": "AVENIDA PAULISTA",
  "latitude": -23.554893,
  "longitude": -46.663839,
  "fonte": "mixed",
  "fontes": ["cnefe", "cnpj_rfb"],
  "url": "/cep/01310100"
}

json · erro · 404

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

06 Mapa de endpoints

URL base: https://cepbusca.com/api/v1. Todos os métodos abaixo são GET. “Condicional” = exige chave só se o painel estiver com chave obrigatória.

Recurso	Método	Rota	Auth
Health	GET	`/health`	Público
CEP	GET	`/cep/{cep}`	Condicional
Busca	GET	`/busca?q=&uf=&limit=`	Condicional
Estados	GET	`/estados`	Condicional
Estado	GET	`/estados/{uf}`	Condicional
Cidades da UF	GET	`/estados/{uf}/cidades`	Condicional
CEPs da cidade	GET	`/cidades/{ibge}/ceps`	Condicional
Município	GET	`/municipios/{ibge}`	Condicional
DDD do município	GET	`/municipios/{ibge}/ddd`	Condicional
Lista DDDs	GET	`/ddds`	Condicional
DDDs por estado	GET	`/ddds/por-estado`	Condicional
Municípios do DDD	GET	`/ddds/{ddd}`	Condicional
Gerador	GET	`/gerador-cep?uf=`	Condicional
OpenAPI	GET	`/openapi.yaml`	Público

CEP e busca

GET /cep/{cep}

Retorna endereço completo, DDD, gentílico, prefeito (quando houver), coordenadas e lista de fontes. Path: 8 dígitos obrigatórios.

cep path — só números, ex. 01310100

curl

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

GET /busca?q=&uf=&limit=

Busca textual em logradouro, bairro e cidade (ILIKE), ordenada por relevância de ocorrências. Ideal para autocomplete e validação parcial.

q query — texto ou CEP de 8 dígitos
uf query — opcional (SP, RJ…)
limit query — 1 a 50 (padrão 20)

curl

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

GET /gerador-cep?uf=

Sorteia um CEP real da base (não inventa números). Sem uf, o sorteio é ponderado pela quantidade de CEPs de cada estado.

Geografia e DDD

GET /estados · /estados/{uf} · /estados/{uf}/cidades

Lista as 27 UFs com capital e faixa de CEP; detalhe do estado com estatísticas (cidades, CEPs, DDDs); municípios da UF.

GET /cidades/{ibge}/ceps?page=&limit=

CEPs do município, paginados. A resposta inclui total, pages e count da página atual. limit máximo: 200.

GET /municipios/{ibge} · /ddds · /ddds/{ddd}

Ficha municipal (DDD, gentílico, prefeito, coords da sede) e cobertura Anatel: lista de DDDs ou municípios de um código (ex.: 11).

07 Códigos HTTP

Trate o status HTTP e o campo error do JSON. Em 404 de CEP inexistente, o corpo continua sendo JSON (não HTML).

200OK — recurso retornado

400CEP/UF ou parâmetro inválido

401API key ausente ou inválida

404CEP, UF, município ou rota inexistente

405Use apenas GET (ou HEAD/OPTIONS)

429Rate limit da chave excedido

500Erro interno — tente de novo

08 Casos de uso

Exemplos práticos de como encaixar a API no seu fluxo.

Formulários e checkout

Ao digitar o CEP, preencha automaticamente cidade, UF, bairro e DDD — menos erro de digitação.

GET /cep/{cep}

Logística e mapas

Valide endereços e, quando houver CNEFE, use lat/lon para plotar ou estimar proximidade.

GET /busca?q=…

QA, seeds e mocks

Gere CEPs reais por UF para testes automatizados — passam em validação de 8 dígitos.

GET /gerador-cep?uf=SP

Telefonia / DDD

Descubra quais municípios um DDD cobre, ou o DDD de um código IBGE.

GET /ddds/11

09 Perguntas frequentes

A API é gratuita?

Sim, no modo público padrão. Chaves no painel são opcionais e servem para controle, auditoria e rate limit por integração.

Posso usar hífen no CEP da URL?

Não no path. Use só dígitos: /cep/01310100. O campo cep da resposta já vem como 01310-100.

De onde vêm os dados?

IBGE (localidades + CNEFE), estabelecimentos RFB/CNPJ e DDD Anatel (PGCN). Não usamos Correios.

O que significa fonte / fontes?

cnefe, cnpj_rfb ou mixed (ambas). O campo fontes é sempre um array JSON, nunca a string {a,b} do PostgreSQL.

Como importar no Postman?

Importe /api/v1/openapi.yaml. Se a chave for obrigatória, configure o header X-Api-Key no ambiente.

Posso chamar do navegador (CORS)?

Sim — a API envia Access-Control-Allow-Origin: *. Para produção com chave, prefira um backend para não expor a credencial.

10 Suporte

Precisa de chave, tem dúvida de integração ou encontrou inconsistência nos dados? Fale conosco com o máximo de contexto (endpoint, horário, status HTTP e trecho da resposta).

Ao pedir ajuda, inclua

URL chamada · status HTTP · trecho do JSON de erro · se usou API key (sem colar a chave secreta).

E-mail [email protected] OpenAPI Spec YAML para Postman / SDK Contato Canais institucionais do site

Referência textual: docs/API.md · Health: /api/v1/health