# Tracking-Ereigniscodes

Live erzeugt unter https://api.superlabel.ca/api/documentation/tracking-events?lang=de aus der bereitgestellten `tracking`-Wörterbuchtabelle (welche Statuscodes existieren und ob Kunden sie sehen), den TrackingEvent-Schlüsseln und den lokalisierten `tracking.*`-Beschreibungstexten. Immer aktuell mit der Datenbank dieser Umgebung.

## Ereignisseite, nicht Auftragstyp

Dieses Wörterbuch ist **keine** Auftragstyp-Liste. Derselbe Auftrag kann sowohl abholseitige als auch lieferseitige Ereignisse erzeugen — z. B. eine Lieferung mit Abholstopp, Peer-to-Peer (zwei Abschnitte), Multi-Leg-Transfer oder Lagerübergabe. Instant Deliver nutzt ein separates Wörterbuch (hier nicht aufgeführt). Jedes Tracking-Ereignis trägt eine **Seite** (Abhol- oder Lieferseite), die Beschreibung und Sichtbarkeit für diesen Status wählt. Die numerische `status_id` und stabile `key` entsprechen `tracking_event_status_id` / `tracking_event_key` in API- und Webhook-Payloads; verzweigen Sie über diese Felder (und bei Bedarf die Seite), nie über den Auftragstyp und nie über den lokalisierten Beschreibungstext.

## Kundensichtbarkeit (`tracking.visible`)

Die öffentliche Tracking-Seite und die öffentliche Tracking-API zeigen nur Ereignisse, deren Wörterbuchzeile `tracking.visible = 1` hat, verknüpft über Statuscode **und** Ereignisseite (dieselbe Seite wie auf dem Tracking-Ereignis). Mit **Nein** markierte Status existieren weiterhin im System (Webhooks, Betriebsverlauf, interne Tools), sind aber aus der kundenbezogenen Zeitleiste ausgeblendet. Die Sichtbarkeit wird live aus der `tracking`-Tabelle dieser Installation gelesen.

## Lieferseitige Ereignisse

Status, wenn ein Tracking-Ereignis auf der **Lieferseite** der Reise liegt (Zustellung / Last-Mile). Gilt für reine Lieferaufträge, den Lieferabschnitt von Peer-to-Peer, Lieferung mit Abholung, Multi-Leg und ähnliche Abläufe — **nicht nur** „reine Lieferaufträge“. **Kundensichtbar** ist `tracking.visible` für diesen Status auf dieser Seite.

| status_id | key | otep | otep phase | kundensichtbar | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Ja | Ihre Sendungsinformationen wurden übermittelt. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Ja | Ihre Sendung wurde bestätigt. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Ja | Ihr Paket wartet auf die Abholung. |
| 200 | `pushed_successful` | — | — | Nein | Ihr Auftrag wurde zur Routenplanung übermittelt. |
| 201 | `pushed_failed` | — | — | Nein | Ihr Auftrag konnte nicht zur Routenplanung übermittelt werden. Er wird erneut versucht oder neu geplant. |
| 300 | `received` | `received` | `inbound` | Ja | Ihr Paket ist sicher im {warehouse_name} angekommen. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Ja | Ihr Paket wurde abgeholt und an {warehouse_name} geliefert. |
| 400 | `planned` | `in_transit` | `transit` | Nein | Ihr Paket wurde verladen und ist bereit zur Zustellung. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | Nein | Ihr Zustellplan wird neu geplant. Bitte warten Sie auf eine Benachrichtigung. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | Nein | Ihr Lieferstatus wird in Kürze aktualisiert. Bitte warten Sie einen Moment. |
| 430 | `in_transit` | `in_transit` | `transit` | Ja | Ihr Paket ist unterwegs. |
| 431 | `on_hold` | `in_transit` | `transit` | Ja | Ihr Paket ist vorübergehend angehalten. Wir informieren Sie in Kürze. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Ja | Ihr Paket befindet sich in der Zollabfertigung. |
| 433 | `loaded` | `package_outbound` | `transit` | Ja | Ihr Paket wurde verladen und wird in Kürze abfahren. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Ja | Die Abholung Ihres Pakets ist vorübergehend angehalten. Wir informieren Sie in Kürze. |
| 435 | `facility_received` | `in_transit` | `transit` | Ja | Ihr Paket wurde vom Logistikzentrum entgegengenommen. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Ja | Ihr Paket ist in einem Logistikzentrum angekommen. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Ja | Ihr Paket ist auf dem Weg zur Zustellung. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Ja | Ihr Paket wartet in einem Paketautomaten auf Sie. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Ja | Ihr Paket wurde aus dem Paketautomaten abgeholt. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Ja | Ihr Paket wurde nicht rechtzeitig abgeholt und befindet sich noch im Paketautomaten. |
| 473 | `device_removed` | `received` | `inbound` | Ja | Ihr Paket wurde vom Personal aus dem Paketautomaten entnommen. |
| 500 | `deliver_success` | `delivered` | `delivered` | Ja | Ihr Paket wurde erfolgreich zugestellt. Vielen Dank! |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Ja | Leider konnte Ihr Paket nicht zugestellt werden. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Ja | Leider konnte Ihr Paket nicht zugestellt werden. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Ja | Es gab ein Problem bei der Lieferung. Bitte kontaktieren Sie unseren Kundenservice. |
| 504 | `partial_deliver_success` | — | — | Ja | Dieses Paket wurde zugestellt. Die übrigen Pakete Ihrer Sendung sind noch unterwegs. |
| 510 | `pickuped` | `picked_up` | `pickup` | Ja | Das Paket wurde erfolgreich von unserem Fahrer abgeholt. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Ja | Ihr Paket hat {warehouse_name} verlassen. |

## Abholseitige Ereignisse

Status, wenn ein Tracking-Ereignis auf der **Abholseite** der Reise liegt (Abholabschnitt). Gilt für reine Abholaufträge, den Abholabschnitt von Peer-to-Peer, Lieferung mit Abholung, Multi-Leg und ähnliche Abläufe — **nicht nur** „reine Abholaufträge“. **Kundensichtbar** ist `tracking.visible` für diesen Status auf dieser Seite.

| status_id | key | otep | otep phase | kundensichtbar | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Ja | Ihre Abholanfrage wurde erfolgreich übermittelt. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Ja | Ihre Abholanfrage wurde bestätigt. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Ja | Ihr Paket wartet auf die Abholung. |
| 200 | `pushed_successful` | — | — | Nein | Ihr Abholauftrag wurde zur Routenplanung übermittelt. |
| 201 | `pushed_failed` | — | — | Nein | Ihr Abholauftrag konnte nicht zur Routenplanung übermittelt werden. Er wird erneut versucht oder neu geplant. |
| 300 | `received` | `received` | `inbound` | Ja | Ihr Paket wurde erfolgreich eingelagert. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Ja | Order a-scan |
| 400 | `planned` | `in_transit` | `transit` | Nein | Ihr Paket wird derzeit bearbeitet. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | Nein | Ihr Abholplan wird neu geplant. Bitte warten Sie auf eine Benachrichtigung. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | Nein | Ihr Abholstatus wird in Kürze aktualisiert. Bitte warten Sie einen Moment. |
| 430 | `in_transit` | `in_transit` | `transit` | Ja | Ihr Paket ist unterwegs. |
| 431 | `on_hold` | `in_transit` | `transit` | Ja | Ihr Paket ist vorübergehend angehalten. Wir informieren Sie in Kürze. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Ja | Ihr Paket befindet sich in der Zollabfertigung. |
| 433 | `loaded` | `package_outbound` | `transit` | Ja | Ihr Paket wurde verladen und wird in Kürze abfahren. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Ja | Die Abholung Ihres Pakets ist vorübergehend angehalten. Wir informieren Sie in Kürze. |
| 435 | `facility_received` | `in_transit` | `transit` | Ja | Ihr Paket wurde vom Logistikzentrum entgegengenommen. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Ja | Ihr Paket ist in einem Logistikzentrum angekommen. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Ja | Der Fahrer ist auf dem Weg zur Abholung. Bitte bereiten Sie Ihr Paket vor. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Ja | Ihr Paket wartet in einem Paketautomaten auf Sie. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Ja | Ihr Paket wurde aus dem Paketautomaten abgeholt. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Ja | Ihr Paket wurde nicht rechtzeitig abgeholt und befindet sich noch im Paketautomaten. |
| 473 | `device_removed` | `received` | `inbound` | Ja | Ihr Paket wurde vom Personal aus dem Paketautomaten entnommen. |
| 500 | `deliver_success` | `delivered` | `delivered` | Ja | Ihr Paket wurde erfolgreich abgeholt. |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Ja | Ihre Abholung wurde neu geplant. Wir werden Sie bald über den neuen Termin informieren. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Ja | Ihre Abholung wurde neu geplant. Wir werden Sie bald über den neuen Termin informieren. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Ja | Es gibt ein Problem mit Ihrem Paket. Bitte kontaktieren Sie unseren Kundenservice. |
| 504 | `partial_deliver_success` | — | — | Ja | Dieses Paket wurde abgeholt. Die übrigen Pakete Ihrer Sendung werden in Kürze abgeholt. |
| 510 | `pickuped` | `picked_up` | `pickup` | Ja | Ihr Paket wurde erfolgreich abgeholt. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Ja | Ihr Paket hat {warehouse_name} verlassen. |

Die Spalten **otep** / **otep phase** werden live aus `OTEPStatusInput::FROM_TRACKING_EVENT` und `PHASES` erzeugt — dieselbe Brücke, die die öffentliche Tracking-API als `otep_status` auf jedes Ereignis schreibt. Ein Strich (—) bedeutet: kein OTEP-Code im Parcel-Profil (z. B. Routing-Push 200/201); das Ereignis wird trotzdem gespeichert und kann bei `visible = 1` kundensichtbar sein.

## Eigene Tracking-Seite bauen

Nutzen Sie die **öffentliche Tracking-API**, um eine gebrandete Seite auf Ihrer Website oder App zu betreiben — ohne Login, ohne API-Token. Derselbe Endpunkt speist die eingebaute Tracking-Seite und die GraphQL-Operation `trackingPublic`. Kombinieren Sie ihn mit dem Statuswörterbuch auf dieser Seite und den Ablaufmustern unten.

### 1. Öffentlichen Endpunkt aufrufen

Ein GET pro Sendungsnummer. Die Suche deckt Superroute-Nummern, externe Nummern und bestimmte Drittnummern ohne Provider-ID ab.

```
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. Sprache der Beschreibungen wählen

Die `description`-Texte folgen der Request-Locale über den Header `Accept-Language`. Senden Sie einen Projekt-Sprachcode (`en`, `chs`, `de`, …) oder einen Alias wie `zh-CN`. Fehlt der Header, gilt die Standard-Locale.

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

### 3. Antwortfelder zum Rendern

Es wird nur die öffentliche Oberfläche geliefert — vollständige Absender-/Empfängeradressen sind **nicht** enthalten (nur im authentifizierten internen Tracking-Endpunkt).

| 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. Empfohlener UI-Ablauf

1. Sendungsnummer vom Besucher erfassen und den öffentlichen GET-Endpunkt aufrufen (optional mit `Accept-Language`).
2. Bei `result: false` oder HTTP 404 „nicht gefunden“ anzeigen und beenden.
3. `data[0]` (neuestes Ereignis) für den Kopfstatus: Text aus `description`; Icons/Fortschritt über `tracking_event_status_id` oder `otep_status`.
4. Die volle `data`-Liste als Zeitlinie rendern (bereits neueste zuerst). Fehlende Schritte nicht erfinden.
5. Wenn `proofs` nicht leer ist und der letzte Status ein Erfolg ist (typisch 500 oder 510), „Nachweis anzeigen“ anbieten; `signed_url` für ablaufende Links, `full_url` für dauerhafte Pfade.

### 5. Fortschrittsanzeige

**Keine** feste Kette für jedes Paket hardcoden. Wörterbuch und Abläufe auf dieser Seite nutzen: viele Last-Mile-Zustellungen 100 → 300/301 → 450 → 500; Zwei-Abschnitts-Fahrten zuerst 460 → 510. Über `otep_status` oder `tracking_event_status_id` verzweigen; bei Korrekturen das neueste Ereignis gilt.

### 6. Zustellnachweis

`proofs[]` enthält Foto-/Signaturmetadaten, sofern vorhanden. Ihre Seite kann die Anzeige weiterhin mit einer Postleitzahlprüfung schützen; die API liefert ein normalisiertes `postcode`-Feld. Keine vollständigen Straßenadressen auf einer völlig öffentlichen Seite — dieser Endpunkt lässt sie absichtlich weg.

### 7. Verwandte öffentliche Oberflächen

Wählen Sie die Oberfläche, die zu Ihrem Stack passt. Alle sind öffentlich (kein Token), sofern die API-Docs nichts anderes sagen.

| 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. Minimale Beispiele

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

## Häufige Tracking-Abläufe

Das sind **typische Sequenzen**, keine harte Zustandsmaschine. Echte Zeitlinien überspringen Schritte, fügen Ausnahmen ein oder mischen abhol- und lieferseitige Ereignisse auf demselben Auftrag. Zahlen sind `tracking_event_status_id`; öffentliche Zeitlinien zeigen nur Zeilen mit `tracking.visible = 1`. Verzweigen Sie über `status_id` / `key` und behandeln Sie das neueste Ereignis (höchste id) als maßgeblich.

### Lager → Last-Mile-Zustellung

Häufigster Eigenfahrer-Pfad: Auftrag erstellt, Paket im Lager empfangen, Fahrer startet Zustellung, dann Erfolg oder Ausnahme. Planungs-Codes wie 400/401/402 existieren oft im Wörterbuch, sind aber **nicht** kundensichtbar.

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

### Abholung / reiner Abholabschnitt

Fahrer holt ab und meldet Erfolg (mit POD möglich) oder Abholausnahme. Reine Abholaufträge bleiben abholseitig; Zwei-Abschnitts-Fahrten gehen nach 510 in die Lieferseite über.

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

### Zwei Abschnitte (erst abholen, dann zustellen)

Wenn eine Fahrt sowohl Abholung als auch Zustellung hat — Lieferung mit Abholung, Peer-to-Peer, viele Multi-Leg-Transfers. Die Zeitlinie zeigt typisch zuerst **abholseitige** Meilensteine (460 → 510), dann **lieferseitige** (450 → 500). Die Ereignisseite wählt die Beschreibung, nicht der Auftragstyp.

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

### Drittpartei / Carrier-Fulfilment

Carrier-Buchung kann 110/120 erzeugen; die Produktpolitik hält sie auf der öffentlichen Zeitlinie **verborgen**. Gemeinsame sichtbare Meilensteine folgen Lager + Last Mile (300/301 → 800 → 450 → 500). Endgültige Carrier-Stornierung nutzt 403 (nicht 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 (Task-Dispatch)

Eigenes Wörterbuch (nicht in den Tabellen oben). Happy Path: eingereicht → Kurier zugewiesen → zur Abholung → abgeholt → unterwegs → zugestellt. 411/412 können vor dem Start schleifen; 501 nach fehlgeschlagenem Versuch.

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

### Ausnahme- und Endcodes (Kurzübersicht)

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

### Faustregeln für Integratoren

1. Kundenrelevante Anker: **100** erstellt, **300/301** im Lager, **450** unterwegs zur Zustellung, **500** zugestellt; Abholung **460** und **510**.
2. Keine feste Vollkette annehmen — optionale Lagerscans, Dritt-Hops (800) und Seitenwechsel sind normal.
3. Ausnahmen (501–503, 512–513, 600, 700) können nach „unterwegs …“ kommen; nach Neu-Planung erneut 450/460.
4. Nicht sichtbare Wörterbuchzeilen auf der öffentlichen Seite ignorieren; Webhooks können sie trotzdem senden. Bei Korrekturen immer die neueste Event-id verwenden.

Platzhalter wie `{warehouse_name}` werden zur Laufzeit durch den echten Lager- oder Standortnamen ersetzt. Neue Wörterbuchzeilen und Sichtbarkeitsänderungen kommen per Migration; die Seite liest die Tabelle bei jeder Anfrage neu und kann relativ zu dieser Umgebung nicht veralten.