Voltar para o Blog
TutorialJavaScriptAPI

Como Integrar a API de CEP em Seu Projeto JavaScript

8 min de leitura
Desenvolvedor integrando API

Neste tutorial completo, você aprenderá como integrar a API de CEP da API Brasil Fácil em seu projeto JavaScript, desde a configuração inicial até a implementação de funcionalidades avançadas.

Por Que Usar uma API de CEP?

Preencher formulários de endereço manualmente é tedioso e propenso a erros. Com uma API de CEP, você pode automatizar esse processo, melhorando significativamente a experiência do usuário e a qualidade dos dados coletados.

A API Brasil oferece consultas de CEP 100% gratuitas, sem limites de requisições, tornando-a ideal para projetos de qualquer tamanho.

Passo 1: Criar Sua Conta

Primeiro, você precisa criar uma conta gratuita na API Brasil para obter sua chave de API:

  1. Acesse o site da API Brasil
  2. Clique em "Começar Grátis"
  3. Preencha o formulário de cadastro
  4. Confirme seu email
  5. Acesse o dashboard e copie sua chave API

💡 Dica: Guarde sua chave API em um local seguro. Você precisará dela para todas as requisições.

Passo 2: Fazer Sua Primeira Requisição

Vamos começar com um exemplo simples usando JavaScript puro com fetch:

async function buscarCep(cep) {
  try {
    const response = await fetch(`https://api.apibrasil.com/v1/cep/${cep}`, {
      headers: {
        'Authorization': 'Bearer SUA_CHAVE_API'
      }
    });
    
    if (!response.ok) {
      throw new Error('CEP não encontrado');
    }
    
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Erro ao buscar CEP:', error);
    return null;
  }
}

// Exemplo de uso
const endereco = await buscarCep('01310100');
console.log(endereco);

Passo 3: Criar um Formulário Inteligente

Agora vamos criar um formulário HTML que preenche automaticamente os campos de endereço quando o usuário digita o CEP:

<form id="form-endereco">
  <input 
    type="text" 
    id="cep" 
    placeholder="Digite o CEP"
    maxlength="9"
  />
  <input type="text" id="logradouro" placeholder="Rua" readonly />
  <input type="text" id="bairro" placeholder="Bairro" readonly />
  <input type="text" id="cidade" placeholder="Cidade" readonly />
  <input type="text" id="estado" placeholder="Estado" readonly />
  <button type="submit">Salvar</button>
</form>

<script>
const cepInput = document.getElementById('cep');

cepInput.addEventListener('blur', async (e) => {
  const cep = e.target.value.replace(/\D/g, '');
  
  if (cep.length === 8) {
    const endereco = await buscarCep(cep);
    
    if (endereco) {
      document.getElementById('logradouro').value = endereco.logradouro;
      document.getElementById('bairro').value = endereco.bairro;
      document.getElementById('cidade').value = endereco.localidade;
      document.getElementById('estado').value = endereco.uf;
    }
  }
});
</script>

Passo 4: Adicionar Validação e Feedback

Para uma melhor experiência do usuário, vamos adicionar validação de CEP e feedback visual:

function validarCep(cep) {
  const cepLimpo = cep.replace(/\D/g, '');
  return cepLimpo.length === 8;
}

function mostrarLoading() {
  cepInput.classList.add('loading');
  cepInput.disabled = true;
}

function esconderLoading() {
  cepInput.classList.remove('loading');
  cepInput.disabled = false;
}

function mostrarErro(mensagem) {
  const erro = document.createElement('span');
  erro.className = 'erro';
  erro.textContent = mensagem;
  cepInput.parentElement.appendChild(erro);
}

cepInput.addEventListener('blur', async (e) => {
  const cep = e.target.value;
  
  // Limpar erros anteriores
  document.querySelectorAll('.erro').forEach(el => el.remove());
  
  if (!validarCep(cep)) {
    mostrarErro('CEP inválido');
    return;
  }
  
  mostrarLoading();
  
  const endereco = await buscarCep(cep.replace(/\D/g, ''));
  
  esconderLoading();
  
  if (!endereco) {
    mostrarErro('CEP não encontrado');
    return;
  }
  
  // Preencher campos...
});

Passo 5: Implementar Cache Local

Para melhorar a performance e reduzir requisições desnecessárias, vamos implementar um sistema de cache usando localStorage:

const CACHE_KEY = 'cep_cache';
const CACHE_DURATION = 24 * 60 * 60 * 1000; // 24 horas

function salvarCache(cep, dados) {
  const cache = JSON.parse(localStorage.getItem(CACHE_KEY) || '{}');
  cache[cep] = {
    dados,
    timestamp: Date.now()
  };
  localStorage.setItem(CACHE_KEY, JSON.stringify(cache));
}

function buscarCache(cep) {
  const cache = JSON.parse(localStorage.getItem(CACHE_KEY) || '{}');
  const item = cache[cep];
  
  if (!item) return null;
  
  // Verificar se o cache expirou
  if (Date.now() - item.timestamp > CACHE_DURATION) {
    return null;
  }
  
  return item.dados;
}

async function buscarCepComCache(cep) {
  // Tentar buscar do cache primeiro
  const cached = buscarCache(cep);
  if (cached) {
    console.log('Usando cache para CEP:', cep);
    return cached;
  }
  
  // Se não estiver no cache, buscar da API
  const dados = await buscarCep(cep);
  if (dados) {
    salvarCache(cep, dados);
  }
  
  return dados;
}

Bônus: Integração com React

Se você está usando React, aqui está um hook personalizado para facilitar a integração:

import { useState, useEffect } from 'react';

function useCep(cep) {
  const [endereco, setEndereco] = useState(null);
  const [loading, setLoading] = useState(false);
  const [erro, setErro] = useState(null);

  useEffect(() => {
    if (!cep || cep.length !== 8) {
      setEndereco(null);
      return;
    }

    const buscar = async () => {
      setLoading(true);
      setErro(null);

      try {
        const response = await fetch(`https://api.apibrasil.com/v1/cep/${cep}`, {
          headers: {
            'Authorization': 'Bearer SUA_CHAVE_API'
          }
        });

        if (!response.ok) {
          throw new Error('CEP não encontrado');
        }

        const data = await response.json();
        setEndereco(data);
      } catch (err) {
        setErro(err.message);
      } finally {
        setLoading(false);
      }
    };

    buscar();
  }, [cep]);

  return { endereco, loading, erro };
}

// Uso no componente
function FormularioEndereco() {
  const [cep, setCep] = useState('');
  const { endereco, loading, erro } = useCep(cep);

  return (
    <div>
      <input
        value={cep}
        onChange={(e) => setCep(e.target.value.replace(/\D/g, ''))}
        placeholder="Digite o CEP"
        maxLength={8}
      />
      {loading && <p>Buscando...</p>}
      {erro && <p className="erro">{erro}</p>}
      {endereco && (
        <div>
          <input value={endereco.logradouro} readOnly />
          <input value={endereco.bairro} readOnly />
          <input value={endereco.localidade} readOnly />
        </div>
      )}
    </div>
  );
}

Conclusão

Integrar a API de CEP da API Brasil é simples e traz benefícios significativos para seus projetos. Com as técnicas apresentadas neste tutorial, você pode criar formulários inteligentes que melhoram drasticamente a experiência do usuário.

Lembre-se de sempre tratar erros adequadamente, implementar cache quando possível e fornecer feedback visual claro para os usuários. Boas práticas como essas fazem toda a diferença na qualidade final da sua aplicação.

Pronto para começar?

Crie sua conta gratuita agora e ganhe R$ 5,00 de crédito para testar todas as nossas APIs.

Criar Conta Grátis