Documentação da API

1. Acesse o painel em /auth e faça login.
2. Vá em Lojas → Nova loja.
3. Copie a API key e o webhook secret. Ambos são exibidos apenas uma vez.

POST /api/public/orders — upsert por external_order_id.

curl -X POST https://SEU_DOMINIO/api/public/orders \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_order_id": "PED-123",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@ex.com",
      "phone": "+5511999999999"
    },
    "tracking_code": "BR123456789BR",
    "carrier": "correios",
    "status": "posted",
    "meta": { "peso": 1.2 }
  }'

Status aceitos: pending, posted, in_transit, out_for_delivery, delivered, exception, returned, cancelled.

PATCH /api/public/orders/:external_order_id

curl -X PATCH https://SEU_DOMINIO/api/public/orders/PED-123 \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "delivered" }'

Ao mudar de status, o sistema (1) grava um evento na timeline, (2) dispara notificações para os canais com template ativo, e (3) envia webhook assinado para a URL configurada da loja.

curl https://SEU_DOMINIO/api/public/orders/PED-123 \
  -H "X-API-Key: sk_live_..."

Quando o status muda, enviamos um POST para o webhook_url configurado da loja. O corpo é assinado com HMAC-SHA256 do body usando o webhook_secret, no header X-Signature.

POST https://sua-loja.com/hooks/rastreia
Content-Type: application/json
X-Signature: <hex>
X-Webhook-Event: order.status_changed

{
  "event": "order.status_changed",
  "order_id": "PED-123",
  "status": "delivered",
  "previous_status": "out_for_delivery",
  "tracking_code": "BR123",
  "carrier": "correios",
  "occurred_at": "2026-07-04T12:34:56.000Z"
}

Verificação em Node/TS:

import { createHmac, timingSafeEqual } from "crypto";

function verify(secret: string, rawBody: string, signature: string) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Tentamos entrega 3 vezes com backoff (0s / 800ms / 2.4s). Retorne HTTP 2xx para confirmar.

// Envie o pedido a partir da sua loja em TanStack Start:
export async function notifyRastreia(order: {
  externalId: string; email: string; name: string;
  status: string; tracking?: string; carrier?: string;
}) {
  const res = await fetch("https://SEU_DOMINIO/api/public/orders", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.RASTREIA_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      external_order_id: order.externalId,
      customer: { name: order.name, email: order.email },
      tracking_code: order.tracking,
      carrier: order.carrier,
      status: order.status,
    }),
  });
  if (!res.ok) throw new Error(`Rastreia: ${res.status}`);
  return res.json();
}

• 401 — API key ausente ou inválida.
• 404 — Pedido não encontrado (GET/PATCH).
• 422 — Validação falhou (veja issues na resposta).
• 500 — Erro interno.