API de CEP

Consulta de endereço completo a partir do código postal brasileiro. Dados dos Correios.

Visão Geral

Aceita CEP em ambos os formatos: 12345678 ou 12345-678. Respostas são cacheadas por 1 hora.

Autenticação

Bearer token no header Authorization. Sem chave válida retorna 401.

Authorization: Bearer sr_live_sua_chave_aqui

Endpoint

GET/api/public/cep/{cep}

Auth10/min por IP

Parâmetros de path

Campo	Tipo	Obrig.	Descrição
`cep`	string	sim	CEP brasileiro (8 dígitos). Aceita `12345678` ou `12345-678`.

Formato da Resposta

Sucesso (200)

{
  "cep": "02037001",
  "status": "found",
  "success": true,
  "data": {
    "cep": "02037-001",
    "logradouro": "Rua Voluntários da Pátria",
    "complemento": "",
    "bairro": "Santana",
    "localidade": "São Paulo",
    "uf": "SP",
    "ibge": "3550308"
  },
  "cached": false,
  "message": "CEP consultado com sucesso na API dos Correios."
}

Não encontrado (404)

{
  "cep": "00000000",
  "status": "not_found",
  "success": false,
  "message": "CEP não encontrado nos registros dos Correios"
}

CEP inválido (400)

{
  "cep": "abc",
  "status": "invalid_format",
  "success": false,
  "message": "Formato de CEP inválido. Use o formato: 12345678 ou 12345-678"
}

Códigos de Status

Status	Significado
`200`	CEP encontrado.
`400`	Formato inválido (`invalid_format` ou `invalid_cep`).
`401`	Chave de API ausente ou inválida.
`404`	CEP não localizado nos registros dos Correios.
`500 / 503`	Erro temporário do serviço.

Exemplos

cURL

curl -H "Authorization: Bearer sr_live_sua_chave_aqui" \
  "https://seurastreio.com.br/api/public/cep/02037001"

JavaScript

const res = await fetch(
  "https://seurastreio.com.br/api/public/cep/02037001",
  { headers: { Authorization: "Bearer sr_live_sua_chave_aqui" } },
);
const { data } = await res.json();
console.log(data.logradouro, data.localidade);

Python

import requests

r = requests.get(
    "https://seurastreio.com.br/api/public/cep/02037001",
    headers={"Authorization": "Bearer sr_live_sua_chave_aqui"},
)
print(r.json()["data"])

Respostas com sucesso são cacheadas por 1 hora (2 horas se vieram do cache interno). Erros são cacheados por 1-5 minutos.