# Codici evento di tracciamento

Generato in tempo reale su https://api.superlabel.ca/api/documentation/tracking-events?lang=it dalla tabella dizionario `tracking` in produzione (quali codici di stato esistono e se i clienti li vedono), dalle chiavi TrackingEvent e dalle stringhe di descrizione localizzate `tracking.*`. Sempre allineato al database di questo ambiente.

## Lato evento, non tipo ordine

Questo dizionario **non** è un elenco di tipi ordine. Lo stesso ordine può emettere eventi lato ritiro e lato consegna — ad es. una consegna con tappa di ritiro, peer-to-peer (due tratte), trasferimento multi-tratta o passaggi magazzino. Instant Deliver usa un dizionario separato (non elencato qui). Ogni evento di tracking porta un **lato** (ritiro o consegna) che sceglie descrizione e visibilità per quello stato. Lo `status_id` numerico e la `key` stabile corrispondono a `tracking_event_status_id` / `tracking_event_key` nei payload API e webhook; ramificate su questi campi (e sul lato se conta il testo), mai sul tipo ordine e mai sul testo di descrizione localizzato.

## Visibilità per il cliente (`tracking.visible`)

La pagina di tracking pubblica e l’API di tracking pubblica mostrano solo gli eventi la cui riga di dizionario ha `tracking.visible = 1`, uniti su codice di stato **e** lato evento (lo stesso lato marchiato sull’evento). Gli stati contrassegnati **No** restano nel sistema (webhook, cronologia operazioni, strumenti interni) ma sono nascosti dalla timeline rivolta al cliente. La visibilità è letta in tempo reale dalla tabella `tracking` di questa installazione.

## Eventi lato consegna

Stati usati quando un evento di tracking è sul **lato consegna** del percorso (consegna / last mile). Vale per ordini solo consegna, la tratta consegna del peer-to-peer, consegna con ritiro, multi-tratta e flussi simili — **non solo** «ordini solo consegna». **Visibile al cliente** è `tracking.visible` per quello stato su questo lato.

| status_id | key | otep | otep phase | visibile al cliente | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Sì | Le tue informazioni di spedizione sono state inviate. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Sì | La tua spedizione è stata confermata. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Sì | Il tuo pacco è in attesa di ritiro. |
| 200 | `pushed_successful` | — | — | No | Il tuo ordine è stato inviato alla pianificazione del percorso. |
| 201 | `pushed_failed` | — | — | No | Non è stato possibile inviare il tuo ordine alla pianificazione del percorso. Verrà ritentato o ripianificato. |
| 300 | `received` | `received` | `inbound` | Sì | Il tuo pacco è arrivato sano e salvo a {warehouse_name}. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Sì | Il tuo pacco è stato ritirato e consegnato a {warehouse_name}. |
| 400 | `planned` | `in_transit` | `transit` | No | Il tuo pacco è stato caricato ed è pronto per la consegna. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | No | Il tuo programma di consegna è in fase di riprogrammazione. Attendi una notifica. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | No | Lo stato della tua consegna verrà aggiornato a breve. Attendi un momento. |
| 430 | `in_transit` | `in_transit` | `transit` | Sì | Il tuo pacco è in transito. |
| 431 | `on_hold` | `in_transit` | `transit` | Sì | Il tuo pacco è temporaneamente in attesa. Ti aggiorneremo a breve. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Sì | Il tuo pacco è in fase di sdoganamento. |
| 433 | `loaded` | `package_outbound` | `transit` | Sì | Il tuo pacco è stato caricato e partirà a breve. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Sì | Il ritiro del tuo pacco è temporaneamente in attesa. Ti aggiorneremo a breve. |
| 435 | `facility_received` | `in_transit` | `transit` | Sì | Il tuo pacco è stato ricevuto dal centro logistico. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Sì | Il tuo pacco è arrivato in un centro logistico. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Sì | Il tuo pacco è in viaggio per la consegna. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Sì | Il tuo pacco ti aspetta in un armadietto automatico. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Sì | Il tuo pacco è stato ritirato dall'armadietto automatico. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Sì | Il tuo pacco non è stato ritirato entro la scadenza ed è ancora nell'armadietto automatico. |
| 473 | `device_removed` | `received` | `inbound` | Sì | Il tuo pacco è stato prelevato dall'armadietto automatico dal personale. |
| 500 | `deliver_success` | `delivered` | `delivered` | Sì | Il tuo pacco è stato consegnato con successo. Grazie! |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Sì | Sfortunatamente, il tuo pacco non ha potuto essere consegnato. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Sì | Sfortunatamente, il tuo pacco non ha potuto essere consegnato. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Sì | Si è verificato un problema durante la consegna. Contatta il nostro servizio clienti. |
| 504 | `partial_deliver_success` | — | — | Sì | Questo collo è stato consegnato. Gli altri colli della sua spedizione sono ancora in viaggio. |
| 510 | `pickuped` | `picked_up` | `pickup` | Sì | Il pacco è stato ritirato con successo dal nostro autista. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Sì | Il tuo pacco è partito da {warehouse_name}. |

## Eventi lato ritiro

Stati usati quando un evento di tracking è sul **lato ritiro** del percorso (tratta di raccolta). Vale per ordini solo ritiro, la tratta ritiro del peer-to-peer, consegna con ritiro, multi-tratta e flussi simili — **non solo** «ordini solo ritiro». **Visibile al cliente** è `tracking.visible` per quello stato su questo lato.

| status_id | key | otep | otep phase | visibile al cliente | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Sì | La tua richiesta di ritiro è stata inviata con successo. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Sì | La tua richiesta di ritiro è stata confermata. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Sì | Il tuo pacco è in attesa di ritiro. |
| 200 | `pushed_successful` | — | — | No | Il tuo ordine di ritiro è stato inviato alla pianificazione del percorso. |
| 201 | `pushed_failed` | — | — | No | Non è stato possibile inviare il tuo ordine di ritiro alla pianificazione del percorso. Verrà ritentato o ripianificato. |
| 300 | `received` | `received` | `inbound` | Sì | Il tuo pacco è stato immagazzinato con successo. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Sì | Order a-scan |
| 400 | `planned` | `in_transit` | `transit` | No | Il tuo pacco è attualmente in elaborazione. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | No | Il tuo programma di ritiro è in fase di riprogrammazione. Attendi una notifica. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | No | Lo stato del tuo ritiro verrà aggiornato a breve. Attendi un momento. |
| 430 | `in_transit` | `in_transit` | `transit` | Sì | Il tuo pacco è in transito. |
| 431 | `on_hold` | `in_transit` | `transit` | Sì | Il tuo pacco è temporaneamente in attesa. Ti aggiorneremo a breve. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Sì | Il tuo pacco è in fase di sdoganamento. |
| 433 | `loaded` | `package_outbound` | `transit` | Sì | Il tuo pacco è stato caricato e partirà a breve. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Sì | Il ritiro del tuo pacco è temporaneamente in attesa. Ti aggiorneremo a breve. |
| 435 | `facility_received` | `in_transit` | `transit` | Sì | Il tuo pacco è stato ricevuto dal centro logistico. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Sì | Il tuo pacco è arrivato in un centro logistico. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Sì | L'autista è in viaggio per il ritiro. Prepara il tuo pacco. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Sì | Il tuo pacco ti aspetta in un armadietto automatico. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Sì | Il tuo pacco è stato ritirato dall'armadietto automatico. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Sì | Il tuo pacco non è stato ritirato entro la scadenza ed è ancora nell'armadietto automatico. |
| 473 | `device_removed` | `received` | `inbound` | Sì | Il tuo pacco è stato prelevato dall'armadietto automatico dal personale. |
| 500 | `deliver_success` | `delivered` | `delivered` | Sì | Il tuo pacco è stato ritirato con successo. |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Sì | Il tuo ritiro è stato riprogrammato. Ti informeremo presto sulla nuova data. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Sì | Il tuo ritiro è stato riprogrammato. Ti informeremo presto sulla nuova data. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Sì | Si è verificato un problema con il tuo pacco. Contatta il nostro servizio clienti. |
| 504 | `partial_deliver_success` | — | — | Sì | Questo collo è stato ritirato. Gli altri colli della sua spedizione saranno ritirati a breve. |
| 510 | `pickuped` | `picked_up` | `pickup` | Sì | Il tuo pacco è stato ritirato con successo. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Sì | Il tuo pacco è partito da {warehouse_name}. |

Le colonne **otep** / **otep phase** sono generate in tempo reale da `OTEPStatusInput::FROM_TRACKING_EVENT` e `PHASES` — lo stesso ponte che l’API pubblica di tracking scrive come `otep_status` su ogni evento. Un trattino (—) indica che non c’è un codice OTEP nel profilo parcel (es. push di routing 200/201); l’evento viene comunque memorizzato e può restare visibile al cliente se `visible = 1`.

## Crea la tua pagina di tracking

Usa l’**API pubblica di tracking** per una pagina con il tuo brand su sito o app — senza login né token. Lo stesso endpoint alimenta la pagina integrata e l’operazione GraphQL `trackingPublic`. Abbinalo al dizionario stati di questa pagina e ai flussi sotto.

### 1. Chiama l’endpoint pubblico

Un GET per numero di tracking. La ricerca copre numeri Superroute, esterni e alcuni terzi senza id provider.

```
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. Scegli la lingua delle descrizioni

I testi `description` seguono la locale della richiesta tramite `Accept-Language`. Invia un codice progetto (`en`, `chs`, `it`, …) o un alias come `zh-CN`. Se manca, si usa la locale predefinita.

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

### 3. Campi di risposta da renderizzare

Viene restituita solo la superficie pubblica — le indirizzi completi mittente/destinatario **non** sono inclusi (solo sull’endpoint interno autenticato).

| 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. Flusso UI consigliato

1. Raccogli il numero dal visitatore e chiama il GET pubblico (opzionalmente con `Accept-Language`).
2. Se `result` è false o HTTP è 404, mostra non trovato e fermati.
3. Usa `data[0]` (evento più recente) per lo stato in evidenza: testo da `description`; icone/progresso da `tracking_event_status_id` o `otep_status`.
4. Renderizza l’intera lista `data` come timeline (già dal più recente). Non inventare passi mancanti.
5. Se `proofs` non è vuoto e l’ultimo stato è di successo (tipicamente 500 o 510), offri “vedi prova”; `signed_url` per link a scadenza, `full_url` per il path permanente.

### 5. Indicatori di avanzamento

**Non** codificare a fisso una sola catena per ogni collo. Usa il dizionario e i flussi di questa pagina. Ramifica su `otep_status` o `tracking_event_status_id`; l’evento più recente è autorevole.

### 6. Prova di consegna

`proofs[]` porta metadati foto/firma quando disponibili. La tua pagina può ancora richiedere il CAP prima di mostrarli; l’API restituisce un `postcode` normalizzato. Non mettere indirizzi strada completi su una pagina totalmente pubblica.

### 7. Superfici pubbliche correlate

Scegli quella adatta al tuo stack. Tutte sono pubbliche (senza token) salvo diversa indicazione nella documentazione 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. Esempi minimi

```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
}
```

## Flussi di tracking comuni

Sono **sequenze tipiche**, non una macchina a stati rigida. Le timeline reali saltano passi, inseriscono eccezioni o intercalano eventi lato ritiro e consegna sullo stesso ordine. I numeri sono `tracking_event_status_id`; la timeline pubblica mostra solo righe con `tracking.visible = 1`. Ramificate su `status_id` / `key` e prendete l’evento più recente (id più alto) come autorevole.

### Magazzino → consegna last-mile

Percorso flotta propria più comune: ordine creato, pacco ricevuto in struttura, autista in consegna, poi successo o eccezione. Codici di pianificazione 400/401/402 spesso esistono ma **non** sono visibili al 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
```

### Ritiro / tratta solo ritiro

L’autista esce a ritirare e registra successo (POD possibile) o eccezione di ritiro. Gli ordini solo ritiro restano lato ritiro; i percorsi a due tratte passano al lato consegna dopo 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
```

### Viaggi a due tratte (prima ritiro, poi consegna)

Quando un viaggio ha sia ritiro sia consegna — consegna con ritiro, peer-to-peer, molti multi-tratta. La timeline di solito mostra prima i traguardi **lato ritiro** (460 → 510), poi **lato consegna** (450 → 500). Il lato dell’evento sceglie la descrizione, non il tipo ordine.

```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"]
```

### Adempimento terzi / corriere

La prenotazione del corriere può emettere 110/120; la policy di prodotto li tiene **nascosti** sulla timeline pubblica. I traguardi visibili condivisi seguono magazzino + last mile (300/301 → 800 → 450 → 500). La cancellazione terminale usa 403 (non 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 (dispatch a task)

Dizionario proprio (non nelle tabelle sopra). Percorso felice: inviato → corriere assegnato → verso ritiro → ritirato → in consegna → consegnato. 411/412 possono ciclare prima della partenza; 501 dopo un tentativo fallito.

```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"]
```

### Codici di eccezione e terminali (mappa rapida)

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

### Regole empiriche per integratori

1. Ancore del percorso felice: **100** creato, **300/301** in struttura, **450** in consegna, **500** consegnato; ritiro **460** e **510**.
2. Non assumete una catena fissa completa: scan opzionali, hop terzi (800) e cambi di lato sono normali.
3. Le eccezioni (501–503, 512–513, 600, 700) possono seguire un codice «in corso…»; l’ordine può rientrare in 450/460 dopo ripianificazione.
4. Ignorate le righe non visibili sulla pagina pubblica; webhook e strumenti interni possono riceverle. Preferite sempre l’id evento più recente per le correzioni.

Segnaposto come `{warehouse_name}` vengono sostituiti a runtime con il nome reale del magazzino o della località. Nuove righe e cambi di visibilità arrivano via migrazioni; la pagina rilegge la tabella a ogni richiesta e non può diventare obsoleta rispetto a questo ambiente.