Se você precisa implementar a busca de cep em seus aplicativos, você pode utilizar nossa API de maneira rápida e simples,
basta implementar uma requisição para
https://consultacep.brasap.com.br/api/cep/01031-970
utilizando o cep
que deseja consultar, como no exemplo 01031-970 é o cep da Agencia Central dos Correios no - Vale do Anhangabau.
É muito simples, o retorno ocorre em formato
JSON e pode ser usado em milhares de sistemas diferentes. Veja o exemplo do
retorno para o cep 01031-970:
{
"server": "BRASAP TECNOLOGIA E SISTEMAS LTDA - Versão 1.0",
"exec_time": "0.123 - Segundos",
"erro": false,
"erro_no": "200",
"erro_msg": "SUCESSO",
"response": {
"registros": "1",
"dados": {
"data_atualizacao": "15-04-2022 13:06:52",
"cep": "01031970",
"tipo": "AGENCIAS CORREIOS",
"logradouro_completo": "Praça do Correio, s/n",
"logradouro": "Praça do Correio, s/n",
"complemento": "",
"unidade": "Praça do Correio, s/n",
"bairro": "Centro",
"cidade": "São Paulo",
"uf": "SP",
"pais": "Brasil"
}
}
}
Esta é a resposta padrão, e é composta de um
objeto JSON (JavaScript Object Notation)
, que é uma forma leve
e baseada em texto legível por humanos para a troca de informações entre diferentes sistemas e programas, sendo a forma
mais utilizada para a troce de informações entre
APIs (Application Program Interface / Interface de Programação de
Aplicação)
no padrão REST.
O JSON é construído em uma coleção de pares nome/valor, que pode ser implementado em várias linguagens, onde cada um dos
pares tem o significado abaixo:
- server: Identificação do servidor e versão da api utilizada
- exec_time: Tempo de resposta da API em milissegundos
- erro: Um
booleano
que indica se houve erros da API, caso o valor retornado seja TRUE
(verdadeiro), a API esta passando por dificuldades técnicas ou existiu algum erro no processamento, o erro retornado
segue o código de retorno HTTP de estado.
- erro_no: O núme do erro, seguindo o padrão HTTP caso queira utilizar mensagens personalizadas de erro aos seus
usuários.
- erro_msg: Um texto, em português contendo uma breve explicação do erro, que pode ser implementada diretamente
aos usuários como resposta de erro de utilização ou comunicação.
- response: Um objeto que compõe o conjunto de resultados da consulta de cep realizadas, cada chave/valor retornado
tem também um significado, e é diretamente utilizado como corpo da resposta. Como segue:
- registros: O número de respostas de objetos de CEP retornados no conjunto de resultados, 0 caso o cep que tenha
sido informado não seja localizado. O método GET exige um numero de CEP e retorna um conjunto com 1 (um) único
resultado. Outros métodos podem retornar conjuntos paginados e uma quantidade maior de resultados.
- dados: conjunto de resultado do retorno, contendo os dados da consulta, ou um resultado vazio para os campos
que não possuem informação relevante. Como segue:
- data_atualizacao: Data onde o CEP foi atualizado pelos correios, ou pelo DNE (Departamento Nacional de
Endereçamento.
- cep: o Código de Endereçamento Postal que foi consultado, somente os digitos numéricos
- tipo: o TIPO pode ser de 5 valores textuais diferentes, onde:
CEP COMUM
um código de CEP pertencente a um logradouro, ou parte de um logradouro.
CEP ÚNICO
um cep único para localidades não codificadas por ruas e endereços, como cidades
ou bairros.
AGENCIAS CORREIOS
indicam que o CEP pertence a uma unidade dos Correios, ou endereços destinados
ao manuseio ou entrega/retirada de mercadorias oriundas dos serviços postais prestados pelos correios.
GRANDES CLIENTES
indicam ceps que pertencem a Grandes Utilizadores ou centralizadoras como Caixas
Postais ou unidades tratadas de maneira especial, que podem possuir regras próprias e prazos de entrega diferentes
para os serviços postais, ou regras de identificação de usuário/destinatário final diferente do padrão de
endereçamento usado pelos logradouros, como a identificação exclusiva do usuário/destinatario final.
OUTROS
são CEPS que podem ser de uso único ou temporário, como para uma promoção ou podem ter alguma
outra tratativa especial por parte dos correios, e que podem sofrer alterações sem aviso prévio.
- logradouro_completo: O logradouro final que o CEP se refere, como por exemplo uma parte de uma Rua ou
Avenida, ou sua totalidade, numerações específicas que usam o CEP para grandes usuários ou prédios, etc.
- logradouro: O logradouro a ser preenchido pelo usuário (utilizado no preenchimento automático)
- complemento: Caso exista, indica que o logradouro pode ter outro sufixo de CEP para usuários/destinatarios
diferentes. P.Ex numerais pares ou impares, até um numero ou combinação destes.
- unidade: em casos de ceps de GRANDES USUARIOS ou AGENCIAS CORREIOS indicam qual o nome da unidade ao qual o
cep se referencia. Em outros casos, indica parte do logradouro usada no endereçamento.
- bairro: representam o nome do bairro ou distrito ao qual aquele CEP se referencia, sendo somente um dado
informetivo ou complementar, já que não existe legislação específica para determinar ou delimitar bairros e distritos
- cidade: indicam o municipio ao qual o CEP se representa, o nome segue a grafia oficial, algumas podem ter
dados relativos a identificação tradicional, geralmente apresentados entre parenteses (). Seguem a indicação de nomes
do IBGE (Instituto Brasileiro de Geografia e Estatística).
- uf: Indicam a sigra da Unidade Federada ou estado no Brasil.
- pais: sempre retorna Brasil.