# Kódy sledovacích udalostí

Generované naživo na https://api.superlabel.ca/api/documentation/tracking-events?lang=sk z nasadenej slovníkovej tabuľky `tracking` (ktoré stavové kódy existujú a či ich zákazníci vidia), kľúčov TrackingEvent a lokalizovaných popisov `tracking.*`. Vždy v súlade s databázou tohto prostredia.

## Strana udalosti, nie typ objednávky

Tento slovník **nie** je zoznam typov objednávok. Tá istá objednávka môže emitovať udalosti strany vyzdvihnutia aj doručenia — napr. doručenie so zastávkou vyzdvihnutia, peer-to-peer (dva úseky), multi-leg transfer alebo odovzdanie v sklade. Instant Deliver používa samostatný slovník (tu neuvedený). Každá sledovacia udalosť nesie **stranu** (vyzdvihnutie alebo doručenie), ktorá vyberie popis a viditeľnosť pre daný stav. Číselný `status_id` a stabilný `key` zodpovedajú `tracking_event_status_id` / `tracking_event_key` v API a webhook payload-och; vetvenie robte podľa týchto polí (a strany, ak záleží na texte), nikdy podľa typu objednávky a nikdy podľa lokalizovaného textu popisu.

## Viditeľnosť pre zákazníka (`tracking.visible`)

Verejná stránka sledovania a verejné tracking API zobrazujú len udalosti, ktorých riadok slovníka má `tracking.visible = 1`, spojené cez stavový kód **a** stranu udalosti (rovnakú stranu ako na udalosti). Stavy označené **Nie** stále existujú v systéme (webhooky, história operácií, interné nástroje), ale sú skryté zo zákazníckej časovej osi. Viditeľnosť sa číta naživo z tabuľky `tracking` tejto inštalácie.

## Udalosti na strane doručenia

Stavy, keď je sledovacia udalosť na **strane doručenia** cesty (doručenie / last mile). Platí pre čisté doručenia, úsek doručenia peer-to-peer, doručenie s vyzdvihnutím, multi-leg a podobné toky — **nielen** „čisté doručovacie objednávky“. **Viditeľné zákazníkovi** je `tracking.visible` daného stavu na tejto strane.

| status_id | key | otep | otep phase | viditeľné zákazníkovi | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Áno | Vaše informácie o zásielke boli odoslané. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Áno | Vaša zásielka bola potvrdená. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Áno | Vaša zásielka čaká na vyzdvihnutie. |
| 200 | `pushed_successful` | — | — | Nie | Vaša objednávka bola odoslaná na plánovanie trasy. |
| 201 | `pushed_failed` | — | — | Nie | Vašu objednávku sa nepodarilo odoslať na plánovanie trasy. Bude zopakovaná alebo preplánovaná. |
| 300 | `received` | `received` | `inbound` | Áno | Váš balík bezpečne dorazil do {warehouse_name}. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Áno | Váš balík bol vyzdvihnutý a dorazil do {warehouse_name}. |
| 400 | `planned` | `in_transit` | `transit` | Nie | Váš balík je naložený a pripravený na doručenie. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | Nie | Vaše doručenie bude čoskoro preplánované; počkajte prosím na aktualizáciu. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | Nie | Stav vášho doručenia bude čoskoro aktualizovaný. |
| 430 | `in_transit` | `in_transit` | `transit` | Áno | Váš balík je na ceste. |
| 431 | `on_hold` | `in_transit` | `transit` | Áno | Váš balík je dočasne pozastavený. Čoskoro vás budeme informovať. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Áno | Váš balík je v colnom konaní. |
| 433 | `loaded` | `package_outbound` | `transit` | Áno | Váš balík bol naložený a čoskoro vyrazí. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Áno | Vyzdvihnutie vášho balíka je dočasne pozastavené. Čoskoro vás budeme informovať. |
| 435 | `facility_received` | `in_transit` | `transit` | Áno | Váš balík bol prijatý v logistickom centre. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Áno | Váš balík dorazil do logistického centra. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Áno | Váš balík je momentálne na ceste na doručenie. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Áno | Vaša zásielka na vás čaká v balíkovom automate. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Áno | Vaša zásielka bola vyzdvihnutá z balíkového automatu. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Áno | Vaša zásielka nebola vyzdvihnutá do termínu a stále je v balíkovom automate. |
| 473 | `device_removed` | `received` | `inbound` | Áno | Vašu zásielku vybral z balíkového automatu personál. |
| 500 | `deliver_success` | `delivered` | `delivered` | Áno | Váš balík bol úspešne doručený. Ďakujeme! |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Áno | Bohužiaľ, nepodarilo sa nám doručiť váš balík. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Áno | Bohužiaľ, nepodarilo sa nám doručiť váš balík. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Áno | Narazili sme na problém s vaším doručením. Kontaktujte prosím náš tím podpory. |
| 504 | `partial_deliver_success` | — | — | Áno | Tento balík bol doručený. Ostatné balíky vašej zásielky sú stále na ceste. |
| 510 | `pickuped` | `picked_up` | `pickup` | Áno | Balík bol úspešne vyzdvihnutý naším kuriérom. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Áno | Váš balík opustil {warehouse_name}. |

## Udalosti na strane vyzdvihnutia

Stavy, keď je sledovacia udalosť na **strane vyzdvihnutia** cesty (úsek vyzdvihnutia). Platí pre čisté vyzdvihnutia, úsek vyzdvihnutia peer-to-peer, doručenie s vyzdvihnutím, multi-leg a podobné toky — **nielen** „čisté objednávky vyzdvihnutia“. **Viditeľné zákazníkovi** je `tracking.visible` daného stavu na tejto strane.

| status_id | key | otep | otep phase | viditeľné zákazníkovi | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Áno | Vaša požiadavka na balík bola úspešne prijatá. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Áno | Vaša žiadosť o vyzdvihnutie bola potvrdená. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Áno | Vaša zásielka čaká na vyzdvihnutie. |
| 200 | `pushed_successful` | — | — | Nie | Vaša objednávka vyzdvihnutia bola odoslaná na plánovanie trasy. |
| 201 | `pushed_failed` | — | — | Nie | Vašu objednávku vyzdvihnutia sa nepodarilo odoslať na plánovanie trasy. Bude zopakovaná alebo preplánovaná. |
| 300 | `received` | `received` | `inbound` | Áno | Prijali sme váš balík v našom zariadení. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Áno | Order a-scan |
| 400 | `planned` | `in_transit` | `transit` | Nie | Váš balík sa momentálne spracováva. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | Nie | Vyzdvihnutie vášho balíka bude čoskoro preplánované. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | Nie | Stav vášho vyzdvihnutia bude čoskoro aktualizovaný. |
| 430 | `in_transit` | `in_transit` | `transit` | Áno | Váš balík je na ceste. |
| 431 | `on_hold` | `in_transit` | `transit` | Áno | Váš balík je dočasne pozastavený. Čoskoro vás budeme informovať. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Áno | Váš balík je v colnom konaní. |
| 433 | `loaded` | `package_outbound` | `transit` | Áno | Váš balík bol naložený a čoskoro vyrazí. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Áno | Vyzdvihnutie vášho balíka je dočasne pozastavené. Čoskoro vás budeme informovať. |
| 435 | `facility_received` | `in_transit` | `transit` | Áno | Váš balík bol prijatý v logistickom centre. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Áno | Váš balík dorazil do logistického centra. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Áno | Kuriér je na ceste vyzdvihnúť váš balík. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Áno | Vaša zásielka na vás čaká v balíkovom automate. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Áno | Vaša zásielka bola vyzdvihnutá z balíkového automatu. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Áno | Vaša zásielka nebola vyzdvihnutá do termínu a stále je v balíkovom automate. |
| 473 | `device_removed` | `received` | `inbound` | Áno | Vašu zásielku vybral z balíkového automatu personál. |
| 500 | `deliver_success` | `delivered` | `delivered` | Áno | Váš balík bol úspešne vyzdvihnutý. |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Áno | Vyzdvihnutie balíka bolo preplánované. Čoskoro vás budeme informovať o novom rozvrhu. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Áno | Vyzdvihnutie balíka bolo preplánované. Čoskoro vás budeme informovať o novom rozvrhu. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Áno | Narazili sme na problém s vaším balíkom. Kontaktujte prosím náš tím podpory. |
| 504 | `partial_deliver_success` | — | — | Áno | Tento balík bol vyzdvihnutý. Ostatné balíky vašej zásielky vyzdvihneme čoskoro. |
| 510 | `pickuped` | `picked_up` | `pickup` | Áno | Váš balík bol úspešne vyzdvihnutý. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Áno | Váš balík opustil {warehouse_name}. |

Stĺpce **otep** / **otep phase** sa generujú naživo z `OTEPStatusInput::FROM_TRACKING_EVENT` a `PHASES` — ten istý most, ktorý verejné tracking API zapisuje ako `otep_status` na každú udalosť. Pomlčka (—) znamená, že v parcel profile nie je OTEP kód (napr. routing push 200/201); udalosť sa aj tak uloží a pri `visible = 1` môže byť viditeľná zákazníkovi.

## Vytvorte vlastnú stránku sledovania

Použite **verejné tracking API** na stránku s vašou značkou na webe alebo v aplikácii — bez prihlásenia a tokenu. Ten istý endpoint poháňa vstavanú stránku a GraphQL operáciu `trackingPublic`. Spojte ho so slovníkom stavov na tejto stránke a vzormi toku nižšie.

### 1. Zavolajte verejný endpoint

Jeden GET na sledovacie číslo. Vyhľadávanie pokrýva Superroute čísla, externé a niektoré third-party čísla bez id poskytovateľa.

```
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. Vyberte jazyk popisov

Texty `description` nasledujú locale požiadavky cez `Accept-Language`. Pošlite kód jazyka projektu (`en`, `chs`, `sk`, …) alebo alias ako `zh-CN`. Bez hlavičky sa použije predvolený jazyk.

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

### 3. Polia odpovede na vykreslenie

Vracia sa len verejná plocha — úplné adresy odosielateľa/príjemcu **nie** sú zahrnuté (iba na autentifikovanom internom endpointe).

| 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. Odporúčaný UI tok

1. Získajte číslo od návštevníka a zavolajte verejný GET (voliteľne s `Accept-Language`).
2. Ak je `result` false alebo HTTP 404, zobrazte nenájdené a zastavte sa.
3. Použite `data[0]` (najnovšia udalosť) na stav v záhlaví: text z `description`; ikony/postup z `tracking_event_status_id` alebo `otep_status`.
4. Vykreslite celý zoznam `data` ako časovú os (už od najnovších). Nevymýšľajte chýbajúce kroky.
5. Ak `proofs` nie je prázdne a posledný stav je úspech (zvyčajne 500 alebo 510), ponúknite zobrazenie dôkazu; `signed_url` pre dočasné odkazy, `full_url` pre trvalú cestu.

### 5. Indikátory postupu

**Ne**hardkódujte jeden reťazec pre každý balík. Použite slovník a toky na tejto stránke. Vetvenie podľa `otep_status` alebo `tracking_event_status_id`; najnovšia udalosť je autoritatívna.

### 6. Dôkaz doručenia

`proofs[]` nesie metaúdaje fotografie/podpisu, keď sú k dispozícii. Vaša stránka môže stále vyžadovať PSČ pred zobrazením; API vracia normalizované pole `postcode`. Nedávajte úplné uličné adresy na úplne verejnú stránku.

### 7. Súvisiace verejné plochy

Vyberte to, čo sedí k vášmu stacku. Všetky sú verejné (bez tokenu), pokiaľ API dokumentácia nehovorí inak.

| 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álne prí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
}
```

## Bežné vzory sledovacieho toku

Toto sú **typické sekvencie**, nie tvrdý stavový automat. Skutočné časové osi preskakujú kroky, vkladajú výnimky alebo prelínajú udalosti strany vyzdvihnutia a doručenia na tej istej objednávke. Čísla sú `tracking_event_status_id`; verejná os zobrazuje len riadky s `tracking.visible = 1`. Vetvenie robte podľa `status_id` / `key` a najnovšiu udalosť (najvyššie id) berte ako autoritatívnu.

### Sklad → doručenie last-mile

Najbežnejšia cesta vlastnej flotily: objednávka vytvorená, balík prijatý, vodič v doručení, potom úspech alebo výnimka. Plánovacie kódy 400/401/402 často existujú, ale **nie** sú viditeľné 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
```

### Vyzdvihnutie / čistý úsek vyzdvihnutia

Vodič ide vyzdvihnúť a zaznamená úspech (POD možný) alebo výnimku vyzdvihnutia. Čisté vyzdvihnutia ostávajú na strane vyzdvihnutia; dvojetapové prechádzajú na stranu doručenia 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
```

### Dvojité etapy (najprv vyzdvihnúť, potom doručiť)

Keď cesta má vyzdvihnutie aj doručenie — doručenie s vyzdvihnutím, peer-to-peer, mnoho multi-leg. Časová os typicky ukazuje najprv míľniky **strany vyzdvihnutia** (460 → 510), potom **strany doručenia** (450 → 500). Strana udalosti volí popis, nie 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"]
```

### Tretia strana / carrier plnenie

Rezervácia prepravcu môže emitovať 110/120; produktová politika ich drží **skryté** na verejnej osi. Spoločné viditeľné míľniky kopírujú sklad + last mile (300/301 → 800 → 450 → 500). Terminálne zrušenie používa 403 (nie 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 úloh)

Vlastný slovník (nie v tabuľkách vyššie). Šťastná cesta: odoslané → kuriér priradený → k vyzdvihnutiu → vyzdvihnuté → v doručení → doručené. 411/412 môžu cyklovať pred štartom; 501 po neúspechu.

```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ýnimiek a terminálne (rýchla 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) |

### Pravidlá pre integrátorov

1. Kotvy šťastnej cesty: **100** vytvorené, **300/301** v zariadení, **450** v doručení, **500** doručené; vyzdvihnutie **460** a **510**.
2. Nepredpokladajte pevnú úplnú reťaz — voliteľné skeny, skoky tretích strán (800) a zmeny strany sú bežné.
3. Výnimky (501–503, 512–513, 600, 700) môžu prísť po „na ceste…“; po preplánovaní znova 450/460.
4. Na verejnej stránke ignorujte neviditeľné riadky; webhooky ich stále môžu posielať. Pri opravách vždy preferujte najnovšie id udalosti.

Zástupné reťazce ako `{warehouse_name}` sa za behu nahradia skutočným názvom skladu alebo miesta. Nové riadky a zmeny viditeľnosti prichádzajú migráciami; stránka pri každej požiadavke znova načíta tabuľku a nemôže voči tomuto prostrediu zastarať.