Desenvolvedor de Software e Especialista em Tecnologia da Informação

Problemas com CEP? Aprenda a construir uma API PHP segura! 🚀

Você já precisou consultar um CEP automaticamente em um sistema PHP? Neste artigo, vamos explorar como consumir a API pública do ViaCEP utilizando PHP + cURL, recebendo um JSON com todas as informações do endereço e tratando a resposta de forma simples e segura. Uma habilidade essencial para qualquer desenvolvedor backend que trabalha com integrações de API.

📅  24 de junho de 2026
⏱️  10 min
🏷️  PHP
📚 artigos +

Como consumir a API ViaCEP com PHP e cURL: Guia completo para consulta de CEP

Você já precisou consultar um CEP automaticamente em um sistema PHP? Neste Short eu mostro como consumir a API pública do ViaCEP utilizando PHP + cURL, recebendo um JSON com todas as informações do endereço e tratando a resposta de forma simples e segura. O exemplo utiliza o CEP 01001-000, correspondente à Catedral da Sé, localizada na Praça da Sé, centro de São Paulo. A partir desse único dado é possível recuperar logradouro, bairro, cidade, estado, DDD, código IBGE e diversas outras informações úteis para aplicações reais.

PHP API ViaCEP cURL PHP Backend API REST JSON Desenvolvimento Web Integração API Programação PHP cURL PHP RogerioPontesTI

"A integração com APIs é a espinha dorsal do desenvolvimento web moderno. Saber consumir serviços externos de forma eficiente e segura é o que separa um desenvolvedor funcional de um desenvolvedor profissional."

O que é a API ViaCEP?

O ViaCEP é uma API pública gratuita que permite consultar informações de endereço a partir de um CEP brasileiro. Ela retorna dados como logradouro, bairro, cidade, estado, DDD, código IBGE e muito mais.

Este serviço é amplamente utilizado em sistemas de cadastro, e-commerces, ERPs, CRMs e aplicações corporativas. Em vez de obrigar o usuário a preencher todo o endereço manualmente, basta informar o CEP para que os demais campos sejam preenchidos automaticamente.

💡 Dica: O ViaCEP é gratuito e não requer autenticação, sendo perfeito para testes e projetos de pequeno a médio porte.

Por que usar cURL no PHP?

O cURL é uma biblioteca que permite fazer requisições HTTP de forma rápida e segura. No PHP, é a ferramenta padrão para consumir APIs e serviços externos.

Principais vantagens do cURL:

  • Flexibilidade: Suporta diversos protocolos (HTTP, HTTPS, FTP, etc.)
  • Segurança: Permite configurar SSL/TLS, headers e autenticação
  • Performance: Requisições rápidas e eficientes
  • Controle: Configurações detalhadas de timeout, redirecionamento, etc.

Estrutura da API ViaCEP

A API ViaCEP possui uma URL simples e intuitiva:

URL DA API 

// URL base
https://viacep.com.br/ws/{cep}/json/

// Exemplo com CEP 01001-000
https://viacep.com.br/ws/01001000/json/

O retorno da API é um JSON com os seguintes campos:

RESPOSTA JSON 

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

Implementando a consulta em PHP

Vamos construir uma classe PHP completa para consumir a API ViaCEP:

CLASSE PHP COMPLETA 

<?php

class Cep {

    private $url = "https://viacep.com.br/ws/{cep}/json/";
    private $resposta = null;
    private $ch = null;

    public function __construct($cep = null){
        if($cep !== null){
            $this->url = str_replace("{cep}", $cep, $this->url);
            $this->consulta();
            $this->toString();
        }
    }

    private function consulta(){
        $this->ch = curl_init($this->url);
        curl_setopt($this->ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($this->ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($this->ch, CURLOPT_FOLLOWLOCATION, true);
        curl_setopt($this->ch, CURLOPT_USERAGENT, 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)');
        curl_setopt($this->ch, CURLOPT_HTTPHEADER, [
            'Accept: application/json',
            'Content-Type: application/json'
        ]);
        $this->resposta = curl_exec($this->ch);
    }

    private function toString(){
        $dados = json_decode($this->resposta, true);

        if(is_array($dados) && isset($dados["localidade"])){
            print_r($dados);
        } else {
            echo "Não foi possível localizar o CEP." . PHP_EOL;
        }
    }

    public function __destruct(){
        if($this->ch){
            curl_close($this->ch);
        }
    }
}

// Executando a consulta
new Cep("01001000");

Exemplo de saída

Ao executar o código com o CEP 01001-000 (Catedral da Sé em São Paulo), obtemos:

SAÍDA DO PHP 

Array
(
    [cep] => 01001-000
    [logradouro] => Praça da Sé
    [complemento] => lado ímpar
    [unidade] => 
    [bairro] => Sé
    [localidade] => São Paulo
    [uf] => SP
    [estado] => São Paulo
    [regiao] => Sudeste
    [ibge] => 3550308
    [gia] => 1004
    [ddd] => 11
    [siafi] => 7107
)

O CEP 01001-000 corresponde à Catedral da Sé, localizada na Praça da Sé, no bairro da Sé, no centro da cidade de São Paulo, SP.

Explicando o código passo a passo

1. Propriedades da classe

PROPRIEDADES 

private $url = "https://viacep.com.br/ws/{cep}/json/";
private $resposta = null;
private $ch = null;
  • $url: URL base da API com placeholder {cep}
  • $resposta: Armazena a resposta da API
  • $ch: Handle da conexão cURL

2. Construtor

CONSTRUTOR 

public function __construct($cep = null){
    if($cep !== null){
        $this->url = str_replace("{cep}", $cep, $this->url);
        $this->consulta();
        $this->toString();
    }
}
  • Recebe o CEP como parâmetro opcional
  • Substitui o placeholder na URL
  • Chama os métodos consulta() e toString()

3. Método consulta()

CONSULTA 

private function consulta(){
    $this->ch = curl_init($this->url);
    curl_setopt($this->ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($this->ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($this->ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($this->ch, CURLOPT_USERAGENT, 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)');
    curl_setopt($this->ch, CURLOPT_HTTPHEADER, [
        'Accept: application/json',
        'Content-Type: application/json'
    ]);
    $this->resposta = curl_exec($this->ch);
}

As opções do cURL configuradas:

  • CURLOPT_RETURNTRANSFER: Retorna a resposta como string
  • CURLOPT_SSL_VERIFYPEER: Desabilita verificação SSL (para ambientes sem certificado)
  • CURLOPT_FOLLOWLOCATION: Segue redirecionamentos
  • CURLOPT_USERAGENT: Define um User-Agent válido
  • CURLOPT_HTTPHEADER: Define headers da requisição

4. Método toString()

TRATAMENTO DA RESPOSTA 

private function toString(){
    $dados = json_decode($this->resposta, true);

    if(is_array($dados) && isset($dados["localidade"])){
        print_r($dados);
    } else {
        echo "Não foi possível localizar o CEP." . PHP_EOL;
    }
}
  • json_decode(): Converte a resposta JSON para array
  • Validação: Verifica se o campo localidade existe
  • Tratamento de erro: Exibe mensagem se o CEP não for encontrado

5. Destrutor

DESTRUTOR 

public function __destruct(){
    if($this->ch){
        curl_close($this->ch);
    }
}
  • __destruct(): Fecha a conexão cURL automaticamente
  • Boa prática: Libera recursos ao final do script

Melhorias e boas práticas

Podemos melhorar a classe com algumas funcionalidades adicionais:

VERSÃO MELHORADA 

<?php

class Cep {

    private $url = "https://viacep.com.br/ws/{cep}/json/";
    private $dados = null;
    private $erro = null;

    public function __construct($cep) {
        $this->consultar($cep);
    }

    public function consultar($cep) {
        $cep = preg_replace('/\D/', '', $cep);
        $url = str_replace("{cep}", $cep, $this->url);

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
        curl_setopt($ch, CURLOPT_TIMEOUT, 10);

        $resposta = curl_exec($ch);

        if (curl_errno($ch)) {
            $this->erro = "Erro na requisição: " . curl_error($ch);
            curl_close($ch);
            return false;
        }

        curl_close($ch);
        $this->dados = json_decode($resposta, true);

        if (isset($this->dados['erro'])) {
            $this->erro = "CEP não encontrado";
            $this->dados = null;
            return false;
        }

        return true;
    }

    public function getDados() {
        return $this->dados;
    }

    public function getErro() {
        return $this->erro;
    }

    public function getEnderecoCompleto() {
        if (!$this->dados) return null;
        return $this->dados['logradouro'] . ', ' .
               $this->dados['bairro'] . ', ' .
               $this->dados['localidade'] . ' - ' .
               $this->dados['uf'];
    }
}

// Usando a classe melhorada
$cep = new Cep("01001000");

if ($cep->getDados()) {
    print_r($cep->getDados());
    echo "\nEndereço completo: " . $cep->getEnderecoCompleto() . PHP_EOL;
} else {
    echo "Erro: " . $cep->getErro() . PHP_EOL;
}

Conclusão

Consumir APIs externas é uma habilidade essencial para qualquer desenvolvedor backend. O ViaCEP é um exemplo perfeito de como integrar serviços de terceiros de forma simples e eficiente.

Neste artigo, você aprendeu:

  • ✅ O que é a API ViaCEP e como ela funciona
  • ✅ Como usar cURL no PHP para fazer requisições HTTP
  • ✅ Como tratar respostas JSON de forma segura
  • ✅ Como organizar o código em classes reutilizáveis
  • ✅ Boas práticas para consumo de APIs

💡 Lembre-se: A integração com APIs é a espinha dorsal do desenvolvimento web moderno. Dominar ferramentas como cURL e saber consumir serviços REST é fundamental para qualquer desenvolvedor que deseje construir aplicações completas e profissionais.

🤔 O que você achou?

💬 Quer aprender JavaScript do ZERO? Comece agora a escrever seu primeiro código e seus fundamentos!

❓ FAQ: Perguntas Frequentes sobre API ViaCEP e PHP

O ViaCEP é uma API pública gratuita que retorna informações de endereço a partir de um CEP brasileiro. Ela fornece dados como logradouro, bairro, cidade, estado, DDD e código IBGE.

Sim. A consulta é pública e gratuita, sem necessidade de cadastro ou autenticação. É ideal para projetos de pequeno a médio porte e para testes.

O cURL permite consumir APIs HTTP de forma rápida, segura e profissional. Ele oferece controle sobre headers, SSL, timeout, redirecionamentos e é a ferramenta padrão para integrações em PHP.

Sim. O ViaCEP retorna dados em formato JSON, que pode ser facilmente interpretado pelo PHP usando a função json_decode().

Sim, desde que a extensão cURL esteja habilitada no PHP. A maioria dos servidores compartilhados e dedicados já possui essa extensão ativada por padrão.

Sim. A lógica pode ser reutilizada em sistemas de cadastro, e-commerces e aplicações corporativas. É uma base sólida que pode ser expandida com validações e tratamentos adicionais.

O ViaCEP permite consulta em lote usando o formato https://viacep.com.br/ws/{cep1}/{cep2}/json/, mas é recomendado fazer consultas individuais para melhor controle e tratamento de erros.

O ViaCEP é gratuito e não requer autenticação, enquanto outras APIs podem ter limites de requisições ou exigir chave de acesso. Para projetos simples, o ViaCEP é a melhor opção.

🎬 Assista ao Vídeos completo sobre Refatoração

O vídeo foi feito em Javascript mais o conceito pode ser utilizado em qualquer outra linguagem de programação..

🔗 Conecte-se Comigo

YouTube Site LinkedIn GitHub Instagram

💬 Você já utilizou o ViaCEP em algum projeto? Ou prefere outra API para consulta de endereços? Escreva nos comentários qual integração você gostaria de ver em um próximo artigo! 👇

#PHP #API #ViaCEP #Backend #Programacao #DesenvolvimentoWeb #ProgramacaoPHP #BackendDeveloper #APIREST #JSON #cURL #LogicaDeProgramacao #RogerioPontesTI