# Kódy sledovacích událostí

Generováno živě na https://api.superlabel.ca/api/documentation/tracking-events?lang=cs z nasazené slovníkové tabulky `tracking` (které stavové kódy existují a zda je zákazníci vidí), klíčů TrackingEvent a lokalizovaných popisů `tracking.*`. Vždy v souladu s databází tohoto prostředí.

## Strana události, ne typ objednávky

Tento slovník **není** seznam typů objednávek. Stejná objednávka může emitovat události strany vyzvednutí i doručení — např. doručení se zastávkou vyzvednutí, peer-to-peer (dva úseky), multi-leg transfer nebo předání ve skladu. Instant Deliver používá samostatný slovník (zde neuvedený). Každá sledovací událost nese **stranu** (vyzvednutí nebo doručení), která vybere popis a viditelnost pro daný stav. Číselný `status_id` a stabilní `key` odpovídají `tracking_event_status_id` / `tracking_event_key` v API a webhook payloadech; větvění dělejte podle těchto polí (a strany, pokud záleží na textu), nikdy podle typu objednávky a nikdy podle lokalizovaného textu popisu.

## Viditelnost pro zákazníka (`tracking.visible`)

Veřejná stránka sledování a veřejné tracking API zobrazují jen události, jejichž řádek slovníku má `tracking.visible = 1`, spojené přes stavový kód **a** stranu události (stejnou stranu jako na události). Stavy označené **Ne** v systému stále existují (webhooky, historie operací, interní nástroje), ale jsou skryté ze zákaznické časové osy. Viditelnost se čte živě z tabulky `tracking` této instalace.

## Události na straně doručení

Stavy, když je sledovací událost na **straně doručení** cesty (doručení / last mile). Platí pro čistá doručení, úsek doručení peer-to-peer, doručení s vyzvednutím, multi-leg a podobné toky — **nejen** „čisté doručovací objednávky“. **Viditelné zákazníkovi** je `tracking.visible` daného stavu na této straně.

| status_id | key | otep | otep phase | viditelné zákazníkovi | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Ano | Vaše informace o zásilce byly odeslány. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Ano | Vaše zásilka byla potvrzena. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Ano | Vaše zásilka čeká na vyzvednutí. |
| 200 | `pushed_successful` | — | — | Ne | Vaše objednávka byla odeslána k plánování trasy. |
| 201 | `pushed_failed` | — | — | Ne | Vaši objednávku se nepodařilo odeslat k plánování trasy. Bude zopakována nebo přeplánována. |
| 300 | `received` | `received` | `inbound` | Ano | Váš balík bezpečně dorazil do {warehouse_name}. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Ano | Váš balík byl vyzvednut a dorazil do {warehouse_name}. |
| 400 | `planned` | `in_transit` | `transit` | Ne | Váš balík je naložen a připraven k doručení. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | Ne | Vaše doručení bude brzy přeplánováno; čekejte prosím na aktualizaci. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | Ne | Stav vašeho doručení bude brzy aktualizován. |
| 430 | `in_transit` | `in_transit` | `transit` | Ano | Váš balík je na cestě. |
| 431 | `on_hold` | `in_transit` | `transit` | Ano | Váš balík je dočasně pozastaven. Brzy vás budeme informovat. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Ano | Váš balík je v celním řízení. |
| 433 | `loaded` | `package_outbound` | `transit` | Ano | Váš balík byl naložen a brzy vyrazí. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Ano | Vyzvednutí vašeho balíku je dočasně pozastaveno. Brzy vás budeme informovat. |
| 435 | `facility_received` | `in_transit` | `transit` | Ano | Váš balík byl přijat v logistickém centru. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Ano | Váš balík dorazil do logistického centra. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Ano | Váš balík je aktuálně na cestě k doručení. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Ano | Vaše zásilka na vás čeká v balíkovém automatu. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Ano | Vaše zásilka byla vyzvednuta z balíkového automatu. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Ano | Vaše zásilka nebyla vyzvednuta do termínu a je stále v balíkovém automatu. |
| 473 | `device_removed` | `received` | `inbound` | Ano | Vaši zásilku vyjmul z balíkového automatu personál. |
| 500 | `deliver_success` | `delivered` | `delivered` | Ano | Váš balík byl úspěšně doručen. Děkujeme! |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Ano | Bohužel se nám nepodařilo doručit váš balík. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Ano | Bohužel se nám nepodařilo doručit váš balík. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Ano | Narazili jsme na problém s vaším doručením. Kontaktujte prosím náš tým podpory. |
| 504 | `partial_deliver_success` | — | — | Ano | Tento balík byl doručen. Ostatní balíky vaší zásilky jsou stále na cestě. |
| 510 | `pickuped` | `picked_up` | `pickup` | Ano | Balík byl úspěšně vyzvednut naším kurýrem. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Ano | Váš balík opustil {warehouse_name}. |

## Události na straně vyzvednutí

Stavy, když je sledovací událost na **straně vyzvednutí** cesty (úsek vyzvednutí). Platí pro čistá vyzvednutí, úsek vyzvednutí peer-to-peer, doručení s vyzvednutím, multi-leg a podobné toky — **nejen** „čisté objednávky vyzvednutí“. **Viditelné zákazníkovi** je `tracking.visible` daného stavu na této straně.

| status_id | key | otep | otep phase | viditelné zákazníkovi | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Ano | Váš požadavek na balík byl úspěšně přijat. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Ano | Vaše žádost o vyzvednutí byla potvrzena. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Ano | Vaše zásilka čeká na vyzvednutí. |
| 200 | `pushed_successful` | — | — | Ne | Vaše objednávka vyzvednutí byla odeslána k plánování trasy. |
| 201 | `pushed_failed` | — | — | Ne | Vaši objednávku vyzvednutí se nepodařilo odeslat k plánování trasy. Bude zopakována nebo přeplánována. |
| 300 | `received` | `received` | `inbound` | Ano | Obdrželi jsme váš balík v našem zařízení. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Ano | Order a-scan |
| 400 | `planned` | `in_transit` | `transit` | Ne | Váš balík je aktuálně zpracováván. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | Ne | Vyzvednutí vašeho balíku bude brzy přeplánováno. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | Ne | Stav vašeho vyzvednutí bude brzy aktualizován. |
| 430 | `in_transit` | `in_transit` | `transit` | Ano | Váš balík je na cestě. |
| 431 | `on_hold` | `in_transit` | `transit` | Ano | Váš balík je dočasně pozastaven. Brzy vás budeme informovat. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Ano | Váš balík je v celním řízení. |
| 433 | `loaded` | `package_outbound` | `transit` | Ano | Váš balík byl naložen a brzy vyrazí. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Ano | Vyzvednutí vašeho balíku je dočasně pozastaveno. Brzy vás budeme informovat. |
| 435 | `facility_received` | `in_transit` | `transit` | Ano | Váš balík byl přijat v logistickém centru. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Ano | Váš balík dorazil do logistického centra. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Ano | Kurýr je na cestě vyzvednout váš balík. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Ano | Vaše zásilka na vás čeká v balíkovém automatu. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Ano | Vaše zásilka byla vyzvednuta z balíkového automatu. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Ano | Vaše zásilka nebyla vyzvednuta do termínu a je stále v balíkovém automatu. |
| 473 | `device_removed` | `received` | `inbound` | Ano | Vaši zásilku vyjmul z balíkového automatu personál. |
| 500 | `deliver_success` | `delivered` | `delivered` | Ano | Váš balík byl úspěšně vyzvednut. |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Ano | Vyzvednutí balíku bylo přeplánováno. Brzy vás informujeme o novém termínu. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Ano | Vyzvednutí balíku bylo přeplánováno. Brzy vás informujeme o novém termínu. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Ano | Narazili jsme na problém s vaším balíkem. Kontaktujte prosím náš tým podpory. |
| 504 | `partial_deliver_success` | — | — | Ano | Tento balík byl vyzvednut. Ostatní balíky vaší zásilky vyzvedneme brzy. |
| 510 | `pickuped` | `picked_up` | `pickup` | Ano | Váš balík byl úspěšně vyzvednut. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Ano | Váš balík opustil {warehouse_name}. |

Sloupce **otep** / **otep phase** se generují živě z `OTEPStatusInput::FROM_TRACKING_EVENT` a `PHASES` — stejný most, který veřejné tracking API zapisuje jako `otep_status` na každou událost. Pomlčka (—) znamená, že v parcel profilu není OTEP kód (např. routing push 200/201); událost se stejně uloží a při `visible = 1` může být viditelná zákazníkovi.

## Vytvořte vlastní stránku sledování

Použijte **veřejné tracking API** pro stránku s vaší značkou na webu nebo v aplikaci — bez přihlášení a tokenu. Stejný endpoint pohání vestavěnou stránku a GraphQL operaci `trackingPublic`. Spojte ho se slovníkem stavů na této stránce a vzory toku níže.

### 1. Zavolejte veřejný endpoint

Jeden GET na sledovací číslo. Vyhledávání pokrývá Superroute čísla, externí a některé third-party čísla bez id poskytovatele.

```
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. Zvolte jazyk popisů

Texty `description` následují locale požadavku přes `Accept-Language`. Pošlete kód jazyka projektu (`en`, `chs`, `cs`, …) nebo alias jako `zh-CN`. Bez hlavičky se použije výchozí jazyk.

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

### 3. Pole odpovědi k vykreslení

Vrací se jen veřejná plocha — úplné adresy odesílatele/příjemce **nejsou** zahrnuty (pouze na autentizovaném interním endpointu).

| 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. Doporučený UI tok

1. Získejte číslo od návštěvníka a zavolejte veřejný GET (volitelně s `Accept-Language`).
2. Pokud je `result` false nebo HTTP 404, zobrazte nenalezeno a zastavte se.
3. Použijte `data[0]` (nejnovější událost) pro stav v záhlaví: text z `description`; ikony/postup z `tracking_event_status_id` nebo `otep_status`.
4. Vykreslete celý seznam `data` jako časovou osu (už od nejnovějších). Nevymýšlejte chybějící kroky.
5. Pokud `proofs` není prázdné a poslední stav je úspěch (typicky 500 nebo 510), nabídněte zobrazení důkazu; `signed_url` pro dočasné odkazy, `full_url` pro trvalou cestu.

### 5. Indikátory postupu

**Ne**hardkódujte jeden řetězec pro každý balík. Použijte slovník a toky na této stránce. Větvení podle `otep_status` nebo `tracking_event_status_id`; nejnovější událost je autoritativní.

### 6. Důkaz doručení

`proofs[]` nese metadata fotografie/podpisu, když jsou k dispozici. Vaše stránka může stále vyžadovat PSČ před zobrazením; API vrací normalizované pole `postcode`. Nedávejte úplné uliční adresy na zcela veřejnou stránku.

### 7. Související veřejné plochy

Vyberte to, co sedí k vašemu stacku. Všechny jsou veřejné (bez tokenu), pokud API dokumentace neříká jinak.

| 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. Minimální příklady

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

## Běžné vzory sledovacího toku

Toto jsou **typické sekvence**, ne tvrdý stavový automat. Skutečné časové osy přeskakují kroky, vkládají výjimky nebo prokládají události strany vyzvednutí a doručení na téže objednávce. Čísla jsou `tracking_event_status_id`; veřejná osa zobrazuje jen řádky s `tracking.visible = 1`. Větvení dělejte podle `status_id` / `key` a nejnovější událost (nejvyšší id) berte jako autoritativní.

### Sklad → doručení last-mile

Nejběžnější cesta vlastní flotily: objednávka vytvořena, balík přijat, řidič v doručení, pak úspěch nebo výjimka. Plánovací kódy 400/401/402 často existují, ale **nejsou** viditelné zákazníkovi.

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

### Vyzvednutí / čistý úsek vyzvednutí

Řidič jede vyzvednout a zaznamená úspěch (POD možný) nebo výjimku vyzvednutí. Čistá vyzvednutí zůstávají na straně vyzvednutí; dvouetapové přecházejí na stranu doručení po 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
```

### Dvě etapy (nejprve vyzvednout, pak doručit)

Když cesta má vyzvednutí i doručení — doručení s vyzvednutím, peer-to-peer, mnoho multi-leg. Časová osa typicky ukazuje nejprve milníky **strany vyzvednutí** (460 → 510), pak **strany doručení** (450 → 500). Strana události volí popis, ne typ objednávky.

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

### Třetí strana / carrier plnění

Rezervace dopravce může emitovat 110/120; produktová politika je drží **skryté** na veřejné ose. Sdílené viditelné milníky kopírují sklad + last mile (300/301 → 800 → 450 → 500). Terminální zrušení používá 403 (ne 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 úkolů)

Vlastní slovník (není v tabulkách výše). Šťastná cesta: odesláno → kurýr přiřazen → k vyzvednutí → vyzvednuto → v doručení → doručeno. 411/412 mohou cyklovat před startem; 501 po neúspěchu.

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

### Kódy výjimek a terminální (rychlá mapa)

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

### Pravidla pro integrátory

1. Kotvy šťastné cesty: **100** vytvořeno, **300/301** v zařízení, **450** v doručení, **500** doručeno; vyzvednutí **460** a **510**.
2. Nepředpokládejte pevný úplný řetězec — volitelné skeny, skoky třetích stran (800) a změny strany jsou běžné.
3. Výjimky (501–503, 512–513, 600, 700) mohou přijít po „na cestě…“; po přeplánování znovu 450/460.
4. Na veřejné stránce ignorujte neviditelné řádky; webhooky je stále mohou posílat. Při opravách vždy preferujte nejnovější id události.

Zástupné řetězce jako `{warehouse_name}` se za běhu nahradí skutečným názvem skladu nebo místa. Nové řádky a změny viditelnosti přicházejí migracemi; stránka při každém požadavku znovu načte tabulku a nemůže vůči tomuto prostředí zastarat.