API de consulta de CEP
O endpoint de CEP retorna o endereço a partir do código postal de 8 dígitos — logradouro, bairro, cidade, UF, além de IBGE e DDD quando disponíveis (dados dos Correios via ViaCEP). É o ponto de partida gratuito para você testar a integração antes de ativar um plano.
Para que serve
- Preenchimento automático de endereço em formulários de checkout.
- Validação de endereço informado pelo cliente.
- Enriquecimento de cadastro com cidade, UF e código IBGE.
Requisição
Autentique com o header Authorization: Bearer — gere seu token no dashboard após ativar um plano.
curl -X POST "https://apiconsultas.xyz/api/v1/consultas/cep" \
-H "Authorization: Bearer dp_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"cep":"01001000"}'const res = await fetch("https://apiconsultas.xyz/api/v1/consultas/cep", {
method: "POST",
headers: {
Authorization: "Bearer dp_live_xxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({"cep":"01001000"}),
});
const data = await res.json();<?php
$ch = curl_init("https://apiconsultas.xyz/api/v1/consultas/cep");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer dp_live_xxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => '{"cep":"01001000"}',
]);
$data = json_decode(curl_exec($ch), true);Resposta (200)
Exemplo com valores ilustrativos. O nível de detalhe (dados completos ou mascarados) depende do seu plano.
{
"success": true,
"tipo_consulta": "cep",
"query": {
"termo_mascarado": "01001-000",
"finalidade": "validacao_endereco"
},
"resultado_count": 1,
"data_quality": {
"sources_used": 1,
"confidence_score": 99,
"has_address": true
},
"data": [
{
"localizacao": {
"cep": "01001-000",
"cidade": "São Paulo",
"estado": "SP",
"enderecos_detalhados": [
{
"logradouro": "Praça da Sé",
"bairro": "Sé",
"cidade": "São Paulo",
"estado": "SP",
"ibge": "3550308",
"ddd": "11"
}
]
}
}
],
"audit": {
"logged": true,
"timestamp": "2026-07-01T12:00:00.000Z"
},
"message": "Consulta realizada com sucesso."
}Campos retornados
| Campo | Descrição |
|---|---|
| cep | CEP normalizado (00000-000). |
| logradouro / bairro | Logradouro e bairro. |
| cidade / estado | Município e UF. |
| enderecos_detalhados[].ibge / ddd | Código IBGE e DDD, quando disponíveis. |
Perguntas frequentes
A consulta de CEP é mesmo gratuita?
Sim. Você pode testar a consulta de CEP direto na página inicial, sem cadastro. Os demais tipos de consulta exigem um plano ativo.
De onde vêm os dados de CEP?
Dos Correios, via ViaCEP. São dados públicos de endereçamento postal — logradouro, bairro, cidade, UF, IBGE e DDD.
O que retorna para um CEP inexistente?
Um erro indicando CEP não encontrado. CEPs com formato inválido (diferente de 8 dígitos) retornam erro 400.
Endpoints relacionados
Quer testar sem cadastro? Use a amostra gratuita de CEP na página inicial.
Integre consulta de cep hoje
Ative um plano a partir de R$ 10, gere seu token Bearer e comece a consultar em minutos. Consultas ilimitadas enquanto o plano estiver ativo.