Uma API de CEP ajuda a preencher rua, bairro, cidade e UF depois que uma pessoa informa o código postal. Ela não confirma o número do imóvel, o nome do destinatário nem a disponibilidade de entrega. Por isso, a integração deve facilitar o cadastro sem impedir que a pessoa corrija os campos.
O exemplo abaixo usa o ViaCEP, que publica a URL, os formatos de resposta e o comportamento para CEP inválido ou inexistente. Verifique as condições atuais do serviço antes de usá-lo em grande volume. Os Correios também têm uma API Busca CEP, que, segundo o manual, é voltada a clientes com contrato comercial e exige autenticação.
O que a API recebe e devolve
Para consultar um código, envie oito dígitos para https://viacep.com.br/ws/01001000/json/. Para o exemplo da Praça da Sé, a resposta contém campos como logradouro, bairro, localidade e uf. Um CEP com formato inválido recebe HTTP 400; um CEP de oito dígitos que não existe retorna JSON com erro: true. São dois casos diferentes e ambos precisam ser tratados.
Exemplo mínimo em JavaScript
async function consultarCep(entrada) {
const cep = entrada.replace(/\D/g, '')
if (cep.length !== 8) {
throw new Error('Informe um CEP com oito dígitos.')
}
const resposta = await fetch('https://viacep.com.br/ws/' + cep + '/json/')
if (!resposta.ok) {
throw new Error('Não foi possível consultar o CEP agora.')
}
const dados = await resposta.json()
if (dados.erro) return null // Código não encontrado
return {
rua: dados.logradouro || '',
bairro: dados.bairro || '',
cidade: dados.localidade || '',
uf: dados.uf || '',
}
}Chame a função depois que a pessoa completar o CEP ou sair do campo. Se ela continuar digitando durante a consulta, evite aplicar uma resposta antiga sobre os dados novos. Mostre um estado de carregamento e uma mensagem clara quando o serviço estiver indisponível; mantenha o formulário editável. Para validar o formato antes da chamada, com regex e máscara, veja como validar CEP.
Quando o resultado não traz a rua
Um CEP de localidade pode retornar somente cidade e UF. Não preencha uma rua inventada, não esconda o campo de logradouro e não conclua que o CEP é inválido. Peça que a pessoa informe o endereço completo e confira o código na consulta de CEP do RuaCEP em caso de dúvida. O guia de tipos de CEP explica por que isso acontece.
Busca inversa: quando o usuário não sabe o código
O ViaCEP também aceita consulta por UF, cidade e logradouro. Cidade e logradouro devem ter pelo menos três caracteres. A resposta pode incluir até 50 CEPs, então não selecione o primeiro automaticamente: mostre as opções e permita comparar bairro e trecho. A URL de exemplo publicada pelo serviço é https://viacep.com.br/ws/RS/Porto%20Alegre/Domingos/json/. Para conferir um endereço manualmente, use a busca de CEP pelo endereço.
Dados para testar o formulário
Para testes, use CEPs reais em vez de números inventados, que podem não existir. O gerador de CEP sorteia códigos cadastrados por estado, e o formatador de CEP padroniza listas com e sem hífen antes de uma importação.
Cuidados antes de colocar em produção
- Valide o formato antes da chamada: remova espaços e hífen, depois confira os oito dígitos.
- Trate erro de rede, HTTP e CEP inexistente separadamente: um serviço fora do ar não prova que o endereço não existe.
- Não substitua o endereço informado pela pessoa sem revisão: mantenha número e complemento manuais.
- Confirme o CEP para envios importantes: uma API de terceiros pode divergir da consulta oficial dos Correios.
- Planeje o volume: o ViaCEP avisa que uso massivo para validar bases locais pode bloquear o acesso. Avalie cache e uma fonte contratual se o negócio precisa de disponibilidade garantida.
Se uma API não encontrar um código exibido em outra consulta, siga o roteiro de CEP inválido ou não encontrado. Para calcular frete, também serão necessários os dados exigidos pelo serviço de entrega; o CEP sozinho não determina um preço.
