Como Integrar uma API de CEP em 5 Minutos (Tutorial Passo a Passo)

Se você trabalha com desenvolvimento web no Brasil, uma das tarefas mais comuns — e potencialmente mais chatas — é lidar com validação e preenchimento de endereços. Quantas vezes você já viu um formulário de cadastro com campos intermináveis de endereço que o usuário precisa preencher manualmente?

Eu já perdi a conta de quantos projetos vi com problemas de entrega porque o cliente digitou "Rua" em vez de "R." ou esqueceu o número do complemento. E pior: quando você percebe, já são 20 pedidos com endereço errado e você tem que correr atrás do prejuízo.

É aí que a API de CEP entra como uma verdadeira mão na roda. Com uma integração simples, você autocompleta rua, bairro, cidade e estado em frações de segundo. O resultado? Menos atrito no checkout, menos erros de entrega e clientes mais felizes.

Neste tutorial, vou te mostrar como integrar a API de CEP da APIBrasil.pro em 5 minutos. Vamos do zero até a primeira requisição funcionando.

O que você vai precisar

• Uma conta gratuita na APIBrasil.pro
• Uma API Key (vamos gerar juntos)
• Um editor de código (VS Code, Sublime, ou até mesmo o Bloco de Notas)
• Conexão com a internet (óbvio, mas é bom avisar)

Passo 1: Criando sua conta na APIBrasil.pro

O primeiro passo é acessar o site da APIBrasil.pro e criar uma conta. O processo é rápido e não exige cartão de crédito para começar.

1. Acesse apibrasil.pro
2. Clique em "Entrar" no canto superior direito
3. Selecione "Criar conta"
4. Preencha seu nome, e-mail e uma senha
5. Confirme seu e-mail (você receberá um link)

Pronto! Em menos de 2 minutos você já tem acesso ao dashboard.

Passo 2: Obtendo sua API Key

Com a conta criada, vamos gerar sua chave de acesso:

1. No dashboard, clique em "Minhas Chaves" no menu lateral
2. Clique em "Gerar nova chave"
3. Dê um nome para identificar (ex: "API CEP - Produção")
4. Copie a chave gerada

⚠️ Atenção: Guarde essa chave em um lugar seguro. Ela funciona como uma senha e dá acesso às APIs. Nunca exponha ela em repositórios públicos ou no frontend do seu app.

Passo 3: Entendendo o Endpoint

A API de CEP da APIBrasil.pro é bem direta:

GET https://api.apibrasil.pro/cep/{CEP}

Onde {CEP} é o código postal que você quer consultar (apenas números, sem hífen).

Exemplo de resposta JSON:

{
    "success": true,
    "data": {
        "cep": "01001000",
        "logradouro": "Praça da Sé",
        "bairro": "Sé",
        "cidade": "São Paulo",
        "estado": "SP",
        "ibge": "3550308"
    }
}

Passo 4: Mão no código!

Agora a parte divertida. Vou mostrar exemplos em 4 linguagens diferentes. Escolha a que você usa no dia a dia.

Exemplo em PHP (com cURL)

<?php
function consultarCep($cep) {
    $apiKey = getenv("APIBRASIL_API_KEY");
    $url = "https://api.apibrasil.pro/cep/$cep";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer $apiKey"));
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

$resultado = consultarCep("01001000");
if ($resultado["success"]) {
    $dados = $resultado["data"];
    echo "CEP: " . $dados["cep"] . "
";
    echo "Logradouro: " . $dados["logradouro"] . "
";
    echo "Cidade: " . $dados["cidade"] . " - " . $dados["estado"] . "
";
}
?>

Exemplo em JavaScript (com fetch)

const API_KEY = process.env.APIBRASIL_API_KEY;
const BASE_URL = "https://api.apibrasil.pro";

async function consultarCep(cep) {
    const response = await fetch(`${BASE_URL}/cep/${cep}`, {
        headers: { "Authorization": `Bearer ${API_KEY}` }
    });
    return await response.json();
}

consultarCep("01001000").then(data => {
    if (data.success) {
        console.log("CEP:", data.data.cep);
        console.log("Logradouro:", data.data.logradouro);
        console.log("Cidade:", data.data.cidade);
    }
});

Exemplo com cURL (linha de comando)

curl -X GET "https://api.apibrasil.pro/cep/01001000" -H "Authorization: Bearer SUA_API_KEY"

Exemplo em Python

import os, requests
API_KEY = os.environ.get("APIBRASIL_API_KEY")
url = "https://api.apibrasil.pro/cep/01001000"
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.get(url, headers=headers)
data = response.json()
if data.get("success"):
    d = data.get("data")
    print("CEP:", d.get("cep"))
    print("Logradouro:", d.get("logradouro"))
    print("Cidade:", d.get("cidade"))

Tratamento de erros

Uma coisa que aprendi na prática: sempre trate os erros. Seu usuário não merece ver uma tela branca ou um erro 500.

Boas práticas

1. Use variáveis de ambiente

Nunca coloque sua API Key diretamente no código.

# .env
APIBRASIL_API_KEY=sk_live_sua_chave

2. Cache os resultados

CEPs não mudam com frequência. Guarde em cache.

3. Valide o CEP antes de chamar a API

function validarCep($cep) {
    return preg_match("/^[0-9]{8}$/", $cep);
}

4. Tenha um fallback

Se a API falhar, permita que o usuário preencha manualmente.

Próximos passos

Na APIBrasil.pro você encontra também a API de CNPJ, API de CPF e API de Cotações.

Veja nossos planos de créditos e comece a integrar hoje mesmo!