REST API de Consulta CEP e IBGE

Guia Rápido

Todas as solicitações na API devem ser realizadas em ambiente criptografado HTTPS através da URL https://webmaniabr.com/api/. O prefixo /1/ indica que atualmente nós estamos utilizando a versão 1.0 da API.

Todas as respostas são no formato objeto JSON.

Autenticação GRÁTIS

Envie na URL de solicitação os parâmetros app_key e app_secret da sua aplicação. Não possui ainda uma aplicação? Preencha o seu e-mail no formulário abaixo para receber as suas credenciais grátis.

Autenticação
Assinantes

Ao assinar o plano da API de CEP você receberá o parâmetro X-Token por e-mail. Para que possa utilizar todos os recursos da API, a autenticação para assinantes pode ser realizada de duas formas:

• No cabeçalho HTTP (HTTP Headers) ao enviar o parâmetro X-Token
• Cadastrar o IP do servidor no endpoint /1/cep/tokens/

Em ambas formas de autenticação, também deve ser enviado na URL da requisição os parâmetros app_key e app_secret da sua aplicação.

Mantenha a credencial de acesso X-Token em segurança. Utilize somente em aplicações onde o processamento do código ocorre no server-side (back-end), para as aplicações client-side (front-end) deve ser suprimido a header X-Token e autorizado o IP do servidor para usufruir do seu plano contratado.

Segue abaixo exemplo de requisição server-side (PHP, Python, NodeJS, Java, etc):

curl -X GET \
-H "X-Token: SEU_TOKEN" \ 
-H "Content-Type: application/json" \
https://webmaniabr.com/api/1/cep/[endpoint]/?app_key=SEU_APP_KEY&app_secret=SEU_APP_SECRET

Segue abaixo exemplo de requisição front-side (Javascript) através de um IP autorizado:

curl -X GET -interface 00.00.00.00 \
-H "Content-Type: application/json" \
https://webmaniabr.com/api/1/cep/[endpoint]/?app_key=SEU_APP_KEY&app_secret=SEU_APP_SECRET

Javascript GRÁTIS

Utilize o jQuery da Webmania® para consultas Ajax nos Correios, com preenchimento automático do formulário. Verifique em nosso repositório no GitHub mais informações de como utilizar o script.

<script src="jquery.js"></script>
<script src="jquery.correios.min.js"></script>

<script>
jQuery(function($){
    correios.init( 'app_key', 'app_secret' );
    $('cep').correios( 'endereco', 'bairro', 'cidade', 'uf' );
});
</script>

Consultar CEP GRÁTIS

Para realizar a consulta do CEP, envie a requisição no método GET para a URL /1/cep/0000-000/ com as credenciais da sua aplicação. Segue abaixo exemplo:

curl -X GET \
-H "Content-Type: application/json" \
https://webmaniabr.com/api/1/cep/05426-100/?app_key=SEU_APP_KEY&app_secret=SEU_APP_SECRET

A resposta do corpo da mensagem será no formato objeto JSON, contendo os campos endereco, bairro, cidade, uf, cep e ibge:

{
  "endereco": "Avenida Brigadeiro Faria Lima",
  "bairro": "Pinheiros",
  "cidade": "São Paulo",
  "uf": "SP",
  "cep": "05426100",
  "ibge": "3550308"
}

Uma requisição bem sucedida é indicada através do status HTTP, o status 2xx indica sucesso. Quando uma requisição ocorre falha o corpo da resposta [body] continua no formato JSON, mas sempre contém o campo error. Caso o CEP seja inválido ou não seja localizado o endereço, será retornado a seguinte mensagem:

{
  "error": "CEP não encontrado"
}

Consultar Requisições e Limites GRÁTIS

Para consultar o uso das requisções e os limites da API, envie a requisição no método GET para a URL /1/cep/requests/ com as credenciais da sua aplicação. Segue abaixo exemplo:

curl -X GET \
-H "Content-Type: application/json" \
https://webmaniabr.com/api/1/cep/requests/?app_key=SEU_APP_KEY&app_secret=SEU_APP_SECRET

A resposta do corpo da mensagem será no formato objeto JSON, contendo os campos total, limit, expires_in e plan:

{
  "total": 0, // Requisições
  "limit": 300, // Limite de requisições
  "expires_in": "2023-09-30 23:59:59", // Data de expiração
  "plan": "free" // Plano atual
}

Gerenciar IP's

Gerencie o IP dos servidores e utilize todos os recursos da API, sem precisar informar o parâmetro X-Token no cabeçalho Header da requisição. Praticidade na integração e segurança nas requisições para utilizar o plano contratado.

Para consultar todos os IP's autorizados envie a requisição no método GET para a URL /1/cep/tokens/ com as credenciais da sua aplicação.

curl -X GET \
-H "X-Token: SEU_TOKEN" \ 
-H "Content-Type: application/json" \
https://webmaniabr.com/api/1/cep/tokens/?app_key=SEU_APP_KEY&app_secret=SEU_APP_SECRET

A resposta do corpo da mensagem será uma array no formato objeto JSON, contendo os campos token e date:

[
  {
  "token": "000.000.000.000", // IP do servidor
  "date": "0000-00-00 00:00:00" // Data/hora de registro
  },  ...
]

Gerenciar IP's
Cadastrar

Para cadastrar um novo IP, envie a requisição no método POST para a URL /1/cep/tokens/ contendo no corpo o parâmetro ip.

curl -X POST \
-H "X-Token: SEU_TOKEN" \ 
-H "Content-Type: application/json" \
-d '{
    "ip":"000.000.000.000"
}'
https://webmaniabr.com/api/1/cep/tokens/?app_key=SEU_APP_KEY&app_secret=SEU_APP_SECRET

A resposta do corpo da mensagem será no formato objeto JSON contendo o campo success:

{
  "success": "Endereço de IP 000.000.000.000 adicionado com sucesso."
}

Gerenciar IP's
Excluir

Para excluir um IP autorizado anteriormente, envie a requisição no método DELETE para a URL /1/cep/tokens/ contendo no corpo o parâmetro ip.

curl -X DELETE \
-H "X-Token: SEU_TOKEN" \ 
-H "Content-Type: application/json" \
-d '{
    "ip":"000.000.000.000"
}'
https://webmaniabr.com/api/1/cep/tokens/?app_key=SEU_APP_KEY&app_secret=SEU_APP_SECRET

A resposta do corpo da mensagem será no formato objeto JSON contendo o campo success:

{
  "success": "Endereço de IP 000.000.000.000 removido com sucesso."
}

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 IP's estáticos, caso necessite autorize no firewall a comunicação com os seguintes IP's:

• 13.248.145.90
• 76.223.17.240

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://webmaniabr.com/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.