# Kodovi događaja praćenja

Generisano uživo na https://api.superlabel.ca/api/documentation/tracking-events?lang=sr iz deploy-ovanog `tracking` rečničkog tabele (koji statusni kodovi postoje i da li ih klijenti vide), TrackingEvent ključeva i lokalizovanih `tracking.*` opisnih stringova. Uvek usklađeno sa bazom ovog okruženja.

## Strana događaja, ne tip porudžbine

Ovaj rečnik **nije** lista tipova porudžbina. Ista porudžbina može emitovati događaje sa strane preuzimanja i strane dostave — npr. dostava sa stajalištem preuzimanja, peer-to-peer (dve etape), multi-leg transfer ili predaja u skladištu. Instant Deliver koristi poseban rečnik (nije naveden ovde). Svaki događaj praćenja nosi **stranu** (preuzimanje ili dostava) koja bira opis i vidljivost za taj status. Numerički `status_id` i stabilni `key` odgovaraju `tracking_event_status_id` / `tracking_event_key` u API i webhook payload-ima; granajte se po tim poljima (i strani kada je tekst bitan), nikad po tipu porudžbine i nikad po lokalizovanom tekstu opisa.

## Vidljivost klijentu (`tracking.visible`)

Javna stranica praćenja i javni tracking API prikazuju samo događaje čiji rečnički red ima `tracking.visible = 1`, povezane preko statusnog koda **i** strane događaja (ista strana kao na događaju praćenja). Statusi označeni sa **Ne** i dalje postoje u sistemu (webhook-ovi, istorija operacija, interni alati) ali su skriveni sa vremenske linije namenjene klijentu. Vidljivost se čita uživo iz `tracking` tabele ove instalacije.

## Događaji na strani dostave

Statusi kada je događaj praćenja na **strani dostave** putovanja (isporuka / last mile). Važi za čiste dostave, etapu dostave peer-to-peer, dostavu sa preuzimanjem, multi-leg i slične tokove — **ne samo** „čiste dostave”. **Vidljivo klijentu** je `tracking.visible` za taj status na ovoj strani.

| status_id | key | otep | otep phase | vidljivo klijentu | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Da | Vaše informacije o pošiljci su poslate. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Da | Vaša pošiljka je potvrđena. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Da | Vaš paket čeka preuzimanje. |
| 200 | `pushed_successful` | — | — | Ne | Vaša porudžbina je poslata na planiranje rute. |
| 201 | `pushed_failed` | — | — | Ne | Vaša porudžbina nije mogla biti poslata na planiranje rute. Biće ponovljeno ili replanirano. |
| 300 | `received` | `received` | `inbound` | Da | Vaš paket je bezbedno stigao u {warehouse_name}. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Da | Vaš paket je uspešno preuzet i dostavljen u {warehouse_name}. |
| 400 | `planned` | `in_transit` | `transit` | Ne | Vaš paket je ukrcan i spreman za dostavu. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | Ne | Vaš plan dostave će uskoro biti preuranjen, molimo sačekajte obaveštenje o ažuriranju. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | Ne | Vaš status dostave će uskoro biti ažuriran, molimo sačekajte. |
| 430 | `in_transit` | `in_transit` | `transit` | Da | Vaš paket je u tranzitu. |
| 431 | `on_hold` | `in_transit` | `transit` | Da | Vaš paket je privremeno zadržan. Uskoro ćemo vas obavestiti. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Da | Vaš paket je na carinjenju. |
| 433 | `loaded` | `package_outbound` | `transit` | Da | Vaš paket je utovaren i uskoro kreće. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Da | Preuzimanje vašeg paketa je privremeno zadržano. Uskoro ćemo vas obavestiti. |
| 435 | `facility_received` | `in_transit` | `transit` | Da | Vaš paket je primljen u logističkom centru. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Da | Vaš paket je stigao u logistički centar. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Da | Vaš paket je na putu dostave. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Da | Vaš paket vas čeka u paketomatu. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Da | Vaš paket je preuzet iz paketomata. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Da | Vaš paket nije preuzet do roka i još uvek se nalazi u paketomatu. |
| 473 | `device_removed` | `received` | `inbound` | Da | Osoblje je izvadilo vaš paket iz paketomata. |
| 500 | `deliver_success` | `delivered` | `delivered` | Da | Vaš paket je uspešno dostavljen, hvala vam što koristite naše usluge! |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Da | Žao nam je, nismo uspeli da dostavimo vaš paket. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Da | Žao nam je, nismo uspeli da dostavimo vaš paket. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Da | Došlo je do problema tokom dostave, molimo kontaktirajte korisničku službu. |
| 504 | `partial_deliver_success` | — | — | Da | Ovaj paket je isporučen. Ostali paketi vaše pošiljke su još uvek na putu. |
| 510 | `pickuped` | `picked_up` | `pickup` | Da | Paket je uspešno preuzet od strane našeg kurira. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Da | Vaš paket je napustio {warehouse_name}. |

## Događaji na strani preuzimanja

Statusi kada je događaj praćenja na **strani preuzimanja** putovanja (etapa preuzimanja). Važi za čista preuzimanja, etapu preuzimanja peer-to-peer, dostavu sa preuzimanjem, multi-leg i slične tokove — **ne samo** „čista preuzimanja”. **Vidljivo klijentu** je `tracking.visible` za taj status na ovoj strani.

| status_id | key | otep | otep phase | vidljivo klijentu | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Da | Vaš zahtev za slanje je uspešno poslat. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Da | Vaš zahtev za preuzimanje je potvrđen. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Da | Vaš paket čeka preuzimanje. |
| 200 | `pushed_successful` | — | — | Ne | Vaša porudžbina preuzimanja je poslata na planiranje rute. |
| 201 | `pushed_failed` | — | — | Ne | Vaša porudžbina preuzimanja nije mogla biti poslata na planiranje rute. Biće ponovljeno ili replanirano. |
| 300 | `received` | `received` | `inbound` | Da | Vaš paket je uspešno uskladišten. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Da | Order a-scan |
| 400 | `planned` | `in_transit` | `transit` | Ne | Vaš paket se obrađuje. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | Ne | Vaš plan preuzimanja će uskoro biti preuranjen, molimo sačekajte obaveštenje. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | Ne | Vaš status preuzimanja će uskoro biti ažuriran, molimo sačekajte. |
| 430 | `in_transit` | `in_transit` | `transit` | Da | Vaš paket je u tranzitu. |
| 431 | `on_hold` | `in_transit` | `transit` | Da | Vaš paket je privremeno zadržan. Uskoro ćemo vas obavestiti. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Da | Vaš paket je na carinjenju. |
| 433 | `loaded` | `package_outbound` | `transit` | Da | Vaš paket je utovaren i uskoro kreće. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Da | Preuzimanje vašeg paketa je privremeno zadržano. Uskoro ćemo vas obavestiti. |
| 435 | `facility_received` | `in_transit` | `transit` | Da | Vaš paket je primljen u logističkom centru. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Da | Vaš paket je stigao u logistički centar. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Da | Kurir je na putu da preuzme paket, molimo pripremite vaš paket. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Da | Vaš paket vas čeka u paketomatu. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Da | Vaš paket je preuzet iz paketomata. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Da | Vaš paket nije preuzet do roka i još uvek se nalazi u paketomatu. |
| 473 | `device_removed` | `received` | `inbound` | Da | Osoblje je izvadilo vaš paket iz paketomata. |
| 500 | `deliver_success` | `delivered` | `delivered` | Da | Vaš paket je uspešno preuzet. |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Da | Vaše preuzimanje je preuraneno, obavestićemo vas o novom vremenu preuzimanja. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Da | Vaše preuzimanje je preuraneno, obavestićemo vas o novom vremenu preuzimanja. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Da | Došlo je do problema sa vašim paketom, molimo kontaktirajte korisničku službu. |
| 504 | `partial_deliver_success` | — | — | Da | Ovaj paket je preuzet. Ostali paketi vaše pošiljke biće preuzeti uskoro. |
| 510 | `pickuped` | `picked_up` | `pickup` | Da | Vaš paket je uspešno preuzet. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Da | Vaš paket je napustio {warehouse_name}. |

Kolone **otep** / **otep phase** se generišu uživo iz `OTEPStatusInput::FROM_TRACKING_EVENT` i `PHASES` — isti most koji javni tracking API upisuje kao `otep_status` na svaki događaj. Crtica (—) znači da nema OTEP koda u parcel profilu (npr. routing push 200/201); događaj se i dalje čuva i može biti vidljiv klijentu kada je `visible = 1`.

## Napravite sopstvenu stranicu praćenja

Koristite **javni tracking API** za brendiranu stranicu na svom sajtu ili u aplikaciji — bez prijave i bez tokena. Isti endpoint pokreće ugrađenu stranicu i GraphQL operaciju `trackingPublic`. Kombinujte ga sa rečnikom statusa na ovoj stranici i tokovima ispod.

### 1. Pozovite javni endpoint

Jedan GET po broju praćenja. Pretraga pokriva Superroute brojeve, spoljne brojeve i neke treće brojeve bez id-a provajdera.

```
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. Izaberite jezik opisa

Tekstovi `description` prate locale zahteva preko `Accept-Language`. Pošaljite kod projekta (`en`, `chs`, `sr`, …) ili alias kao `zh-CN`. Bez zaglavlja koristi se podrazumevani jezik.

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

### 3. Polja odgovora za prikaz

Vraća se samo javna površina — pune adrese pošiljaoca/primaoca **nisu** uključene (samo na autentifikovanom internom 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. Preporučeni UI tok

1. Prikupite broj od posetioca i pozovite javni GET (opciono sa `Accept-Language`).
2. Ako je `result` false ili HTTP 404, prikažite nije pronađeno i zaustavite se.
3. Koristite `data[0]` (najnoviji događaj) za naslovni status: tekst preko `description`; ikone/napredak preko `tracking_event_status_id` ili `otep_status`.
4. Iscrtajte celu listu `data` kao vremensku liniju (već od najnovijeg). Ne izmišljajte korake koji nisu nastali.
5. Ako `proofs` nije prazan i poslednji status je uspeh (obično 500 ili 510), ponudite pregled dokaza; `signed_url` za privremene linkove, `full_url` za trajnu putanju.

### 5. Indikatori napretka

**Ne** hardkodirajte jedan lanac za svaki paket. Koristite rečnik i tokove na ovoj stranici. Granajte po `otep_status` ili `tracking_event_status_id`; najnoviji događaj je merodavan.

### 6. Dokaz isporuke

`proofs[]` nosi metapodatke fotografije/potpisa kada postoje. Vaša stranica i dalje može tražiti poštanski broj pre prikaza; API vraća normalizovano polje `postcode`. Nemojte stavljati pune ulične adrese na potpuno javnu stranicu.

### 7. Povezane javne površine

Izaberite ono što odgovara vašem steku. Sve su javne (bez tokena) osim ako API dokumentacija kaže drugačije.

| 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. Minimalni primeri

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

## Uobičajeni tokovi praćenja

Ovo su **tipične sekvence**, ne tvrda mašina stanja. Stvarne vremenske linije preskaču korake, ubacuju izuzetke ili mešaju događaje strane preuzimanja i dostave na istoj porudžbini. Brojevi su `tracking_event_status_id`; javna linija prikazuje samo redove sa `tracking.visible = 1`. Granajte po `status_id` / `key` i tretirajte najnoviji događaj (najveći id) kao merodavan.

### Skladište → last-mile dostava

Najčešći put sopstvene flote: porudžbina kreirana, paket primljen, vozač kreće u dostavu, zatim uspeh ili izuzetak. Kodovi planiranja 400/401/402 često postoje ali **nisu** vidljivi klijentu.

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

### Preuzimanje / čista etapa preuzimanja

Vozač ide po paket i beleži uspeh (POD moguć) ili izuzetak preuzimanja. Čista preuzimanja ostaju na strani preuzimanja; dvostruke etape nastavljaju na stranu dostave posle 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
```

### Dvostruke etape (prvo preuzmi, zatim dostavi)

Kada putovanje ima i preuzimanje i isporuku — dostava sa preuzimanjem, peer-to-peer, mnogi multi-leg. Vremenska linija tipično prvo pokazuje **stranu preuzimanja** (460 → 510), zatim **stranu dostave** (450 → 500). Strana događaja bira opis, ne tip porudžbine.

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

### Treća strana / carrier ispunjenje

Carrier rezervacija može emitovati 110/120; proizvodna politika ih drži **skrivenim** na javnoj liniji. Zajedničke vidljive tačke prate skladište + last mile (300/301 → 800 → 450 → 500). Terminalni otkaz koristi 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 zadataka)

Sopstveni rečnik (nije u tabelama iznad). Srećan put: poslato → kurir dodeljen → ka preuzimanju → preuzeto → u dostavi → dostavljeno. 411/412 mogu da se vrte pre starta; 501 posle neuspeha.

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

### Kodovi izuzetaka i terminalni (brza 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) |

### Pravila za integratore

1. Sidra srećnog puta: **100** kreirano, **300/301** u objektu, **450** u dostavi, **500** dostavljeno; preuzimanje **460** i **510**.
2. Ne pretpostavljajte fiksni pun lanac — opcioni skenovi, third-party skokovi (800) i promene strane su normalni.
3. Izuzeci (501–503, 512–513, 600, 700) mogu uslediti posle „na putu…“; posle replaniranja ponovo 450/460.
4. Ignorišite nevidljive redove na javnoj stranici; webhook-ovi ih i dalje mogu slati. Uvek preferirajte najnoviji event id pri ispravkama.

Rezervisana mesta kao `{warehouse_name}` zamenjuju se u runtime-u stvarnim imenom skladišta ili lokacije. Novi redovi i promene vidljivosti dolaze migracijama; stranica ponovo čita tabelu pri svakom zahtevu i ne može zastareti u odnosu na ovo okruženje.