Emissor Fiscal · todos os modelos
NFS-e em mais de 5.000 municípios
+15 milhõesde documentos fiscais por mês
Conheça as soluções Webmania® para o seu negócio e escolha a ideal para sua operação.
Agendar demonstraçãoConsulte condições e serviços disponíveis.
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.
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.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:
Endereço, bairro, cidade, UF e código IBGE a partir do CEP com 8 dígitos, no GET /2/cep/{cep}.
Busca por nome de rua com filtros por UF, cidade e bairro, no GET /2/cep/autocomplete.
Cada consulta nova usa créditos. Repetições reconhecidas na janela de 24 horas não consomem créditos adicionais.
A autenticação é pelo cabeçalho X-Token. Proteja o token e nunca o exponha no front-end.
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.
Como integrar a API de CEP:
X-Token. /2/cep/{cep}, com o CEP de 8 dígitos. A resposta traz endereço, bairro, cidade, UF e o código IBGE. /2/cep/autocomplete com o texto em q, para o usuário escolher o endereço pelo nome da rua. 401 para o token, 402 para créditos, 429 para o limite por segundo, entre outros. 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:
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:
{
"error": "Unauthorized",
"message": "Acesso restrito."
} A lista completa dos status, com o que fazer em cada um, está em Erros.
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.
410 Gone. Utilize a API 2.0.| 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 |
api.webmania.com.br/2/cep/{cep} no lugar do endpoint legado /api/1/cep/{cep}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.
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.
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.
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 Disponível
git clone https://github.com/
Python Disponível
git clone https://github.com/
PHP Disponível
git clone https://github.com/
Perl Disponível
git clone https://github.com/
Go Disponível
git clone https://github.com/
C Disponível
git clone https://github.com/
C++ Disponível
git clone https://github.com/
Lua Disponível
git clone https://github.com/
Dart Disponível
git clone https://github.com/
R Disponível
git clone https://github.com/
Java Disponível
git clone https://github.com/
Kotlin Disponível
git clone https://github.com/
Scala Disponível
git clone https://github.com/
Clojure Disponível
git clone https://github.com/
Ruby Disponível
git clone https://github.com/
.NET (C#) Disponível
git clone https://github.com/
PowerShell Disponível
git clone https://github.com/
Elixir Disponível
git clone https://github.com/
Rust Disponível
git clone https://github.com/
Haskell Disponível
git clone https://github.com/
Swift Disponível
git clone https://github.com/
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.
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.
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/ 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" Exemplo em PHP, com o script salvo na pasta php da SDK:
// 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:
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(); 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'];
} 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:
| 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 |
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.
X-Token. Isso evita o uso indevido da API e protege seus créditos. 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:
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.
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.
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:
{
"cep": "01310100",
"endereco": "Avenida Paulista",
"bairro": "Bela Vista",
"cidade": "Sao Paulo",
"uf": "SP",
"ibge": "3550308"
} | 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) |
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.
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) |
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:
{
"resultados": [
{
"cep": "09726310",
"endereco": "Rua das Flores",
"bairro": "Jardim do Mar",
"cidade": "Sao Bernardo do Campo",
"uf": "SP"
}
],
"total": 1,
"creditos_consumidos": 0.005
} ibge. Caso precise do código IBGE, utilize o CEP retornado para consultar o CEP no endpoint /2/cep/{cep}.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.
403), conforme a gravidade.| Tipo | Limite Contínuo | Burst (10s) |
|---|---|---|
| Por token | 2 req/s | 12 requisições |
| Por IP | 8 req/s | 40 requisições |
| Tipo | Limite Contínuo | Burst (10s) |
|---|---|---|
| Por token | 5 req/s | 30 requisições |
| Por IP | 10 req/s | 60 requisições |
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.
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. |
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 e 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. |
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.
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.
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.
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.
Entrada e saída por IPs fixos: libere no firewall e confira a origem das notificações recebidas.
13.248.145.9076.223.17.24034.196.69.3844.219.142.86A 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.
https://webmania.com.br/api/ retorne 403 Erro Forbidden entre em contato para liberarmos o IP do seu servidor. 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.