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
./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
<code>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 )</code>
Construindo o Controller
Cria <code>@RestController</code> com método <code>GET</code> que recebe CEP. Chama API usando RestTemplate .
Implementando o Endpoint
Dentro do controller criamos o método <code>consultarCep</code> :
<code></code>
Testando com HTTP Request
Se você estiver utilizando IntelliJ Ultimate, pode criar um arquivo <code>.http</code> para realizar requisições diretas ao seu endpoint durante o desenvolvimento.
Exemplo de Requisição
Supondo que a aplicação esteja rodando em <em>localhost:8080</em> , 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 <code>erro:true</code> . 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 <code>Spring WebFlux</code> , 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 <code>request.http</code> . 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
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.