# CEP / IBGE

Source: https://webmania.com.br/docs/rest-api-cep-ibge/
API: 2.0
Autenticação: X-Token
Versão da documentação v2.0.1 (2026-11-09)
Última atualização: A documentação agora é compatível com LLMs: cópia da página ou de cada seção em Markdown, índice por seção e llms.txt.

[Changelog](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=changelog)

This is the rendered official reference. HTTP success alone does not prove fiscal authorization. Check the response body and documented document status.

## Seções

Leia por partes: índice com o tamanho de cada seção em https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&indice=1; cada link abaixo retorna somente a seção.

- [Guia Rápido](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=guiarapido)
- [Guia Rápido › Consulta ou Autocomplete](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=cep-qual-endpoint)
- [Guia Rápido › Respostas de Erro](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=cep-respostas-erro)
- [Guia Rápido › Migração da API 1.0](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=migracao)
- [SDKs & LLMs](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=sdks-llms)
- [Compatível com LLM](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=compativel-com-llm)
- [SDKs Webmania](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=sdks)
- [Exemplos](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=exemplos)
- [SDKs & LLMs › Exemplos › Como utilizar](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=como-utilizar)
- [Autenticação](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=autenticacao)
- [Consultas › Consultar CEP](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=consultar-cep)
- [Consultas › Autocomplete](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=autocomplete)
- [Uso e Créditos › Limites de Uso](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=limites)
- [Uso e Créditos › Créditos](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=creditos)
- [Erros](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=erros)
- [Infraestrutura](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=infraestrutura)
- [Limite de requisições](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=limite-requisicoes)
- [Changelog](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=changelog)

⚡ Acompanhe em tempo real: [Status](https://status.webmaniabr.com) | [Monitor Sefaz](https://monitorsefaz.webmaniabr.com) | [Monitor Prefeituras](https://monitorprefeituras.webmaniabr.com)

# API de Consulta de CEP 2.0

A API de CEP 2.0 da Webmania oferece consulta de CEP com dados completos e um endpoint de autocomplete de endereços. Integre no seu back-end com autenticação segura via token e pague apenas pelos créditos consumidos. Para começar, consulte o [Guia Rápido](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=guiarapido).

**Migre para a API de CEP 2.0.** O bloqueio parcial da API de CEP 1.0 começou em **30/04/2026** (requisições sem `X-Token`). Desde **31/08/2026 23:59:59 (America/Sao_Paulo)**, os endpoints da API 1.0 retornam HTTP `410 Gone`. Novo endpoint canônico: `/2/cep/{cep}`. Veja a [Migração da API 1.0](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=migracao).

**O que é a API de CEP?** É a API que transforma um CEP em endereço completo, com o código IBGE do município, e que sugere endereços enquanto o usuário digita o nome da rua:

#### Consulta de CEP

Endereço, bairro, cidade, UF e código IBGE a partir do CEP com 8 dígitos, no `GET /2/cep/{cep}`.

#### Autocomplete de endereços

Busca por nome de rua com filtros por UF, cidade e bairro, no `GET /2/cep/autocomplete`.

#### Créditos

Cada consulta nova usa créditos. Repetições reconhecidas na janela de 24 horas não consomem créditos adicionais.

#### Somente no back-end

A autenticação é pelo cabeçalho `X-Token`. Proteja o token e nunca o exponha no front-end.

Quer integrar CEP/IBGE na sua aplicação? [Fale com um especialista](https://webmania.com.br/chat/)
Receba orientações e credenciais de acesso

## 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.

| URL | HTTP Verb | Função |
| --- | --- | --- |
| `/2/cep/{cep}` | GET | Consulta de CEP |
| `/2/cep/autocomplete` | GET | Busca por endereço |

Todas as respostas são no formato objeto JSON. Envie o cabeçalho `X-Token` com o seu token em todas as chamadas, sempre a partir do seu back-end; veja [Autenticação](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=autenticacao).

**Como integrar a API de CEP:**

1. [Obtenha o token](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=autenticacao) O token é um UUID fornecido ao adquirir créditos para a API de CEP. Guarde-o no seu servidor e envie-o no cabeçalho `X-Token`.
2. [Consulte o CEP](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=consultar-cep) GET para `/2/cep/{cep}`, com o CEP de 8 dígitos. A resposta traz endereço, bairro, cidade, UF e o código IBGE.
3. [Sugira endereços](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=autocomplete)se necessário Sem o CEP, GET para `/2/cep/autocomplete` com o texto em `q`, para o usuário escolher o endereço pelo nome da rua.
4. [Respeite os limites e os créditos](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=limites) Cada endpoint tem limite de requisições por segundo e um custo em créditos por consulta nova. Repetições reconhecidas em 24 horas não são cobradas de novo.
5. [Trate os erros](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=erros) Confira o status HTTP: `401` para o token, `402` para créditos, `429` para o limite por segundo, entre outros.

## Guia Rápido Consulta ou Autocomplete

Os dois endpoints se completam: o autocomplete encontra o CEP pelo nome da rua, e a consulta do CEP traz o código IBGE. Escolha pelo que o usuário já informou:

**Consulta de CEP ou autocomplete:** Se o usuário já informou o CEP, consulte o GET /2/cep/{cep}: a resposta traz endereço, bairro, cidade, UF e o código IBGE, que pode ser null em alguns CEPs; cada consulta nova usa 0.10 crédito. Sem o CEP, busque pelo nome da rua no GET /2/cep/autocomplete: cada resultado traz o CEP, sem o código IBGE, e cada busca nova usa 0.005 crédito. Se precisar do código IBGE, consulte o CEP do resultado escolhido no GET /2/cep/{cep}.

Endpoint da API Verificação Resultado na sua aplicação

 Repetições reconhecidas em até 24 horas não consomem créditos novamente. Veja [Créditos](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=creditos) e [Limites de Uso](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=limites).

## Guia Rápido Respostas de Erro

Uma requisição bem-sucedida é indicada pelo status HTTP `2xx`. Quando uma requisição falha, o corpo da resposta continua no formato JSON e sempre contém o campo `error`. Por exemplo, caso a autenticação não seja bem-sucedida, a API retorna HTTP `401` com o seguinte corpo:

```json
{
  "error": "Unauthorized",
  "message": "Acesso restrito."
}
```

A lista completa dos status, com o que fazer em cada um, está em [Erros](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=erros).

## Guia Rápido Migração da API 1.0

Quem ainda usa a API de CEP 1.0 precisa trocar a URL, o endpoint e a autenticação. O cronograma e os passos estão abaixo.

**API 1.0 descontinuada.** Desde **31/08/2026 23:59:59 (America/Sao_Paulo)**, os endpoints de CEP 1.0 retornam HTTP `410 Gone`. Utilize a API 2.0.

### Cronograma

| Data | Mudança |
| --- | --- |
| `01/04/2026` | Credenciais via query string (`app_key`, `app_secret`) bloqueadas |
| `30/04/2026` | `X-Token` obrigatório em todas as requisições |
| `31/08/2026` | Sunset completo da API 1.0 — todos os endpoints desativados |

### Como migrar

- Altere a URL base para `api.webmania.com.br`
- Utilize `/2/cep/{cep}` no lugar do endpoint legado `/api/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.

## SDKs & LLMs

Leve esta referência para o seu assistente de IA, integre a API com um SDK oficial ou comece pelos módulos e exemplos prontos.

### Compatível com LLM

Envie a uma IA o índice de seções desta referência: ela lê o índice e busca só as seções de que precisa, em Markdown.

- [**Índice por seção** Comece aqui Cada seção desta referência com sua URL e tamanho, para a IA ler só o necessário. Ver índice em Markdown](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&indice=1)
- [**Página em Markdown** A referência completa em texto puro, com as mesmas tabelas e exemplos. Ver como Markdown](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown)
- [**Abrir no ChatGPT** Lê o índice e busca só as seções necessárias. Abrir no ChatGPT](https://chatgpt.com/?hints=search&q=Leia%20o%20%C3%ADndice%20da%20documenta%C3%A7%C3%A3o%20da%20API%20Webmania%20em%20https%3A%2F%2Fwebmania.com.br%2Fdocs%2Frest-api-cep-ibge%2F%3Fformat%3Dmarkdown%26indice%3D1%20e%20busque%20somente%20as%20se%C3%A7%C3%B5es%20necess%C3%A1rias%2C%20pela%20URL%20de%20cada%20uma%20%28%3Fformat%3Dmarkdown%26secao%3D%3Cid%3E%29%2C%20para%20responder%20%C3%A0s%20minhas%20perguntas%20com%20base%20nelas.)
- [**Abrir no Claude** Lê o índice e busca só as seções necessárias. Abrir no Claude](https://claude.ai/new?q=Leia%20o%20%C3%ADndice%20da%20documenta%C3%A7%C3%A3o%20da%20API%20Webmania%20em%20https%3A%2F%2Fwebmania.com.br%2Fdocs%2Frest-api-cep-ibge%2F%3Fformat%3Dmarkdown%26indice%3D1%20e%20busque%20somente%20as%20se%C3%A7%C3%B5es%20necess%C3%A1rias%2C%20pela%20URL%20de%20cada%20uma%20%28%3Fformat%3Dmarkdown%26secao%3D%3Cid%3E%29%2C%20para%20responder%20%C3%A0s%20minhas%20perguntas%20com%20base%20nelas.)
- [**llms.txt** Ponto de partida para agentes, com todas as referências públicas. Abrir o llms.txt](https://webmania.com.br/docs/llms.txt)

### SDKs Webmania

SDKs oficiais de código aberto, disponíveis no GitHub, para integrar as APIs Webmania na linguagem do seu projeto. Cada repositório traz a instalação, exemplos e as operações cobertas.

- [Node.js / TypeScript](https://github.com/webmaniabr/webmania-node) Disponível

   Node.js >= 22 [README](https://github.com/webmaniabr/webmania-node#readme)

   `git clone https://github.com/webmaniabr/webmania-node.git`
- [Python](https://github.com/webmaniabr/webmania-python) Disponível

   Python >= 3.11 [README](https://github.com/webmaniabr/webmania-python#readme)

   `git clone https://github.com/webmaniabr/webmania-python.git`
- [PHP](https://github.com/webmaniabr/webmania-php) Disponível

   PHP >= 8.3 [README](https://github.com/webmaniabr/webmania-php#readme)

   `git clone https://github.com/webmaniabr/webmania-php.git`
- [Perl](https://github.com/webmaniabr/webmania-perl) Disponível

   Perl 5.36 [README](https://github.com/webmaniabr/webmania-perl#readme)

   `git clone https://github.com/webmaniabr/webmania-perl.git`
- [Go](https://github.com/webmaniabr/webmania-go) Disponível

   Go 1.26 [README](https://github.com/webmaniabr/webmania-go#readme)

   `git clone https://github.com/webmaniabr/webmania-go.git`
- [C](https://github.com/webmaniabr/webmania-c) Disponível

   C11, Linux arm64 [README](https://github.com/webmaniabr/webmania-c#readme)

   `git clone https://github.com/webmaniabr/webmania-c.git`
- [C++](https://github.com/webmaniabr/webmania-cpp) Disponível

   C++, Linux arm64 [README](https://github.com/webmaniabr/webmania-cpp#readme)

   `git clone https://github.com/webmaniabr/webmania-cpp.git`
- [Lua](https://github.com/webmaniabr/webmania-lua) Disponível

   Lua 5.4, Linux arm64 [README](https://github.com/webmaniabr/webmania-lua#readme)

   `git clone https://github.com/webmaniabr/webmania-lua.git`
- [Dart](https://github.com/webmaniabr/webmania-dart) Disponível

   Dart >= 3.8.3, Linux arm64 [README](https://github.com/webmaniabr/webmania-dart#readme)

   `git clone https://github.com/webmaniabr/webmania-dart.git`
- [R](https://github.com/webmaniabr/webmania-r) Disponível

   R >= 4.6.2, Linux arm64 [README](https://github.com/webmaniabr/webmania-r#readme)

   `git clone https://github.com/webmaniabr/webmania-r.git`
- [Java](https://github.com/webmaniabr/webmania-java) Disponível

   Java 17+ [README](https://github.com/webmaniabr/webmania-java#readme)

   `git clone https://github.com/webmaniabr/webmania-java.git`
- [Kotlin](https://github.com/webmaniabr/webmania-kotlin) Disponível

   Kotlin 2.4 / JVM 17+ [README](https://github.com/webmaniabr/webmania-kotlin#readme)

   `git clone https://github.com/webmaniabr/webmania-kotlin.git`
- [Scala](https://github.com/webmaniabr/webmania-scala) Disponível

   Scala 3.3 / JVM 17+ [README](https://github.com/webmaniabr/webmania-scala#readme)

   `git clone https://github.com/webmaniabr/webmania-scala.git`
- [Clojure](https://github.com/webmaniabr/webmania-clojure) Disponível

   Clojure 1.12 / JVM 17+ [README](https://github.com/webmaniabr/webmania-clojure#readme)

   `git clone https://github.com/webmaniabr/webmania-clojure.git`
- [Ruby](https://github.com/webmaniabr/webmania-ruby) Disponível

   Ruby 3.3, Ruby 3.4 [README](https://github.com/webmaniabr/webmania-ruby#readme)

   `git clone https://github.com/webmaniabr/webmania-ruby.git`
- [.NET (C#)](https://github.com/webmaniabr/webmania-dotnet) Disponível

   .NET 10 [README](https://github.com/webmaniabr/webmania-dotnet#readme)

   `git clone https://github.com/webmaniabr/webmania-dotnet.git`
- [PowerShell](https://github.com/webmaniabr/webmania-powershell) Disponível

   PowerShell 7.6 [README](https://github.com/webmaniabr/webmania-powershell#readme)

   `git clone https://github.com/webmaniabr/webmania-powershell.git`
- [Elixir](https://github.com/webmaniabr/webmania-elixir) Disponível

   Elixir ~> 1.18, Linux arm64 [README](https://github.com/webmaniabr/webmania-elixir#readme)

   `git clone https://github.com/webmaniabr/webmania-elixir.git`
- [Rust](https://github.com/webmaniabr/webmania-rust) Disponível

   Rust >= 1.85 [README](https://github.com/webmaniabr/webmania-rust#readme)

   `git clone https://github.com/webmaniabr/webmania-rust.git`
- [Haskell](https://github.com/webmaniabr/webmania-haskell) Disponível

   GHC 9.6.7, Linux arm64 [README](https://github.com/webmaniabr/webmania-haskell#readme)

   `git clone https://github.com/webmaniabr/webmania-haskell.git`
- [Swift](https://github.com/webmaniabr/webmania-swift) Disponível

   macOS 13+, iOS 16+ [README](https://github.com/webmaniabr/webmania-swift#readme)

   `git clone https://github.com/webmaniabr/webmania-swift.git`

### Exemplos

Teste os endpoints da API de CEP 2.0 diretamente pelo Postman ou integre pelo CEP-SDK, que inclui a classe wrapper da API, um endpoint proxy para integração segura com o front-end e exemplos de uso completos.

- [**Coleção Postman** Testes instantâneos Requisições prontas para testar a API sem escrever código. Abrir no Postman](https://www.postman.com/webmania-api/webmania/collection/99c90724-2a35-4e66-9ba1-0be91f88c305)
- [**CEP-SDK** PHP, Node.js, Python, C#, Java e Ruby, com classe wrapper, proxy e exemplos. Ver no GitHub](https://github.com/webmaniabr/CEP-SDK)
- [**Como utilizar** Passo a passo com o CEP-SDK: instalação, token e consulta pelo back-end. Ver o passo a passo](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=como-utilizar)

## SDKs & LLMs › 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.

**Arquitetura recomendada:** Navegador do Usuário → Seu Backend (proxy) → API Webmania. O front-end faz requisições para o seu servidor, que repassa para a API da Webmania com o X-Token de forma segura.

### 1. Instale a SDK

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

Illustrative example; verify syntax and required fields before execution.

```text
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](https://webmania.com.br):

Illustrative example; verify syntax and required fields before execution.

```text
# 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, com o script salvo na pasta `php` da SDK:

Illustrative example; verify syntax and required fields before execution.

```text
// Carregue e instancie a SDK
require_once __DIR__ . '/WebmaniaCep.php';
$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, com o script salvo na pasta `nodejs` da SDK:

Illustrative example; verify syntax and required fields before execution.

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

async function main() {
  const endereco = await cep.consultarCep('01310100');
  console.log(endereco.endereco); // Avenida Paulista
}

main();
```

### 4. Autocomplete de Endereço

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

Illustrative example; verify syntax and required fields before execution.

```text
// 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:

Illustrative example; verify syntax and required fields before execution.

```text
# 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:

| Método | Endpoint Local | Descrição |
| --- | --- | --- |
| GET | `http://localhost:8080/api/cep/{cep}` | Consulta de CEP via proxy |
| GET | `http://localhost:8080/api/cep/autocomplete?q=...` | Autocomplete via proxy |

### 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.

**Importante:** O front-end **nunca** deve acessar a API da Webmania diretamente. Sempre utilize o proxy do back-end para proteger seu `X-Token`. Isso evita o uso indevido da API e protege seus créditos.

## 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. **Consultas novas exigem créditos suficientes; repetições já cobradas e reconhecidas na janela de deduplicação não geram nova cobrança.**

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

```bash
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.

Precisa de credenciais ou ajuda na integração? [Entre em contato](https://webmania.com.br/chat/).

## Consultas Consultar CEP

A consulta devolve o endereço completo de um CEP: logradouro, bairro, cidade, UF e o código IBGE do município. Use-a quando o usuário já informou o CEP.

Para consultar um 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.

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

| Parâmetro | Local | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- | --- |
| `cep` | Path | String | Sim | CEP com 8 dígitos (com ou sem hífen) |
| `X-Token` | Header | String (UUID) | Sim | Token de autenticação |

Exemplo de resposta HTTP `200`:

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

### Campos de resposta

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `cep` | String | CEP formatado com 8 dígitos (sem hífen) |
| `endereco` | String | Logradouro (rua, avenida, etc.) |
| `bairro` | String | Bairro |
| `cidade` | String | Cidade |
| `uf` | String | Sigla do estado (2 caracteres) |
| `ibge` | String ou null | Código IBGE do município (pode ser `null` para alguns CEPs) |

## Consultas Autocomplete

O autocomplete sugere endereços a partir do nome da rua, para formulários com preenchimento automático. Cada resultado traz o CEP do endereço.

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

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

| Parâmetro | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `q` | String | Sim | Texto de busca (mín. 4 caracteres, máx. 120) |
| `uf` | String | Não | Sigla de uma UF brasileira válida, com 2 letras maiúsculas (ex: `SP`) |
| `cidade` | String | Não | Filtro por cidade (máx. 80 caracteres) |
| `bairro` | String | Não | Filtro por bairro (máx. 80 caracteres) |
| `limit` | Integer | Não | Máximo de resultados (1-20, padrão: 10) |

### Expansão de Abreviações

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

| Abreviação | Expansão |
| --- | --- |
| `R.` | Rua |
| `Av.` | Avenida |
| `Trav.` | Travessa |
| `Al.` | Alameda |
| `Pça.` | Praça |

Exemplo de resposta HTTP `200`:

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

**Sem código IBGE.** O endpoint de autocomplete **não retorna** o campo `ibge`. Caso precise do código IBGE, utilize o CEP retornado para [consultar o CEP](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=consultar-cep) no endpoint `/2/cep/{cep}`.

## Uso e Créditos 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`.

**Anti-scraping no autocomplete.** Padrões suspeitos nesse endpoint podem bloquear temporariamente novas chamadas de autocomplete do cliente por 5 ou 30 minutos (status `403`), conforme a gravidade.

### Consulta de CEP

| Tipo | Limite Contínuo | Burst (10s) |
| --- | --- | --- |
| Por token | 2 req/s | 12 requisições |
| Por IP | 8 req/s | 40 requisições |

### Autocomplete

| Tipo | Limite Contínuo | Burst (10s) |
| --- | --- | --- |
| Por token | 5 req/s | 30 requisições |
| Por IP | 10 req/s | 60 requisições |

## Uso e Créditos Créditos

Consultas novas à API de CEP 2.0 exigem créditos suficientes. Quando a requisição é reconhecida como repetição de uma consulta já cobrada na janela de deduplicação, não há novo débito.

| Endpoint | Créditos por consulta | Deduplicação |
| --- | --- | --- |
| `/2/cep/{cep}` | 0.10 | 24 horas |
| `/2/cep/autocomplete` | 0.005 | 24 horas |

A deduplicação é por cliente e endpoint, durante 24 horas após a cobrança reconhecida. Na consulta, considera o mesmo CEP normalizado. No autocomplete, considera o texto de busca normalizado e os filtros `uf` e `cidade`; `bairro` e `limit` não alteram essa identificação. Em uma repetição reconhecida, `creditos_consumidos` no autocomplete é `0`. Falhas no reconhecimento da repetição podem gerar nova cobrança.

## Erros

Quando uma requisição falha, a resposta contém o campo `error` no formato JSON e pode incluir `message`. Abaixo estão os principais status e exemplos; o texto de `error` pode variar conforme a validação ou a consulta. Trate o status HTTP e não dependa de uma única mensagem.

| Status HTTP | Erro | O que significa | O que fazer |
| --- | --- | --- | --- |
| `401` | Unauthorized | Token não encontrado ou inválido. | Verifique o header `X-Token`. |
| `402` | insufficient_credits | Créditos insuficientes para processar a requisição. | Adquira mais créditos no painel. |
| `403` | access_temporarily_blocked | Autocomplete bloqueado por atividade suspeita (anti-scraping). | Aguarde o bloqueio de 5 ou 30 minutos expirar. Veja [Limites de Uso](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=limites). |
| `404` | CEP não encontrado | O CEP informado não existe na base de dados. | Verifique o CEP informado. |
| `422` | CEP inválido. | Parâmetros da requisição inválidos (CEP inválido, query muito curta, etc.). | Corrija os parâmetros conforme a documentação de [Consultar CEP](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=consultar-cep) e [Autocomplete](https://webmania.com.br/docs/rest-api-cep-ibge/?format=markdown&secao=autocomplete). |
| `429` | Too Many Requests | Limite de requisições por segundo excedido. | Aguarde alguns segundos e tente novamente, com a estratégia de retry abaixo. |
| `500` | internal_error | Erro interno do servidor. | Tente novamente. Se persistir, contate o suporte. |
| `503` | Não foi possível localizar o CEP. | Serviço de consulta temporariamente indisponível. | Tente novamente em instantes, com a estratégia de retry abaixo. |

### 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

A API da Webmania® roda 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). A entrada é **anycast** e de alta disponibilidade: de qualquer lugar do mundo, a sua requisição é redirecionada para o servidor mais próximo da sua localidade.

**Entrada anycast da API da Webmania ao redor do mundo:** Mapa-múndi com a região us-east-1, no Leste dos EUA, e o ponto de presença sa-east-1, em São Paulo. Requisições de várias partes do mundo entram pela rede anycast e são redirecionadas para o servidor mais próximo: a América do Norte, a Europa e a Ásia para us-east-1, e a América do Sul, a África e a Oceania para sa-east-1.

Região AWS da Webmania Sua aplicação Rota anycast até o servidor mais próximo

 Ilustração. Os pontos representam aplicações em diferentes regiões do mundo, não endereços reais de servidores.

#### Anycast global

Os mesmos IPs de entrada atendem o mundo todo. A requisição é redirecionada para o servidor mais próximo da sua localidade, sem configuração do seu lado.

#### Duas localidades AWS

us-east-1 (Leste dos EUA) e sa-east-1 (São Paulo). Manter a sua estrutura perto de uma delas garante um menor tempo de resposta.

#### IPs estáticos

Entrada e saída por IPs fixos: libere no firewall e confira a origem das notificações recebidas.

**IPs estáticos de entrada** Requisições da sua aplicação para a API.

- `13.248.145.90`
- `76.223.17.240`

**IPs estáticos de saída** Notificações enviadas pela Webmania® para a sua URL.

- `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 credenciais de acesso válidas nos headers indicados na seção Autenticação; o envio incorreto é atribuído como uso indevido da API.

## Changelog

1. **v2.0.1** · 09/11/2026 · Documentação · Adicionado

   A documentação agora é compatível com LLMs: cópia da página ou de cada seção em Markdown, índice por seção e llms.txt.
