Seu Rastreio

API de Rastreamento

Eventos de rastreio de Correios (AA123456789BR) e Total Express (TX...). Detecção automática pelo formato do código.

Visão Geral

Por padrão a resposta inclui apenas o eventoMaisRecente. Times com plano pago e assinatura ativa (ou em trial) recebem também historico (todos os eventos, mais recente primeiro) e previsaoEntrega em ISO. Sem alterar campos existentes.

Autenticação

Envie sua chave no header Authorization. Sem chave válida a rota responde 401 com helpUrl. Sem assinatura ativa ou em teste responde 402 com subscription_required. A página pública de rastreio do cliente continua disponível.

Authorization: Bearer sr_live_sua_chave_aqui

Endpoint

GET/api/public/rastreio/{codigo}
Auth10/min por IP

Parâmetros de path

CampoTipoObrig.Descrição
codigostringsimCódigo de rastreamento. Formatos aceitos: Correios AA123456789BR ou Total Express TXAQ187563341tx.

Query params opcionais

CampoTipoObrig.Descrição
customerNamestringnãoNome do cliente vinculado ao rastreio para avisos de WhatsApp e e-mail (máx. 255 caracteres).
customerEmailstringnãoE-mail do cliente vinculado ao rastreio (máx. 255). Usado nos avisos automáticos de e-mail quando não há pedido. Valor inválido retorna 400.
phonestringnãoTelefone do cliente com DDI e apenas dígitos (ex.: 5511999999999). Valor inválido retorna 400.

Formato da Resposta

Sucesso (200) — plano sem histórico completo

{
  "codigo": "BR123456789BR",
  "status": "found",
  "success": true,
  "eventoMaisRecente": {
    "codigo": "BDE",
    "descricao": "Objeto entregue ao destinatário",
    "detalhe": "Entrega realizada",
    "data": "2026-01-15T14:30:00.000Z",
    "local": "São Paulo/SP",
    "destino": null
  },
  "linkDetalhesCompletos": "https://seurastreio.com.br/objetos/BR123456789BR",
  "message": "Evento mais recente encontrado."
}

Sucesso (200) — assinatura ativa ou em teste

Inclui historico (array completo) e previsaoEntrega (ISO ou null).

{
  "codigo": "BR123456789BR",
  "status": "found",
  "success": true,
  "eventoMaisRecente": { "...": "..." },
  "historico": [
    {
      "codigo": "BDE",
      "descricao": "Objeto entregue ao destinatário",
      "data": "2026-01-15T14:30:00.000Z",
      "local": "São Paulo/SP"
    },
    {
      "codigo": "OEC",
      "descricao": "Objeto saiu para entrega ao destinatário",
      "data": "2026-01-15T08:00:00.000Z",
      "local": "São Paulo/SP",
      "destino": "Campinas/SP"
    }
  ],
  "previsaoEntrega": "2026-01-18T00:00:00.000Z",
  "linkDetalhesCompletos": "https://seurastreio.com.br/objetos/BR123456789BR"
}

Sucesso (200) — Total Express

Inclui carrier e carrierName para identificar a transportadora.

{
  "codigo": "TXAQ187563341tx",
  "carrier": "total_express",
  "carrierName": "Total Express",
  "status": "found",
  "success": true,
  "eventoMaisRecente": {
    "descricao": "Entrega Realizada",
    "detalhe": "Entrega efetuada com sucesso",
    "data": "2026-06-10T15:45:00.000Z",
    "local": "São Paulo/SP"
  },
  "linkDetalhesCompletos": "https://seurastreio.com.br/objetos/TXAQ187563341tx"
}

Erro (400/401/402/429)

{
  "codigo": "INVALID123",
  "status": "invalid_format",
  "success": false,
  "message": "Formato de código não reconhecido. Verifique se o código está correto.",
  "linkDetalhesCompletos": "https://seurastreio.com.br/objetos/INVALID123"
}

Códigos de Status

StatusSignificado
200Resposta gerada (mesmo found, not_found ou no_events).
400Código vazio (invalid_code), formato não reconhecido (invalid_format) ou query inválida (invalid_query — nome, e-mail ou telefone).
401Chave de API ausente/inválida. Corpo inclui message e helpUrl.
402Assinatura atrasada, cancelada ou inexistente (subscription_required). Regularize em Plano e cobrança.
429Limite mensal de rastreios atingido. Corpo inclui current e max.
500 / 503Erro temporário (Correios fora do ar, CAPTCHA, rate limit upstream).

Exemplos

cURL

curl -H "Authorization: Bearer sr_live_sua_chave_aqui" \
  "https://seurastreio.com.br/api/public/rastreio/BR123456789BR?customerName=Maria%20Silva&customerEmail=maria%40exemplo.com&phone=5511999999999"

JavaScript

const res = await fetch(
  "https://seurastreio.com.br/api/public/rastreio/BR123456789BR?customerName=Maria%20Silva&customerEmail=maria%40exemplo.com&phone=5511999999999",
  { headers: { Authorization: "Bearer sr_live_sua_chave_aqui" } },
);
const data = await res.json();
console.log(data.eventoMaisRecente);

Python

import requests

r = requests.get(
    "https://seurastreio.com.br/api/public/rastreio/BR123456789BR?customerName=Maria%20Silva&customerEmail=maria%40exemplo.com&phone=5511999999999",
    headers={"Authorization": "Bearer sr_live_sua_chave_aqui"},
)
print(r.json()["eventoMaisRecente"])