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.

Authorization: Bearer sr_live_sua_chave_aqui

Endpoint

GET/api/public/rastreio/{codigo}

Auth10/min por IP

Parâmetros de path

Campo	Tipo	Obrig.	Descrição
`codigo`	string	sim	Código de rastreamento. Formatos aceitos: Correios `AA123456789BR` ou Total Express `TXAQ187563341tx`.

Query params opcionais

Campo	Tipo	Obrig.	Descrição
`customerName`	string	não	Nome do cliente vinculado ao rastreio para uso em notificações WhatsApp do time (máx. 255 caracteres).
`phone`	string	não	Telefone do cliente com DDI e apenas dígitos (ex.: 5511999999999). Valor inválido retorna 400.

Formato da Resposta

Sucesso (200) — plano gratuito

{
  "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) — plano pago

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/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

Status	Significado
`200`	Resposta gerada (mesmo found, not_found ou no_events).
`400`	Código vazio (`invalid_code`) ou formato não reconhecido (`invalid_format`).
`401`	Chave de API ausente/inválida. Corpo inclui `message` e `helpUrl`.
`429`	Limite mensal de rastreios atingido. Corpo inclui `current` e `max`.
`500 / 503`	Erro 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&phone=5511999999999"

JavaScript

const res = await fetch(
  "https://seurastreio.com.br/api/public/rastreio/BR123456789BR?customerName=Maria%20Silva&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&phone=5511999999999",
    headers={"Authorization": "Bearer sr_live_sua_chave_aqui"},
)
print(r.json()["eventoMaisRecente"])

Cache: respostas found são cacheadas por 10 minutos. Erros não são cacheados. Acompanhe seu uso e cota mensal no dashboard.