Documentação da API

APIs RESTful para rastreamento de encomendas e consulta de CEP dos Correios brasileiros.

Rastreamento de Encomendas
Obtenha o status mais recente de qualquer encomenda dos Correios com uma simples chamada de API.
Grátis
Tempo Real
Consulta de CEP
Obtenha informações completas de endereço usando códigos postais brasileiros (CEP).
Grátis
Atualizado Diariamente
Características
  • 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_aqui

Sem a chave ou com chave inválida a API retorna 401 com mensagem e link para obter uma chave gratuitamente.

Endpoints

GET
/api/public/rastreio/[codigo]

Obtenha as informações de rastreamento mais recentes de uma encomenda. Requer header Authorization com chave de API.

Parâmetros

codigo
string
obrigatório

Có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

StatusDescriçã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_aqui

Sem a chave ou com chave inválida a API retorna 401 com mensagem explicando como obter uma chave gratuitamente no site.

Endpoints

GET
/api/public/cep/[cep]

Obtenha informações completas de endereço para um CEP. Requer header Authorization com chave de API.

Parâmetros

cep
string
obrigatório

Có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

StatusDescriçã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.

Onde configurar

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

1. Página de consulta de pedidos
Onde o cliente informa e-mail ou CPF/CNPJ e, opcionalmente, o número do pedido. Se houver um único pedido ou pedido + documento batendo, mostra status e rastreio; caso contrário, lista os pedidos para o cliente escolher.
https://[slug].seurastreio.com.br

Ou, sem subdomínio: https://seurastreio.com.br/loja/[slug]

2. Página de rastreio direto (por código)
Link direto para ver o rastreamento de um código (ex.: AB123456789BR). Mesma aparência da loja, sem botão “Voltar”. Use em e-mails, SMS ou redirecionamento após consulta.
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

Rastreamento de Encomendas
A API de rastreamento exige chave de API. Gere uma gratuitamente no dashboard e use no header Authorization.
Obter chave de API (Dashboard)

Sem chave, a requisição retorna 401 com mensagem e link para gerar uma chave gratuitamente.

Consulta de CEP
A API de CEP exige chave de API. Gere uma gratuitamente no dashboard e use no header Authorization.
Obter chave de API (Dashboard)

Sem chave, a requisição retorna 401 com mensagem e link para gerar uma chave gratuitamente.

Rate Limiting

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.