API de Consulta de CEP 2.0

Guia Rápido

Todas as requisições na API devem ser realizadas em ambiente criptografado HTTPS através da URL https://api.webmania.com.br. O prefixo /2/ indica que estamos utilizando a versão 2.0 da API.

Todas as respostas são no formato objeto JSON.

Uma requisição bem-sucedida é indicada através do status HTTP. O status 2xx indica sucesso. Quando uma requisição falha, o corpo da resposta [body] continua no formato JSON, mas sempre contém o campo error. Por exemplo, caso sua autenticação não seja bem-sucedida, será retornada a seguinte mensagem:

{
  "error": "Token nao encontrado ou invalido."
}

Migração da API 1.0

Cronograma

Como migrar

• Altere a URL base para api.webmania.com.br
• Utilize /2/cep/{cep} ao invés de /1/cep/{cep}
• Autentique com o header X-Token (remova app_key e app_secret da query string)

Novo recurso: O endpoint de autocomplete permite busca por nome de rua e não estava disponível na API 1.0.

Módulos & Exemplos

Integre a API de CEP 2.0 da Webmania® na sua aplicação utilizando nossas SDKs oficiais ou teste os endpoints diretamente pelo Postman.

• Ferramentas
  • Coleção Postman (Testes instantâneos)
• SDK
  • CEP-SDK (PHP, Node.js, Python, C#, Java, Ruby)

Cada SDK inclui a classe wrapper da API, um endpoint proxy para integração segura com o front-end e exemplos de uso completos.

Módulos & Exemplos
Como utilizar

A API de CEP 2.0 deve ser acessada exclusivamente pelo back-end da sua aplicação. Nunca exponha o X-Token em código JavaScript no front-end do usuário.

1. Instale a SDK

Clone o repositório da SDK na linguagem do seu back-end:

git clone https://github.com/webmaniabr/CEP-SDK.git
cd CEP-SDK
# Acesse a pasta da linguagem desejada:
# php/ | nodejs/ | python/ | csharp/ | java/ | ruby/

2. Configure o token

Defina a variável de ambiente WEBMANIA_CEP_TOKEN com o seu token X-Token (UUID de 36 caracteres) obtido no painel da Webmania:

# Linux/macOS
export WEBMANIA_CEP_TOKEN="seu-token-uuid-aqui"

# Windows (PowerShell)
$env:WEBMANIA_CEP_TOKEN = "seu-token-uuid-aqui"

3. Consultar CEP

Exemplo em PHP:

// Instancie a SDK
$cep = new WebmaniaCep(getenv('WEBMANIA_CEP_TOKEN'));

// Consultar um CEP
$endereco = $cep->consultarCep('01310100');
echo $endereco['endereco']; // Avenida Paulista
echo $endereco['cidade'];    // Sao Paulo
echo $endereco['uf'];       // SP

Exemplo em Node.js:

const WebmaniaCep = require('./webmania-cep');
const cep = new WebmaniaCep(process.env.WEBMANIA_CEP_TOKEN);

const endereco = await cep.consultarCep('01310100');
console.log(endereco.endereco); // Avenida Paulista

4. Autocomplete de Endereço

O autocomplete permite buscar endereços por nome de rua, ideal para formulários com preenchimento automático:

// PHP — Buscar endereços com filtro
$resultados = $cep->autocomplete('Rua das Flores', [
    'uf'     => 'SP',
    'cidade' => 'São Paulo',
    'limit'  => 5
]);

foreach ($resultados['resultados'] as $item) {
    echo $item['endereco'] . ' — ' . $item['cep'];
}

5. Proxy para o Front-end

Cada SDK inclui um servidor proxy pronto para uso. O proxy recebe requisições do front-end e as repassa para a API da Webmania com o token seguro:

# PHP — Inicie o proxy
php -S localhost:8080 proxy.php

# Node.js — Inicie o proxy (também serve o front-end)
npm install && node server.js

# Python — Inicie o proxy
pip install -r requirements.txt && python server.py

Após iniciar o proxy, o front-end pode fazer requisições para:

6. Exemplo no Front-end

O exemplo HTML incluído na SDK (frontend/cep-autocomplete.html) demonstra um formulário completo com autocomplete e consulta de CEP. Basta iniciar qualquer um dos proxies e abrir o HTML no navegador.

Autenticação

A API 2.0 utiliza autenticação via header X-Token. O token é um UUID fornecido ao adquirir créditos para a API de CEP. Apenas clientes com créditos ativos podem utilizar a API 2.0.

Envie o token no cabeçalho HTTP de cada requisição:

curl -X GET \
-H "X-Token: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
https://api.webmania.com.br/2/cep/01310100

Mantenha o X-Token em segurança. Utilize somente em aplicações server-side (back-end). Nunca exponha o token em código JavaScript no front-end.

Consultar CEP

Para consultar os dados completos de um endereço a partir do CEP, envie a requisição no método GET para a URL /2/cep/{cep} informando o CEP com 8 dígitos no path da URL.

curl -X GET \
-H "X-Token: SEU_TOKEN" \
https://api.webmania.com.br/2/cep/01310100

Segue abaixo o exemplo de resposta para uma consulta bem-sucedida:

{
  "cep": "01310100",
  "endereco": "Avenida Paulista",
  "bairro": "Bela Vista",
  "cidade": "Sao Paulo",
  "uf": "SP",
  "ibge": "3550308"
}

Campos de resposta

Autocomplete

Para buscar endereços por nome de rua, envie a requisição no método GET para a URL /2/cep/autocomplete contendo os parâmetros de busca na query string.

curl -X GET \
-H "X-Token: SEU_TOKEN" \
"https://api.webmania.com.br/2/cep/autocomplete?q=Rua das Flores&uf=SP&limit=5"

Expansão de Abreviações

A API expande automaticamente abreviações comuns na busca:

Segue abaixo o exemplo de resposta para uma consulta bem-sucedida:

{
  "resultados": [
    {
      "cep": "09726310",
      "endereco": "Rua das Flores",
      "bairro": "Jardim do Mar",
      "cidade": "Sao Bernardo do Campo",
      "uf": "SP"
    }
  ],
  "total": 10,
  "creditos_consumidos": 0.005
}

Nota: O endpoint de autocomplete não retorna o campo ibge. Caso precise do código IBGE, utilize o CEP retornado para consultar o endpoint /2/cep/{cep}.

Limites de Uso

A API de CEP 2.0 possui limites de requisições por segundo para garantir a estabilidade do serviço. Requisições que excedem o limite recebem o status 429 Too Many Requests.

Consulta de CEP

Autocomplete

Créditos

Cada consulta à API de CEP 2.0 consome créditos da sua conta. Somente clientes com créditos ativos podem utilizar a API.

Consultas repetidas (mesmo CEP ou mesma busca) dentro da janela de deduplicação de 24 horas não consomem créditos adicionais.

Erros

Quando uma requisição falha, a resposta contém o campo error no formato JSON. Abaixo a lista completa de erros possíveis:

Estratégia de retry

Para erros 429 e 503, utilize retry com backoff exponencial: aguarde 1 segundo após a primeira falha, 2 segundos após a segunda, e assim por diante até o máximo de 3 tentativas.

Infraestrutura

O servidores da Webmania estão localizados na Amazon AWS, líder global em cloud computing, na região us-east-1 (Leste dos EUA) com ponto de presença em sa-east-1 (São Paulo). Manter a sua estrutura perto de algumas das duas localidades, garante um menor tempo de resposta nas requisições na API.

Utilizamos uma infraestrutura na Amazon AWS anycast de alta disponibilidade, o que significa que ao se comunicar com API da Webmania a requisição será redirecionada para o servidor mais próximo da sua localidade. As requisições dos endpoints são gerenciados através de IPs estáticos, caso necessite autorize no firewall a comunicação com os IPs abaixo.

• 13.248.145.90
• 76.223.17.240

• 34.196.69.38
• 44.219.142.86

Limite de requisições

A Webmania® aplica um limite de solicitações por segundo e total requisições por mês de acordo com o plano escolhido, calculado com a soma das solicitações do lado do cliente e do lado do servidor. Se o aplicativo exceder o limite inicial, apresentará falhas.

• Localização do servidor: O firewall bloqueia por padrão o IP de servidores em regiões com alto índice de ataques. Caso a sua comunicação via GET no endpoint https://webmania.com.br/api/ retorne 403 Erro Forbidden entre em contato para liberarmos o IP do seu servidor.
• Credenciais de acesso: Os endpoints exigem as credenciais de acesso válida e correta na URI da requisição, o envio incorreto é atribuído como uso indevido da API.