Como integrar consulta automática de CEP em formulário HTML

Por que integrar consulta de CEP em formulários

Cadastros com endereço são uma das maiores fontes de fricção e erro em formulários web. Quando o usuário precisa digitar manualmente cidade, bairro e estado, é comum errar acentuação, digitar nomes diferentes do oficial ou simplesmente abandonar o formulário. Integrar a consulta automática de CEP resolve isso: o usuário digita os 8 dígitos, e os campos de logradouro, bairro, cidade e UF se preenchem sozinhos. A taxa de conclusão de cadastros sobe e a qualidade do dado armazenado melhora drasticamente.

A estrutura básica do formulário

Antes do JavaScript, monte o HTML com IDs nos campos que serão preenchidos:

<form>
  <label>CEP
    <input type="text" id="cep" maxlength="9" placeholder="00000-000">
  </label>
  <label>Logradouro
    <input type="text" id="logradouro">
  </label>
  <label>Bairro
    <input type="text" id="bairro">
  </label>
  <label>Cidade
    <input type="text" id="cidade">
  </label>
  <label>UF
    <input type="text" id="uf" maxlength="2">
  </label>
  <label>Número
    <input type="text" id="numero">
  </label>
</form>

Versão simples com fetch

A forma mais direta é escutar o evento blur (quando o usuário sai do campo CEP) e disparar uma requisição para uma API pública de consulta:

document.getElementById('cep').addEventListener('blur', async (e) => {
  const cep = e.target.value.replace(/\D/g, '');
  if (cep.length !== 8) return;
  try {
    const res  = await fetch(`https://viacep.com.br/ws/${cep}/json/`);
    const data = await res.json();
    if (data.erro) {
      alert('CEP não encontrado');
      return;
    }
    document.getElementById('logradouro').value = data.logradouro || '';
    document.getElementById('bairro').value     = data.bairro     || '';
    document.getElementById('cidade').value     = data.localidade || '';
    document.getElementById('uf').value         = data.uf         || '';
    document.getElementById('numero').focus();
  } catch (err) {
    console.error('Erro ao consultar CEP:', err);
  }
});

Esse é o esqueleto. Funciona, mas falta polimento.

Boas práticas que você não pode ignorar

1. Aplique uma máscara visual no campo CEP

O usuário espera ver o hífen aparecer automaticamente no formato 00000-000:

document.getElementById('cep').addEventListener('input', (e) => {
  let v = e.target.value.replace(/\D/g, '');
  if (v.length > 5) v = v.slice(0, 5) + '-' + v.slice(5, 8);
  e.target.value = v;
});

2. Sempre permita edição manual

Algumas situações exigem que o usuário corrija o que veio da consulta — endereços novos que ainda não estão na base, condomínios, casas de fundos, sítios. Nunca trave os campos preenchidos automaticamente.

3. Faça debounce se você consultar a cada tecla

Se preferir consultar enquanto o usuário digita (em vez de no blur), aplique um debounce de pelo menos 400ms para evitar centenas de requisições desnecessárias.

4. Tenha um fallback se a API falhar

APIs públicas eventualmente saem do ar ou ficam lentas. Garanta que o formulário continue funcionando mesmo se a consulta falhar — o usuário deve poder digitar o endereço manualmente.

5. Valide o formato antes de consultar

Não desperdice requisições com CEPs incompletos ou inválidos. Cheque o formato (8 dígitos numéricos) antes de chamar a API.

Usando o pacote ceprua-autofill

Para evitar reinventar a roda, o pacote npm ceprua-autofill faz tudo isso (máscara, debounce, fallback, preenchimento) com poucas linhas de código:

npm install ceprua-autofill

import { autofill } from 'ceprua-autofill';
autofill({
  cep:        '#cep',
  logradouro: '#logradouro',
  bairro:     '#bairro',
  cidade:     '#cidade',
  uf:         '#uf',
});

O pacote tem builds ESM e UMD, funciona com qualquer framework (React, Vue, Svelte, jQuery ou nada) e é open source.

Validando o CEP do lado do servidor

Mesmo com consulta no front, sempre revalide o CEP no backend antes de salvar no banco. Usuários podem desabilitar JavaScript, manipular o DOM ou enviar dados via API direta. Uma simples chamada à mesma API do CEP no servidor garante que o endereço armazenado é real. E armazene o CEP sempre sem hífen (apenas 8 dígitos numéricos) — isso facilita queries, comparações e índices.

Performance: cache de consultas comuns

Se você opera um e-commerce com volume alto, considere cachear no seu próprio servidor as consultas mais frequentes. CEPs de grandes capitais são consultados milhares de vezes por dia — cachear por 24h reduz drasticamente o número de chamadas externas e melhora o tempo de resposta do checkout. Em Redis isso é trivial:

SET cep:01310100 '{"logradouro":"Av. Paulista",...}' EX 86400

Com TTL de 1 dia, você mantém a base atualizada sem sobrecarregar nem o seu sistema nem a API externa.