Documentação da API
APIs RESTful para rastreamento de encomendas e consulta de CEP dos Correios brasileiros.
- Sem chave de API - Comece a usar imediatamente
- CORS habilitado - Use de qualquer domínio
- Rate limiting - 10 requisições por minuto por IP
- Respostas em cache - Rápido e confiável
Início Rápido
Rastreamento de Encomendas
Requer chave de API (obtenha gratuitamente no Dashboard → Chaves de API).
GET https://seurastreio.com.br/api/public/rastreio/[codigo]curl -H "Authorization: Bearer SUA_API_KEY" "https://seurastreio.com.br/api/public/rastreio/BR123456789BR"
Consulta de CEP
Requer chave de API (obtenha gratuitamente no Dashboard → Chaves de API).
GET https://seurastreio.com.br/api/public/cep/[cep]curl -H "Authorization: Bearer SUA_API_KEY" "https://seurastreio.com.br/api/public/cep/02037001"
API de Rastreamento de Encomendas
Rastreie encomendas dos Correios e obtenha as informações de status mais recentes. A API pública exige chave de API; você pode gerar uma gratuitamente no Dashboard → Chaves de API.
Autenticação
Envie sua chave de API no header Authorization:
Authorization: Bearer sr_live_sua_chave_aquiSem a chave ou com chave inválida a API retorna 401 com mensagem e link para obter uma chave gratuitamente.
Endpoints
/api/public/rastreio/[codigo]Obtenha as informações de rastreamento mais recentes de uma encomenda. Requer header Authorization com chave de API.
Parâmetros
codigoCódigo de rastreamento no formato: AB123456789BR
Formato da Resposta
Resposta de Erro - Sem/inválida API key (401)
{
"success": false,
"message": "Missing or invalid Authorization header. Gere uma chave de API gratuitamente em nosso site: https://seurastreio.com.br (Dashboard → Chaves de API).",
"helpUrl": "https://seurastreio.com.br/dashboard"
}Resposta de Sucesso (200)
{
"codigo": "BR123456789BR",
"status": "found",
"success": true,
"eventoMaisRecente": {
"codigo": "BDE",
"descricao": "Objeto entregue ao destinatário",
"detalhe": "Entrega realizada",
"data": "2024-01-15T14:30:00.000Z",
"local": "São Paulo/SP",
"destino": null
},
"linkDetalhesCompletos": "https://seurastreio.com.br/objetos/BR123456789BR",
"message": "Evento mais recente encontrado."
}Resposta de Erro (400/404)
{
"codigo": "INVALID123",
"status": "invalid_format",
"success": false,
"message": "Formato de código de rastreamento inválido",
"linkDetalhesCompletos": "https://seurastreio.com.br/objetos/INVALID123"
}Códigos de Status
| Status | Descrição |
|---|---|
401 | Chave de API ausente ou inválida. O corpo inclui message e helpUrl para obter uma chave gratuitamente. |
found | Encomenda encontrada com eventos de rastreamento |
not_found | Encomenda não encontrada no sistema dos Correios |
invalid_format | Formato de código de rastreamento inválido |
service_error | Erro temporário no serviço |
API de Consulta de CEP
Obtenha informações completas de endereço usando códigos postais brasileiros (CEP). A API pública de CEP exige chave de API; você pode gerar uma gratuitamente no Dashboard → Chaves de API.
Autenticação
Envie sua chave de API no header Authorization:
Authorization: Bearer sr_live_sua_chave_aquiSem a chave ou com chave inválida a API retorna 401 com mensagem explicando como obter uma chave gratuitamente no site.
Endpoints
/api/public/cep/[cep]Obtenha informações completas de endereço para um CEP. Requer header Authorization com chave de API.
Parâmetros
cepCódigo postal brasileiro com 8 dígitos (12345678 ou 12345-678)
Formato da Resposta
Resposta de Erro - Sem/inválida API key (401)
{
"success": false,
"message": "Missing or invalid Authorization header. Gere uma chave de API gratuitamente em nosso site: https://seurastreio.com.br (Dashboard → Chaves de API).",
"helpUrl": "https://seurastreio.com.br/dashboard"
}Resposta de Sucesso (200)
{
"cep": "02037001",
"status": "found",
"success": true,
"cached": true,
"data": {
"cep": "02037001",
"uf": "SP",
"localidade": "São Paulo",
"logradouro": "Rua Doutor Olavo Egídio",
"bairro": "Santana",
"complemento": "- de 451/452 ao fim",
"numeroInicial": 451,
"numeroFinal": 99999
},
"message": "CEP encontrado no cache."
}Códigos de Status
| Status | Descrição |
|---|---|
401 | Chave de API ausente ou inválida. O corpo da resposta inclui message e helpUrl para obter uma chave gratuitamente. |
found | CEP encontrado com dados completos |
not_found | CEP não encontrado nos registros dos Correios |
invalid_format | Formato de CEP inválido (deve ter 8 dígitos) |
service_error | Erro temporário no serviço |
Exemplos
JavaScript
Rastreamento de Encomendas
const API_KEY = 'sr_live_sua_chave'; // Obtenha em Dashboard → Chaves de API
async function rastrearEncomenda(codigo) {
const response = await fetch('https://seurastreio.com.br/api/public/rastreio/' + codigo, {
headers: { 'Authorization': 'Bearer ' + API_KEY }
});
const data = await response.json();
if (data.success) {
console.log('Status:', data.eventoMaisRecente.descricao);
console.log('Local:', data.eventoMaisRecente.local);
console.log('Data:', data.eventoMaisRecente.data);
} else {
console.log('Erro:', data.message);
if (response.status === 401 && data.helpUrl) window.open(data.helpUrl);
}
}
rastrearEncomenda('BR123456789BR');Consulta de CEP
const API_KEY = 'sr_live_sua_chave'; // Obtenha em Dashboard → Chaves de API
async function consultarCEP(cep) {
const response = await fetch('https://seurastreio.com.br/api/public/cep/' + cep, {
headers: { 'Authorization': 'Bearer ' + API_KEY }
});
const data = await response.json();
if (data.success) {
console.log('Endereço:', data.data.logradouro);
console.log('Bairro:', data.data.bairro);
console.log('Cidade:', data.data.localidade, data.data.uf);
console.log('Cache:', data.cached);
} else {
console.log('Erro:', data.message);
if (response.status === 401 && data.helpUrl) window.open(data.helpUrl);
}
}
consultarCEP('02037001');Python
Rastreamento de Encomendas
import requests
API_KEY = "sr_live_sua_chave" # Obtenha em Dashboard → Chaves de API
def rastrear_encomenda(codigo):
url = f"https://seurastreio.com.br/api/public/rastreio/{codigo}"
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.get(url, headers=headers)
data = response.json()
if data["success"]:
evento = data["eventoMaisRecente"]
print(f"Status: {evento['descricao']}")
print(f"Local: {evento['local']}")
print(f"Data: {evento['data']}")
else:
print(f"Erro: {data['message']}")
if response.status_code == 401 and data.get("helpUrl"):
print(f"Obtenha uma chave: {data['helpUrl']}")
rastrear_encomenda("BR123456789BR")Consulta de CEP
import requests
API_KEY = "sr_live_sua_chave" # Obtenha em Dashboard → Chaves de API
def consultar_cep(cep):
url = f"https://seurastreio.com.br/api/public/cep/{cep}"
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.get(url, headers=headers)
data = response.json()
if data["success"]:
endereco = data["data"]
print(f"Endereço: {endereco['logradouro']}")
print(f"Bairro: {endereco['bairro']}")
print(f"Cidade: {endereco['localidade']} - {endereco['uf']}")
print(f"Cache: {data['cached']}")
else:
print(f"Erro: {data['message']}")
if response.status_code == 401 and data.get("helpUrl"):
print(f"Obtenha uma chave: {data['helpUrl']}")
consultar_cep("02037001")cURL
Rastreamento de Encomendas
curl -X GET "https://seurastreio.com.br/api/public/rastreio/BR123456789BR" \ -H "Accept: application/json" \ -H "Authorization: Bearer SUA_API_KEY"
Consulta de CEP
curl -X GET "https://seurastreio.com.br/api/public/cep/02037001" \ -H "Accept: application/json" \ -H "Authorization: Bearer SUA_API_KEY"
Páginas personalizadas
Times com página pública ativa podem oferecer aos clientes duas URLs com a identidade da loja (logo, título, cores), sem o header do site principal.
Dashboard → Times → [seu time] → Personalize sua página de Rastreios. Ative a página, defina o slug do time (usado na URL) e personalize logo, título e cor.
Com NEXT_PUBLIC_APP_DOMAIN configurado (ex.: seurastreio.com.br), as URLs usam subdomínio (ex.: sualoja.seurastreio.com.br). Sem isso, usa-se /loja/[slug].
As duas URLs
https://[slug].seurastreio.com.brOu, sem subdomínio: https://seurastreio.com.br/loja/[slug]
https://[slug].seurastreio.com.br/objetos/[CODIGO]Ex.: https://sualoja.seurastreio.com.br/objetos/AB123456789BR
API e linkDetalhesCompletos
A API de rastreamento GET /api/public/rastreio/[codigo] retorna sempre o campo linkDetalhesCompletos: o link para a página onde o usuário pode ver o histórico completo do rastreio.
Quando a requisição é feita com uma chave de API vinculada a um time que tem página pública ativa, esse link aponta para a URL personalizada do time (subdomínio + /objetos/[codigo]). Assim, ao enviar esse link ao cliente (e-mail, WhatsApp, etc.), ele abre a página com a identidade da sua loja.
// Resposta da API (com chave de um time com página ativa):
{
"codigo": "AB123456789BR",
"status": "found",
"success": true,
"eventoMaisRecente": { ... },
"linkDetalhesCompletos": "https://sualoja.seurastreio.com.br/objetos/AB123456789BR",
"message": "Evento mais recente encontrado."
}Se o time não tiver página pública ou a chave não for de um time, linkDetalhesCompletos aponta para o domínio principal: https://seurastreio.com.br/objetos/[codigo].
Testes
Sem chave, a requisição retorna 401 com mensagem e link para gerar uma chave gratuitamente.
Sem chave, a requisição retorna 401 com mensagem e link para gerar uma chave gratuitamente.
Ambas as APIs têm limite de 10 requisições por minuto por endereço IP.
Se você exceder este limite, receberá uma resposta 429 Too Many Requests.