# Códigos de eventos de rastreamento

Gerado em tempo real em https://api.superlabel.ca/api/documentation/tracking-events?lang=pt a partir da tabela de dicionário `tracking` implantada (quais códigos de estado existem e se os clientes os veem), das chaves TrackingEvent e das strings de descrição localizadas `tracking.*`. Sempre atualizado com a base de dados deste ambiente.

## Lado do evento, não tipo de pedido

Este dicionário **não** é uma lista de tipos de pedido. O mesmo pedido pode emitir eventos do lado recolha e do lado entrega — por exemplo uma entrega com paragem de recolha, peer-to-peer (dois troços), transferência multi-troço ou passagem de armazém. Instant Deliver usa um dicionário separado (não listado aqui). Cada evento de rastreamento leva um **lado** (recolha ou entrega) que escolhe a descrição e a visibilidade desse estado. O `status_id` numérico e a `key` estável correspondem a `tracking_event_status_id` / `tracking_event_key` nos payloads de API e webhook; ramifique nesses campos (e no lado se o texto importa), nunca no tipo de pedido nem no texto localizado da descrição.

## Visibilidade para o cliente (`tracking.visible`)

A página pública de rastreamento e a API pública de rastreamento só mostram eventos cuja linha de dicionário tem `tracking.visible = 1`, ligados por código de estado **e** lado do evento (o mesmo lado marcado no evento). Estados marcados **Não** ainda existem no sistema (webhooks, histórico de operações, ferramentas internas) mas ficam ocultos da linha do tempo voltada ao cliente. A visibilidade é lida ao vivo da tabela `tracking` desta implantação.

## Eventos do lado entrega

Estados usados quando um evento de rastreamento está no **lado entrega** da viagem (entrega / última milha). Aplica-se a pedidos só entrega, ao troço de entrega do peer-to-peer, entrega com recolha, multi-troço e fluxos semelhantes — **não só** a «pedidos só entrega». **Visível ao cliente** é `tracking.visible` desse estado neste lado.

| status_id | key | otep | otep phase | visível ao cliente | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Sim | Suas informações de envio foram enviadas. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Sim | Seu envio foi confirmado. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Sim | Seu pacote aguarda coleta. |
| 200 | `pushed_successful` | — | — | Não | O seu pedido foi enviado para o planeamento de rotas. |
| 201 | `pushed_failed` | — | — | Não | Não foi possível enviar o seu pedido para o planeamento de rotas. Será repetido ou replanificado. |
| 300 | `received` | `received` | `inbound` | Sim | Seu pacote chegou em segurança em {warehouse_name}. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Sim | Seu pacote foi coletado e entregue em {warehouse_name}. |
| 400 | `planned` | `in_transit` | `transit` | Não | Seu pacote foi carregado e está pronto para entrega. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | Não | Sua programação de entrega está sendo reagendada. Aguarde uma notificação. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | Não | O status da sua entrega será atualizado em breve. Aguarde um momento. |
| 430 | `in_transit` | `in_transit` | `transit` | Sim | O seu pacote está em trânsito. |
| 431 | `on_hold` | `in_transit` | `transit` | Sim | O seu pacote está temporariamente retido. Iremos informá-lo em breve. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Sim | O seu pacote está em desalfandegamento. |
| 433 | `loaded` | `package_outbound` | `transit` | Sim | O seu pacote foi carregado e partirá em breve. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Sim | A recolha do seu pacote está temporariamente suspensa. Iremos informá-lo em breve. |
| 435 | `facility_received` | `in_transit` | `transit` | Sim | O seu pacote foi recebido pelo centro logístico. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Sim | O seu pacote chegou a um centro logístico. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Sim | Seu pacote está a caminho para entrega. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Sim | Seu pacote está esperando por você em um armário automático. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Sim | Seu pacote foi retirado do armário automático. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Sim | Seu pacote não foi retirado dentro do prazo e continua no armário automático. |
| 473 | `device_removed` | `received` | `inbound` | Sim | Seu pacote foi retirado do armário automático pela equipe. |
| 500 | `deliver_success` | `delivered` | `delivered` | Sim | Seu pacote foi entregue com sucesso. Obrigado! |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Sim | Infelizmente, seu pacote não pôde ser entregue. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Sim | Infelizmente, seu pacote não pôde ser entregue. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Sim | Houve um problema com a entrega. Entre em contato com nosso atendimento ao cliente. |
| 504 | `partial_deliver_success` | — | — | Sim | Este volume foi entregue. Os restantes volumes da sua encomenda estão a caminho. |
| 510 | `pickuped` | `picked_up` | `pickup` | Sim | O pacote foi coletado com sucesso pelo nosso motorista. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Sim | Seu pacote saiu de {warehouse_name}. |

## Eventos do lado recolha

Estados usados quando um evento de rastreamento está no **lado recolha** da viagem (troço de recolha). Aplica-se a pedidos só recolha, ao troço de recolha do peer-to-peer, entrega com recolha, multi-troço e fluxos semelhantes — **não só** a «pedidos só recolha». **Visível ao cliente** é `tracking.visible` desse estado neste lado.

| status_id | key | otep | otep phase | visível ao cliente | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Sim | Sua solicitação de coleta foi enviada com sucesso. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Sim | Sua solicitação de coleta foi confirmada. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Sim | Seu pacote aguarda coleta. |
| 200 | `pushed_successful` | — | — | Não | O seu pedido de recolha foi enviado para o planeamento de rotas. |
| 201 | `pushed_failed` | — | — | Não | Não foi possível enviar o seu pedido de recolha para o planeamento de rotas. Será repetido ou replanificado. |
| 300 | `received` | `received` | `inbound` | Sim | Seu pacote foi armazenado com sucesso. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Sim | Order a-scan |
| 400 | `planned` | `in_transit` | `transit` | Não | Seu pacote está sendo processado no momento. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | Não | Sua programação de coleta está sendo reagendada. Aguarde uma notificação. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | Não | O status da sua coleta será atualizado em breve. Aguarde um momento. |
| 430 | `in_transit` | `in_transit` | `transit` | Sim | O seu pacote está em trânsito. |
| 431 | `on_hold` | `in_transit` | `transit` | Sim | O seu pacote está temporariamente retido. Iremos informá-lo em breve. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Sim | O seu pacote está em desalfandegamento. |
| 433 | `loaded` | `package_outbound` | `transit` | Sim | O seu pacote foi carregado e partirá em breve. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Sim | A recolha do seu pacote está temporariamente suspensa. Iremos informá-lo em breve. |
| 435 | `facility_received` | `in_transit` | `transit` | Sim | O seu pacote foi recebido pelo centro logístico. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Sim | O seu pacote chegou a um centro logístico. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Sim | O motorista está a caminho para a coleta. Prepare seu pacote. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Sim | Seu pacote está esperando por você em um armário automático. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Sim | Seu pacote foi retirado do armário automático. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Sim | Seu pacote não foi retirado dentro do prazo e continua no armário automático. |
| 473 | `device_removed` | `received` | `inbound` | Sim | Seu pacote foi retirado do armário automático pela equipe. |
| 500 | `deliver_success` | `delivered` | `delivered` | Sim | Seu pacote foi coletado com sucesso. |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Sim | Sua coleta foi reagendada. Informaremos a nova data em breve. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Sim | Sua coleta foi reagendada. Informaremos a nova data em breve. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Sim | Houve um problema com seu pacote. Entre em contato com nosso atendimento ao cliente. |
| 504 | `partial_deliver_success` | — | — | Sim | Este volume foi recolhido. Os restantes volumes da sua encomenda serão recolhidos em breve. |
| 510 | `pickuped` | `picked_up` | `pickup` | Sim | Seu pacote foi coletado com sucesso. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Sim | Seu pacote saiu de {warehouse_name}. |

As colunas **otep** / **otep phase** são geradas em tempo real a partir de `OTEPStatusInput::FROM_TRACKING_EVENT` e `PHASES` — a mesma ponte que a API pública de rastreamento grava como `otep_status` em cada evento. Um travessão (—) significa que não há código OTEP no perfil parcel (ex. push de routing 200/201); o evento é guardado na mesma e pode ser visível ao cliente se `visible = 1`.

## Crie a sua própria página de rastreamento

Use a **API pública de rastreamento** para uma página com a sua marca no site ou app — sem login nem token. O mesmo endpoint alimenta a página integrada e a operação GraphQL `trackingPublic`. Combine com o dicionário de estados desta página e os fluxos abaixo.

### 1. Chamar o endpoint público

Um GET por número de rastreamento. A pesquisa cobre números Superroute, externos e alguns de terceiros sem id de fornecedor.

```
GET https://api.superlabel.ca/api/v1/tracking/{tracking_number}
```

- No authentication — public, rate-limited with the rest of the API.
- Path parameter: the Superroute tracking number, external tracking number, or (when applicable) third-party tracking number without a third-party provider id.
- HTTP **200** with `"result": true` when found; **404** with `"result": false` when not found or the order is cancelled.

### 2. Escolher o idioma das descrições

Os textos `description` seguem a locale do pedido via `Accept-Language`. Envie um código do projeto (`en`, `chs`, `pt`, …) ou um alias como `zh-CN`. Sem cabeçalho, usa-se o idioma predefinido.

```
Accept-Language: chs
Accept-Language: zh-CN
Accept-Language: de
```

### 3. Campos de resposta a apresentar

Só é devolvida a superfície pública — moradas completas de remetente/destinatário **não** estão incluídas (apenas no endpoint interno autenticado).

| field | meaning |
|---|---|
| `result` | `true` when a live order was found |
| `data` | Event timeline (newest first) |
| `data[].tracking_event_status_id` | Numeric code — match the dictionary on this page |
| `data[].otep_status` | Open tracking code when mapped (same bridge as the **otep** column) |
| `data[].description` | Localized customer text for this event |
| `data[].updated_at` / `timestamp` / `updated_at_localized` | When it happened (UTC string, unix, local clock) |
| `data[].location_*` / `operation_location` | Where it happened, when known |
| `data[].reason` | Public return/failure reason text when present |
| `deliveried` / `returntosender` / `rejectedbyrecipient` | Coarse final-state flags for header chips |
| `postcode` | Normalized delivery postcode (for POD gate on your side if you need it) |
| `proofs[]` | Signature / photo files (`url`, `full_url`, `signed_url`, `type`, `file_id`) |
| `is_third_party_tracking` / `third_party_info` | Present when a label/carrier timeline was merged in |

### 4. Fluxo de UI recomendado

1. Recolha o número do visitante e chame o GET público (opcionalmente com `Accept-Language`).
2. Se `result` for false ou HTTP for 404, mostre não encontrado e pare.
3. Use `data[0]` (evento mais recente) para o estado de destaque: texto com `description`; ícones/progresso com `tracking_event_status_id` ou `otep_status`.
4. Renderize a lista completa `data` como linha do tempo (já do mais recente). Não invente passos em falta.
5. Se `proofs` não estiver vazio e o último estado for de sucesso (tipicamente 500 ou 510), ofereça ver a prova; `signed_url` para ligações com validade, `full_url` para o caminho permanente.

### 5. Indicadores de progresso

**Não** codifique uma única cadeia para todos os envios. Use o dicionário e os fluxos desta página. Ramifique por `otep_status` ou `tracking_event_status_id`; o evento mais recente é autoritativo.

### 6. Prova de entrega

`proofs[]` transporta metadados de foto/assinatura quando existem. A sua página pode ainda exigir o código postal antes de mostrar; a API devolve um `postcode` normalizado. Não coloque moradas de rua completas numa página totalmente pública.

### 7. Superfícies públicas relacionadas

Escolha a que se adequa à sua stack. Todas são públicas (sem token) salvo indicação em contrário na documentação da API.

| surface | when to use |
|---|---|
| `GET https://api.superlabel.ca/api/v1/tracking/{tracking_number}` | Default branded tracking page (this guide) |
| GraphQL `trackingPublic(trackingNumber: …)` at `https://api.superlabel.ca/graphql` | Same payload when your stack is GraphQL-first |
| `GET https://api.superlabel.ca/api/v1/otep/trackings/{tracking_number}` | Vendor-neutral OTEP timeline / EPCIS / ONE Record / UN-CEFACT projections |

### 8. Exemplos mínimos

```bash
curl -sS -H "Accept-Language: en" \
  "https://api.superlabel.ca/api/v1/tracking/SR1234567890"
```

```javascript
const res = await fetch(`https://api.superlabel.ca/api/v1/tracking/${encodeURIComponent(tn)}`, {
  headers: { "Accept-Language": "chs" },
});
const body = await res.json();
if (!body.result) {
  // show "not found"
} else {
  const events = body.data || [];          // newest first
  const latest = events[0];
  const proofs = body.proofs || [];
  // render latest.description, map latest.tracking_event_status_id or otep_status for the stepper
}
```

## Padrões comuns de fluxo de rastreamento

São **sequências típicas**, não uma máquina de estados rígida. Linhas do tempo reais saltam passos, inserem exceções ou intercalam eventos de recolha e entrega no mesmo pedido. Os números são `tracking_event_status_id`; a linha pública só mostra linhas com `tracking.visible = 1`. Ramifique em `status_id` / `key` e trate o evento mais recente (id mais alto) como autoritativo.

### Armazém → entrega last-mile

Caminho próprio mais comum: pedido criado, pacote recebido na instalação, motorista em entrega, depois sucesso ou exceção. Códigos de planeamento 400/401/402 muitas vezes existem mas **não** são visíveis ao cliente.

```mermaid
flowchart LR
  s100["100 information_submitted"] --> s300["300 received / 301 arrival_scan"]
  s300 --> s450["450 start_delivery"]
  s450 --> s500["500 deliver_success"]
  s450 --> s501["501 need_rescheduled"]
  s450 --> s502["502 redelivered_later"]
  s450 --> s503["503 not_delivered"]
  s450 --> s700["700 rejected_by_recipient"]
  s501 --> s450
  s502 --> s450
```

### Recolha / troço só recolha

O motorista sai a recolher e regista sucesso (POD possível) ou exceção de recolha. Pedidos só recolha ficam no lado recolha; fluxos de dois troços passam ao lado entrega após 510.

```mermaid
flowchart LR
  s100["100 information_submitted"] --> s460["460 start_pickup"]
  s460 --> s510["510 pickuped"]
  s460 --> s512["512 repickup_later"]
  s460 --> s513["513 not_pickuped"]
  s512 --> s460
```

### Viagens de dois troços (recolher e depois entregar)

Quando uma viagem tem recolha e entrega — entrega com recolha, peer-to-peer, muitos multi-troço. A linha do tempo costuma mostrar marcos do **lado recolha** primeiro (460 → 510), depois do **lado entrega** (450 → 500). O lado do evento escolhe a descrição, não o tipo de pedido.

```mermaid
flowchart LR
  s100["100 information_submitted"] --> pickup["Pickup-side: 460 → 510"]
  pickup --> delivery["Delivery-side: 450 → 500"]
  pickup --> pFail["Pickup exception: 512 / 513"]
  delivery --> dFail["Delivery exception: 501 / 502 / 503 / 700"]
```

### Cumprimento de terceiros / transportadora

A reserva da transportadora pode emitir 110/120; a política de produto mantém-nos **ocultos** na linha pública. Marcos visíveis partilhados seguem armazém + last mile (300/301 → 800 → 450 → 500). Cancelamento terminal usa 403 (não 402).

```mermaid
flowchart LR
  s100["100 information_submitted"] --> s110["110 / 120 hidden on public timeline"]
  s110 --> s300["300 / 301 warehouse"]
  s300 --> s800["800 package_outbound"]
  s800 --> s450["450 start_delivery"]
  s450 --> s500["500 deliver_success"]
  s450 --> sFail["501 / 503 / 600 / 700"]
```

### Instant Deliver (despacho por tarefas)

Dicionário próprio (não nas tabelas acima). Caminho feliz: submetido → estafeta atribuído → a caminho da recolha → recolhido → em entrega → entregue. 411/412 podem ciclar antes de arrancar; 501 após tentativa falhada.

```mermaid
flowchart LR
  s100["100 information_submitted"] --> s410["410 rider_assigned"]
  s410 --> s411["411 reassigned optional"]
  s410 --> s412["412 assignment_cancelled"]
  s412 --> s410
  s410 --> s460["460 start_pickup"]
  s460 --> s510["510 pickuped"]
  s510 --> s450["450 start_delivery"]
  s450 --> s500["500 deliver_success"]
  s450 --> s501["501 need_rescheduled"]
```

### Códigos de exceção e terminais (mapa rápido)

| status_id | key | typical meaning |\n|---|---|---|\n| 501 | need_rescheduled | Delivery failed; needs a new plan |\n| 502 | redelivered_later | Retry on the same route / later attempt |\n| 503 | not_delivered | Delivery problem / failed attempt |\n| 512 | repickup_later | Pickup failed; try again later |\n| 513 | not_pickuped | Pickup problem |\n| 600 | return_to_sender | Returned to shipper |\n| 700 | rejected_by_recipient | Recipient refused |\n| 403 | cancelled | Terminal cancel (distinct from 402 route cancel) |\n| 402 | route_cancelled | Route cancelled / re-plan (usually not customer-visible) |

### Regras práticas para integradores

1. Âncoras do caminho feliz: **100** criado, **300/301** na instalação, **450** em entrega, **500** entregue; recolha **460** e **510**.
2. Não assuma uma cadeia completa fixa — scans opcionais, saltos de terceiros (800) e mudanças de lado são normais.
3. Exceções (501–503, 512–513, 600, 700) podem seguir um código «em curso…»; o pedido pode voltar a 450/460 após replanear.
4. Ignore linhas não visíveis na página pública; webhooks e ferramentas internas ainda as podem receber. Prefira sempre o id de evento mais recente ao corrigir.

Marcadores como `{warehouse_name}` são substituídos em tempo de execução pelo nome real do armazém ou local. Novas linhas e alterações de visibilidade chegam por migrações; a página relê a tabela a cada pedido e não fica obsoleta em relação a este ambiente.