ViaCEP + Spring Boot: API de CEP gratuita
API de CEP com Spring Boot e ViaCEP: contrato, cache e fallback sem inventar SLA.
Por que isso é importante
API gratuita de CEP com Spring: CRUD de consulta com cache e contrato claro.
Leitura relacionada: DTO, DAO e Repository · Ordem para aprender Spring · Arquitetura na era da IA · Cursos CrazyStack.
ViaCEP: o que validar antes de depender
O ViaCEP é uma das APIs públicas de CEP mais usadas no Brasil (HTTPS, JSON). Não trate blog posts como SLA: confira limites e disponibilidade na documentação oficial e planeje fallback (outro provider ou cache) se o endpoint for crítico.
Endpoints e formatos (confira o oficial)
Base típica: https://viacep.com.br/ws/{cep}/json/ . Formatos comuns incluem JSON (e variantes documentadas no site). Evite assumir endpoints “batch” ou métricas de CDN sem confirmar na documentação atual do provider.
Preparando o Projeto Spring Boot
- Passo 1: Spring Initializr: Java 21 LTS, Spring Boot 3.2.2,
dependências: Web, WebFlux, Validation . Maven/Gradle conforme
preferência. - Passo 2: IDE recomendada: IntelliJ IDEA (melhor Spring support) ou VS Code com Spring Boot Extension Pack.
- Passo 3: Valide setup:
./mvnw spring-boot:run.
Deve inicializar em ~3s no Java 21 (vs 5s no Java 17).
DTO com Java Records e Validação
Records (Java 16+ em produção estável) reduzem boilerplate de DTOs. O ViaCEP costuma devolver campos como cep, logradouro, complemento, bairro, localidade, uf, ibge, gia e ddd — mapeie só o que seu domínio precisa.
Código Otimizado
public record CepResponse( @JsonProperty("cep") @NotBlank String cep,
@JsonProperty("logradouro") String logradouro, @JsonProperty("bairro") String
bairro, @JsonProperty("localidade") String cidade, @JsonProperty("uf") @Size(min =
2, max = 2) String estado )
Construindo o Controller
Cria @RestController com método GET que recebe CEP. Chama API usando RestTemplate .
Implementando o Endpoint
Dentro do controller criamos o método consultarCep :
Testando com HTTP Request
Se você estiver utilizando IntelliJ Ultimate, pode criar um arquivo .http para realizar requisições diretas ao seu endpoint durante o desenvolvimento.
Exemplo de Requisição
Supondo que a aplicação esteja rodando em localhost:8080 , a chamada será: GET http://localhost:8080/consulta-cep/88804440 .
Dados Retornados
O resultado da API inclui, dentre outros campos: cep , logradouro , bairro , localidade , uf , ibge e ddd . Usando o DTO, você
poderá mapear essas informações e tratá-las no seu sistema.
Tratando CEPs Inválidos
Atenção
Quando um CEP é inválido ou não encontrado, o retorno será um JSON vazio ou com o
campo erro:true . Certifique-se de tratar esse caso para evitar erros no
frontend ou registros incorretos.
Melhorias Futuras
Você pode criar uma camada de serviço para delegar a lógica de consumo da API, adicionar
cache para CEPs mais utilizados, ou criar uma interface na sua aplicação para teste
visual.
Alternativas Pagas
Info
Existem APIs pagas com mais recursos e SLAs garantidos. A ViaCEP é ótima para projetos
pessoais, protótipos ou aplicações que aceitam eventual lentidão ou indisponibilidade.
Quando Usar o RestTemplate
Dica Técnica
O RestTemplate ainda é amplamente utilizado, mas para novos projetos
a recomendação do Spring é usar o WebClient do módulo Spring WebFlux , que é não bloqueante e mais performático.
Organizando seu Projeto
Separe bem suas responsabilidades: DTOs, Controllers e Services. Evite lógica replicada
no controller e mantenha seus códigos limpos e legíveis.
Atalhos no IntelliJ
Produtividade
Com o IntelliJ Ultimate você pode executar testes HTTP direto da IDE com um arquivo request.http . Se quiser adquirir, use cupons oficiais disponíveis na
internet para obter descontos.
Evite Serviços Abusivos
Atenção
Evite hardcodear URLs ou confiar unicamente na disponibilidade da API pública em
produção. Sempre prepare o sistema para contingências.
Combinando com Formulários Frontend
Com a integração pronta no backend, você pode acionar esse endpoint via JavaScript ou
frameworks como React e preencher dinamicamente os campos de endereço no seu formulário.
Validação de CEP
Antes de realizar a chamada à API, valide se o CEP possui 8 dígitos numéricos. Evite
chamadas desnecessárias e melhore a experiência do usuário.
Aplicações Práticas
Ideal para sistemas de CRM, ERPs, cadastros de clientes, distribuidores, prestadores de
serviço ou qualquer sistema que precise normalizar endereços automaticamente.
Checklist de Implementação
- Criou o projeto com Spring Web no Initializr
- Implementou o DTO mapeando os campos do ViaCEP
- Construiu o endpoint GET com RestTemplate
- Testou requisições com arquivo .http, Postman ou Insomnia
- Tratou casos de CEP inválido ou não encontrado
- Documentou ou integrou com o frontend
Perguntas frequentes
Como fazer API de CEP com Spring?
Endpoint que consulta provider, cacheia e devolve JSON tipado. Trate CEP inválido com 400.
Gratuita até quando?
Depende do provider. Tenha fallback.
Serve de portfolio?
Sim se tiver testes e README.
E rate limit?
Obrigatório se público.
Continue explorando
Perguntas frequentes
Como fazer API de CEP com Spring Boot?
Crie um endpoint que valida o CEP, consulta o ViaCEP (ou outro provider), mapeia para um DTO e trata resposta vazia/`erro:true` com 400/404 claros.
ViaCEP é sempre gratuita e estável?
É popular e gratuita para muitos casos, mas limites e disponibilidade mudam. Tenha fallback e não invente SLA — leia a documentação oficial.
RestTemplate, RestClient ou WebClient?
Em apps imperativos novos, prefira RestClient. WebClient encaixa em stacks reativas. RestTemplate ainda aparece em legado.
Preciso de cache?
Sim se o mesmo CEP se repete muito. Comece in-memory; Redis quando houver escala e múltiplas instâncias.