Como integrar CEP em formulários e sistemas

Por que integrar uma API de CEP no seu sistema

Digitar endereço manualmente é lento e sujeito a erros. Com uma API de CEP, o usuário informa apenas o código postal e o sistema preenche automaticamente rua, bairro, cidade e estado — o número e o complemento ficam para o usuário confirmar. Essa funcionalidade, conhecida como autofill de endereço, reduz erros de cadastro, diminui o abandono de formulários e melhora a qualidade dos dados no banco.

A API gratuita do CepRua

O CepRua oferece uma API REST gratuita sem necessidade de cadastro ou chave de acesso.

Endpoint

GET https://ceprua.com.br/api/cep/{cep}

Exemplo de requisição

curl https://ceprua.com.br/api/cep/01310-100

Exemplo de resposta

{
  "cep": "01310-100",
  "logradouro": "Avenida Paulista",
  "complemento": "de 1 a 610 - lado par",
  "bairro": "Bela Vista",
  "cidade": "São Paulo",
  "uf": "SP",
  "ibge": "3550308"
}

Integrando em JavaScript (fetch)

async function buscarCep(cep) {
  const cepLimpo = cep.replace(/\D/g, '');
  if (cepLimpo.length !== 8) return null;
  const res = await fetch(`https://ceprua.com.br/api/cep/${cepLimpo}`);
  if (!res.ok) return null;
  return await res.json();
}
// Uso em um formulário
document.getElementById('cep').addEventListener('blur', async function () {
  const dados = await buscarCep(this.value);
  if (!dados) return;
  document.getElementById('logradouro').value = dados.logradouro;
  document.getElementById('bairro').value     = dados.bairro;
  document.getElementById('cidade').value     = dados.cidade;
  document.getElementById('uf').value         = dados.uf;
});

Integrando em PHP

function buscarCep(string $cep): ?array
{
    $cepLimpo = preg_replace('/\D/', '', $cep);
    if (strlen($cepLimpo) !== 8) return null;
    $url      = "https://ceprua.com.br/api/cep/{$cepLimpo}";
    $response = file_get_contents($url);
    if ($response === false) return null;
    return json_decode($response, true);
}

Biblioteca npm: ceprua-autofill

Para projetos JavaScript, o CepRua oferece a biblioteca ceprua-autofill no npm, que automatiza o preenchimento de formulários com uma única linha de configuração.

npm install ceprua-autofill

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

Boas práticas de integração

Cache no cliente — evite consultar a API toda vez que o usuário digita. Faça a requisição apenas quando o campo CEP perder o foco (blur) ou quando o usuário colar um valor com 8 dígitos. Tratamento de erro — nem todo CEP retorna dados completos. Sempre permita que o usuário preencha os campos manualmente caso a API não encontre o endereço. Validação antes da requisição — cheque se o CEP tem exatamente 8 dígitos numéricos antes de chamar a API. Isso evita requisições desnecessárias. Não bloqueie o formulário — o preenchimento automático é uma conveniência, não uma obrigação. O formulário deve funcionar mesmo sem a integração ativa.

Limites de uso

A API do CepRua é gratuita para uso normal. Para integrações com alto volume de requisições, entre em contato para discutir uma solução adequada.