Consumo de CEP com Spring Boot e ViaCEP
Descubra como integrar a API gratuita ViaCEP com seu backend em Spring Boot, realizar buscas de endereço por CEP e aplicar isso no seu sistema de cadastro.
Por que isso é importante
Toda aplicação que lida com cadastro de usuários ou fornecedores normalmente precisa validar e preencher dados de endereço a partir do CEP. Utilizar uma API gratuita como a ViaCEP permite reduzir custos com integrações pagas sem abrir mão da funcionalidade, garantindo agilidade e padronização nos formulários.
O que é a ViaCEP?
A ViaCEP é uma API pública e gratuita que permite consultas de endereços a partir de qualquer CEP válido do Brasil. Com uma simples requisição HTTP, é possível obter informações como logradouro, bairro, cidade, UF e muito mais.
Estrutura da URL de Consulta
A requisição para obter os dados do CEP segue esse padrão: https://viacep.com.br/ws/SEU_CEP/json/. Basta substituir SEU_CEP por um valor válido.
Preparando o Projeto Spring Boot
Criando o DTO de Retorno
Como a API retorna um JSON padronizado, podemos criar um record em Java com as propriedades esperadas. Exemplo:
public record CepResponse(String cep, String logradouro, String complemento, String bairro, String localidade, String uf, String ibge, String ddd)
Construindo o Controller
Agora criamos um @RestController com um método GET que recebe o CEP como parâmetro. Dentro desse endpoint fazemos a chamada usando RestTemplate.
Implementando o Endpoint
Dentro do controller criamos o método consultarCep:
@GetMapping("/consulta-cep/{cep}")
public CepResponse consultarCep(@PathVariable String cep) {
RestTemplate restTemplate = new RestTemplate();
String url = String.format("https://viacep.com.br/ws/%s/json/", cep);
ResponseEntity<CepResponse> response = restTemplate.getForEntity(url, CepResponse.class);
return response.getBody();
}
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.