Rastreamento

Pelo código

GET /api/v1/tracking/code/{trackingCode}?refresh=false
Authorization: Bearer <accessToken>
X-Tenant-Id: <lojaId>

[
  {
    "id": "evento-1",
    "status": "IN_TRANSIT",
    "description": "Objeto em transferência",
    "location": "São Paulo/SP",
    "happenedAt": "2026-07-29T14:30:00.000Z"
  }
]

Use refresh=false no polling normal. refresh=true solicita atualização imediata ao provedor e deve ser usado com baixa frequência.

Pelo envio

GET /api/v1/tracking/shipments/{shipmentId}/tracking-events?page=1&limit=20

{
  "events": [],
  "total": 0,
  "page": 1,
  "limit": 20,
  "isDelayed": false
}

Status normalizados

Status	Significado
`POSTED`	Postado ou coletado.
`IN_TRANSIT`	Em deslocamento.
`OUT_FOR_DELIVERY`	Saiu para entrega.
`DELIVERED`	Entregue.
`DELAYED`	Atrasado.
`EXCEPTION`	Ocorrência que exige atenção.
`RETURNED`	Devolvido ou em devolução.

Uma lista vazia não prova falha: a primeira leitura física pode ainda não ter ocorrido.

Polling

comece com intervalos de 30 a 60 minutos;
aumente o intervalo quando não houver mudança;
preserve happenedAt;
aplique backoff em 429 e 5xx;
encerre o polling em DELIVERED ou RETURNED;
não exponha dados pessoais em páginas públicas.

Finalize o tratamento de erros →