Documentação da API

APIs RESTful para rastreamento de encomendas de multiplas transportadoras (Correios, Total Express) e consulta de CEP.

Rastreamento de Encomendas
Obtenha o status mais recente de encomendas de Correios e Total Express. Times com plano pago e assinatura ativa recebem também o array historico com todos os eventos.
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
  • 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
Transportadoras Suportadas
Correios

SEDEX, PAC e todas as modalidades. Formato: AA123456789BR

Total Express

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_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. Com plano pago válido, o JSON pode incluir historico.

Parâmetros

codigo
string
obrigatório

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

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. 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_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://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

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

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://teste.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. 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

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.