Documentação da API
APIs RESTful para rastreamento de encomendas de multiplas transportadoras (Correios, Total Express) e consulta de CEP.
historico com todos os eventos.- Chave de API — gratuita no Dashboard; obrigatória para rastreio e CEP
- CORS habilitado - Use de qualquer domínio
- Rate limiting - 10 requisições por minuto por IP
- Respostas em cache - Rápido e confiável
SEDEX, PAC e todas as modalidades. Formato: AA123456789BR
Rastreamento completo via API. Formato: TXAQ187563341tx
A API detecta automaticamente a transportadora pelo formato do código.
Início Rápido
Rastreamento de Encomendas
Requer chave de API (obtenha gratuitamente no Dashboard → Chaves de API).
GET https://teste.seurastreio.com.br/api/public/rastreio/[codigo]curl -H "Authorization: Bearer SUA_API_KEY" "https://teste.seurastreio.com.br/api/public/rastreio/BR123456789BR"
Funciona com Correios (BR123456789BR) e Total Express (TXAQ187563341tx). A transportadora é detectada automaticamente.
Consulta de CEP
Requer chave de API (obtenha gratuitamente no Dashboard → Chaves de API).
GET https://teste.seurastreio.com.br/api/public/cep/[cep]curl -H "Authorization: Bearer SUA_API_KEY" "https://teste.seurastreio.com.br/api/public/cep/02037001"
API de Rastreamento de Encomendas
Rastreie encomendas de Correios e Total Express. Por padrão a resposta inclui apenas o eventoMaisRecente. Se a chave de API for de um time com plano pago e assinatura ativa ou em trial, a resposta ganha o campo opcional historico (todos os eventos, do mais recente ao mais antigo), sem alterar os campos existentes. A API exige chave de API; gere 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. Com plano pago válido, o JSON pode incluir historico.
Parâmetros
codigoCódigo de rastreamento. Formatos aceitos: Correios (AB123456789BR) ou Total Express (TXAQ187563341tx)
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://teste.seurastreio.com.br (Dashboard → Chaves de API).",
"helpUrl": "https://teste.seurastreio.com.br/dashboard"
}Resposta de Sucesso (200) — plano gratuito
Sem o campo historico.
{
"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://teste.seurastreio.com.br/objetos/BR123456789BR",
"message": "Evento mais recente encontrado."
}Resposta de Sucesso (200) — plano pago (ex.: Correios)
Inclui historico com todos os eventos (exemplo abreviado).
{
"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
},
"historico": [
{
"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
},
{
"codigo": "OEC",
"descricao": "Objeto saiu para entrega ao destinatário",
"detalhe": "",
"data": "2024-01-15T08:00:00.000Z",
"local": "São Paulo/SP",
"destino": "Campinas/SP"
}
],
"linkDetalhesCompletos": "https://teste.seurastreio.com.br/objetos/BR123456789BR",
"message": "Evento mais recente encontrado."
}Resposta de Sucesso - Total Express (200)
{
"codigo": "TXAQ187563341tx",
"carrier": "total_express",
"carrierName": "Total Express",
"status": "found",
"success": true,
"eventoMaisRecente": {
"descricao": "Entrega Realizada",
"detalhe": "Entrega efetuada com sucesso",
"data": "2024-06-10T15:45:00.000Z",
"local": "São Paulo/SP"
},
"linkDetalhesCompletos": "https://teste.seurastreio.com.br/objetos/TXAQ187563341tx",
"message": "Evento mais recente encontrado."
}Respostas de Total Express incluem os campos carrier e carrierName para identificar a transportadora. Com plano pago válido, também é retornado historico (itens no mesmo formato de eventoMaisRecente, em geral sem codigo).
Resposta de Erro (400/404)
{
"codigo": "INVALID123",
"status": "invalid_format",
"success": false,
"message": "Formato de código de rastreamento inválido",
"linkDetalhesCompletos": "https://teste.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. Com plano pago e assinatura ativa, o corpo pode incluir o array historico. |
not_found | Encomenda não encontrada na transportadora |
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://teste.seurastreio.com.br (Dashboard → Chaves de API).",
"helpUrl": "https://teste.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://teste.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://teste.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://teste.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://teste.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://teste.seurastreio.com.br/api/public/rastreio/BR123456789BR" \ -H "Accept: application/json" \ -H "Authorization: Bearer SUA_API_KEY"
Consulta de CEP
curl -X GET "https://teste.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://teste.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. Times em plano pago com assinatura válida recebem ainda o array historico diretamente no JSON da API.
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://teste.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.