ℹ️ Sobre: Esta API usa uma arquitetura de duas camadas: consulta local em arquivos JSON estáticos para CEPs conhecidos, com fallback automático para a API do ViaCEP quando necessário.
📋 Endpoints Disponíveis
1. Consulta por CEP
GET/ws/{cep}/{formato}/
Consulta informações de um CEP específico. Tenta primeiro o cache local, depois faz fallback para ViaCEP.
- {cep}
- CEP com 8 dígitos (sem hífen). Exemplo: 01001000
- {formato}
- Formato da resposta:
jsonouxml
Exemplo de requisição:
curl http://localhost:8080/ws/01001000/json/
Resposta (JSON):
{
"cep": "01001-000",
"logradouro": "Praça da Sé",
"complemento": "lado ímpar",
"bairro": "Sé",
"localidade": "São Paulo",
"uf": "SP",
"ibge": "3550308",
"gia": "1004",
"ddd": "11",
"siafi": "7107"
}
2. Pesquisa por Endereço
GET/ws/{UF}/{Cidade}/{Logradouro}/{formato}/
Busca CEPs por endereço (mínimo 3 caracteres no logradouro). Sempre usa proxy para ViaCEP.
- {UF}
- Sigla do estado (2 letras maiúsculas). Exemplo: RS, SP, RJ
- {Cidade}
- Nome da cidade (pode conter espaços). Exemplo: Porto Alegre
- {Logradouro}
- Nome da rua/avenida (mínimo 3 caracteres). Exemplo: Domingos
- {formato}
- Formato da resposta:
jsonouxml
Exemplo de requisição:
curl http://localhost:8080/ws/RS/Porto%20Alegre/Domingos/json/
Resposta (JSON) - Array de resultados:
[
{
"cep": "90035-030",
"logradouro": "Rua Domingos Rubbo",
"complemento": "",
"bairro": "Centro Histórico",
"localidade": "Porto Alegre",
"uf": "RS",
"ibge": "4314902",
"gia": "",
"ddd": "51",
"siafi": "8801"
},
...
]
3. Acesso Direto ao Cache Local
GET/v1/{cep}.json
Acessa diretamente o arquivo JSON local sem fallback. Retorna 404 se o CEP não estiver no cache.
Exemplo de requisição:
curl http://localhost:8080/v1/01001000.json
4. Health Check
GET/health
Verifica o status do serviço (não depende de APIs externas).
Exemplo de requisição:
curl http://localhost:8080/health
Resposta:
{
"status": "ok",
"service": "opencep-api",
"timestamp": "2025-10-17T14:30:00+00:00"
}
⚡ Arquitetura
Cache Local: A API mantém um banco de dados local com milhões de CEPs brasileiros em arquivos JSON estáticos, garantindo respostas ultrarrápidas sem dependência de serviços externos.
Fallback Inteligente: Se um CEP não for encontrado no cache local (CEPs novos ou atualizados), a API automaticamente consulta o ViaCEP e retorna o resultado, mantendo 100% de compatibilidade.
⚠️ Observações
CEP sem hífen: Os CEPs devem ser informados sem hífen (8 dígitos). Exemplo: use
01001000 ao invés de 01001-000.
Espaços nas URLs: Para pesquisa por endereço, use
%20 ou + para representar espaços nos nomes de cidades. Exemplo: Porto%20Alegre.
Mínimo de caracteres: A pesquisa por logradouro requer no mínimo 3 caracteres.