Como usar APIs de CEP no seu site ou aplicativo

Se você já comprou algo online e o endereço foi preenchido automaticamente ao digitar o CEP, saiba que por trás dessa mágica existe uma API trabalhando em tempo real. As APIs de CEP são serviços que permitem consultar dados de endereçamento de forma programática, retornando informações como rua, bairro, cidade e estado a partir de um código de oito dígitos.

Neste artigo, vamos explicar o que é uma API de CEP, por que usá-la, quais são as opções gratuitas disponíveis no Brasil e como integrá-las no seu site ou aplicativo. O guia é acessível para quem está começando, mas também inclui detalhes técnicos úteis para desenvolvedores experientes.

O que é uma API de CEP?

API é a sigla para Application Programming Interface (Interface de Programação de Aplicações). No contexto de CEP, uma API é um serviço online que recebe um CEP como entrada e retorna os dados do endereço correspondente em formato estruturado, como JSON ou XML. Isso permite que sites e aplicativos consultem endereços automaticamente, sem que o usuário precise digitá-los manualmente.

O funcionamento é simples: seu sistema faz uma requisição HTTP para a URL da API passando o CEP, e a API responde com os dados. Por exemplo, ao consultar o CEP 01001-000, a API retorna que se trata da Praça da Sé, bairro Sé, em São Paulo/SP.

Na prática, o fluxo funciona assim:

Por que usar uma API de CEP?

Para quem mantém um site com formulários de endereço (e-commerce, cadastro, delivery), as vantagens de integrar uma API de CEP são enormes:

• Reduz erros de digitação: Quando o endereço é preenchido automaticamente, o usuário erra muito menos. Bairros com nomes longos, ruas com grafia complexa e cidades com acentos deixam de ser problema.
• Agiliza o checkout: Em lojas virtuais, cada segundo a mais no processo de compra aumenta a taxa de abandono de carrinho. Autocompletar o endereço a partir do CEP economiza tempo e cliques.
• Valida endereços em tempo real: Se o CEP não existe, a API retorna um erro. Isso permite alertar o usuário na hora, evitando pedidos com endereço inválido que seriam devolvidos.
• Calcula frete com precisão: APIs de CEP podem ser combinadas com APIs de frete para calcular automaticamente o custo e prazo de entrega. Para entender essa relação, veja nosso artigo sobre como o CEP influencia o frete.

As 3 principais APIs gratuitas de CEP

1. ViaCEP

O ViaCEP é a API de CEP mais popular do Brasil. Lançada em 2014, é gratuita, não requer cadastro e não tem limite de requisições documentado. Retorna dados em JSON, XML, JSONP e Piped.

URL de consulta:

// Consulta por CEP (retorna JSON)
https://viacep.com.br/ws/01001000/json/

// Resposta:
{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "unidade": "",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "estado": "São Paulo",
  "ibge": "3550308",
  "gia": "1004",
  "ddd": "11",
  "siafi": "7107"
}

Além da consulta por CEP, o ViaCEP oferece busca por endereço: passando UF, cidade e logradouro, retorna os CEPs correspondentes. Isso é útil para implementar busca reversa no seu formulário.

2. BrasilAPI

O BrasilAPI é um projeto open source mantido pela comunidade que agrega diversas APIs úteis para desenvolvedores brasileiros: CEP, CNPJ, bancos, feriados, taxas e mais. A API de CEP consulta múltiplas fontes como fallback, o que aumenta a confiabilidade.

// Consulta por CEP (retorna JSON)
https://brasilapi.com.br/api/cep/v2/01001000

// Resposta:
{
  "cep": "01001000",
  "state": "SP",
  "city": "São Paulo",
  "neighborhood": "Sé",
  "street": "Praça da Sé",
  "service": "correios",
  "location": {
    "type": "Point",
    "coordinates": { ... }
  }
}

Um diferencial do BrasilAPI é retornar coordenadas geográficas (latitude/longitude) para muitos CEPs, o que é útil para aplicações que precisam de geolocalização.

3. OpenCEP

O OpenCEP é uma alternativa mais enxuta, focada em velocidade e simplicidade. Mantida pela comunidade open source, é totalmente gratuita e sem limites.

// Consulta por CEP (retorna JSON)
https://opencep.com/v1/01001000

// Resposta similar ao ViaCEP:
{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "ibge": "3550308"
}

Comparação das APIs

Exemplo prático de integração

Aqui está um exemplo simples de como consultar um CEP usando JavaScript puro no navegador. Esse código pode ser usado em qualquer site HTML:

async function buscarCEP(cep) {
  // Remove caracteres não numéricos
  const cepLimpo = cep.replace(/\D/g, '');

  if (cepLimpo.length !== 8) {
    alert('CEP deve ter 8 dígitos');
    return;
  }

  try {
    const resposta = await fetch(
      `https://viacep.com.br/ws/${cepLimpo}/json/`
    );
    const dados = await resposta.json();

    if (dados.erro) {
      alert('CEP não encontrado');
      return;
    }

    // Preenche os campos do formulário
    document.getElementById('rua').value = dados.logradouro;
    document.getElementById('bairro').value = dados.bairro;
    document.getElementById('cidade').value = dados.localidade;
    document.getElementById('estado').value = dados.uf;

  } catch (erro) {
    console.error('Erro na consulta:', erro);
    alert('Erro ao buscar CEP. Tente novamente.');
  }
}

Boas práticas de integração

Ao integrar uma API de CEP no seu projeto, considere estas recomendações que vão melhorar a confiabilidade e a experiência do usuário:

Estratégia de fallback

Uma das práticas mais importantes é implementar um sistema de fallback: se a API principal não responder, seu código tenta automaticamente uma segunda API. Isso garante que o formulário continue funcionando mesmo quando uma das APIs estiver fora do ar. Aqui está a lógica simplificada:

async function buscarCEPComFallback(cep) {
  const apis = [
    `https://viacep.com.br/ws/${cep}/json/`,
    `https://brasilapi.com.br/api/cep/v2/${cep}`,
    `https://opencep.com/v1/${cep}`,
  ];

  for (const url of apis) {
    try {
      const resp = await fetch(url, { signal: AbortSignal.timeout(3000) });
      if (resp.ok) {
        const dados = await resp.json();
        if (!dados.erro) return dados;
      }
    } catch {
      // API falhou, tenta a próxima
      continue;
    }
  }

  return null; // Todas as APIs falharam
}

Quando pagar por uma API de CEP?

As APIs gratuitas atendem perfeitamente a maioria dos casos de uso. Porém, existem cenários em que uma API paga pode fazer sentido:

• Volume muito alto: Se seu site faz centenas de milhares de consultas por dia, uma API paga com SLA (garantia de disponibilidade) oferece mais estabilidade.
• Dados enriquecidos: Algumas APIs pagas retornam informações extras como coordenadas GPS precisas, código IBGE, fuso horário e região administrativa.
• Suporte técnico: APIs pagas geralmente incluem suporte dedicado para resolver problemas de integração.
• Compliance: Empresas que precisam de garantias contratuais sobre disponibilidade e atualização dos dados podem preferir a licença direta do e-DNE dos Correios.

Para a grande maioria dos sites e aplicativos brasileiros, as três APIs gratuitas apresentadas neste artigo, combinadas com uma boa estratégia de fallback, são mais do que suficientes.

Conclusão

Integrar uma API de CEP é uma das formas mais simples e eficazes de melhorar a experiência do usuário no seu site ou aplicativo. Com ViaCEP, BrasilAPI e OpenCEP, você tem três opções gratuitas e confiáveis à disposição, cada uma com suas particularidades. O mais importante é implementar uma boa estratégia de fallback, validar os dados antes da requisição e permitir que o usuário corrija o endereço quando necessário.

Se você quer entender melhor como o sistema de CEPs funciona por trás dessas APIs, recomendamos nosso artigo sobre o que é CEP e como funciona. E se está enfrentando problemas com CEPs que não são encontrados, confira nosso guia sobre o que fazer quando o CEP não funciona.