# Követési eseménykódok

Élőben generálva a https://api.superlabel.ca/api/documentation/tracking-events?lang=hu címen a telepített `tracking` szótártáblából (mely állapotkódok léteznek, és az ügyfelek látják-e őket), a TrackingEvent kulcsokból és a lokalizált `tracking.*` leírásokból. Mindig összhangban van ennek a környezetnek az adatbázisával.

## Eseményoldal, nem rendeléstípus

Ez a szótár **nem** rendeléstípus-lista. Ugyanaz a rendelés kibocsáthat felvételi és kézbesítési oldali eseményeket is — pl. felvételi megállóval járó kézbesítés, peer-to-peer (két szakasz), több szakaszos átszállítás vagy raktári átadás. Az Instant Deliver külön szótárat használ (itt nem listázva). Minden követési esemény egy **oldalt** kap (felvétel vagy kézbesítés), amely kiválasztja a leírást és a láthatóságot ehhez az állapothoz. A numerikus `status_id` és a stabil `key` az API- és webhook-payload `tracking_event_status_id` / `tracking_event_key` mezőinek felel meg; e mezőkre (és szükség esetén az oldalra) ágazza a logikát, soha ne a rendeléstípusra és soha ne a lokalizált leírás szövegére.

## Ügyfél-láthatóság (`tracking.visible`)

A nyilvános követési oldal és a nyilvános követési API csak azokat az eseményeket jeleníti meg, amelyek szótársorán `tracking.visible = 1`, összekapcsolva állapotkód **és** eseményoldal szerint (ugyanaz az oldal, mint az eseményen). A **Nem** jelű állapotok továbbra is léteznek a rendszerben (webhookok, műveleti előzmények, belső eszközök), de az ügyfélnek szánt idővonalról rejtve maradnak. A láthatóság élőben ebből a telepítésből a `tracking` táblából olvasható.

## Kézbesítési oldali események

Állapotok, ha a követési esemény az út **kézbesítési oldalán** van (kézbesítés / last mile). Érvényes tiszta kézbesítési rendelésekre, a peer-to-peer kézbesítési szakaszára, felvétellel járó kézbesítésre, több szakaszos folyamatokra — **nem csak** a „tiszta kézbesítési rendelésekre”. Az **ügyfélnek látható** az adott állapot `tracking.visible` értéke ezen az oldalon.

| status_id | key | otep | otep phase | ügyfélnek látható | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Igen | Szállítmányinformációi beküldésre kerültek. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Igen | A küldeményt megerősítettük. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Igen | A csomag felvételre vár. |
| 200 | `pushed_successful` | — | — | Nem | A rendelését elküldtük útvonaltervezésre. |
| 201 | `pushed_failed` | — | — | Nem | A rendelését nem sikerült elküldeni útvonaltervezésre. Újrapróbáljuk vagy újratervezzük. |
| 300 | `received` | `received` | `inbound` | Igen | Csomagja biztonságosan megérkezett a(z) {warehouse_name} raktárba. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Igen | Csomagja átvétele megtörtént és kiszállításra került a(z) {warehouse_name} raktárba. |
| 400 | `planned` | `in_transit` | `transit` | Nem | Csomagja felrakodásra került és kiszállításra kész. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | Nem | A kiszállítási tervét hamarosan újraütemezzük, kérjük várja a frissítési értesítést. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | Nem | A kiszállítási állapota hamarosan frissítésre kerül, kérjük várjon. |
| 430 | `in_transit` | `in_transit` | `transit` | Igen | Csomagja úton van. |
| 431 | `on_hold` | `in_transit` | `transit` | Igen | Csomagja átmenetileg várakozik. Hamarosan frissítjük az állapotát. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Igen | Csomagja vámkezelés alatt áll. |
| 433 | `loaded` | `package_outbound` | `transit` | Igen | Csomagját felrakodtuk, hamarosan útnak indul. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Igen | Csomagja felvétele átmenetileg szünetel. Hamarosan frissítjük az állapotát. |
| 435 | `facility_received` | `in_transit` | `transit` | Igen | Csomagját átvette a logisztikai központ. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Igen | Csomagja megérkezett egy logisztikai központba. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Igen | Csomagja kiszállítás alatt áll. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Igen | Csomagja egy csomagautomatában várja Önt. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Igen | Csomagját átvették a csomagautomatából. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Igen | Csomagját nem vették át a határidőig, és még a csomagautomatában van. |
| 473 | `device_removed` | `received` | `inbound` | Igen | Csomagját a személyzet kivette a csomagautomatából. |
| 500 | `deliver_success` | `delivered` | `delivered` | Igen | Csomagja sikeresen kiszállításra került, köszönjük hogy használta szolgáltatásunkat! |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Igen | Sajnáljuk, nem sikerült kiszállítani csomagját. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Igen | Sajnáljuk, nem sikerült kiszállítani csomagját. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Igen | Probléma merült fel a kiszállítás során, kérjük lépjen kapcsolatba az ügyfélszolgálattal. |
| 504 | `partial_deliver_success` | — | — | Igen | Ezt a csomagot kézbesítettük. Küldeménye többi csomagja még úton van. |
| 510 | `pickuped` | `picked_up` | `pickup` | Igen | A csomagot futárunk sikeresen átvette. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Igen | Csomagja elhagyta a(z) {warehouse_name}. |

## Felvételi oldali események

Állapotok, ha a követési esemény az út **felvételi oldalán** van (felvételi szakasz). Érvényes tiszta felvételi rendelésekre, a peer-to-peer felvételi szakaszára, felvétellel járó kézbesítésre, több szakaszos folyamatokra — **nem csak** a „tiszta felvételi rendelésekre”. Az **ügyfélnek látható** az adott állapot `tracking.visible` értéke ezen az oldalon.

| status_id | key | otep | otep phase | ügyfélnek látható | description |
|---|---|---|---|---|---|
| 100 | `information_submitted` | `information_submitted` | `pre_shipment` | Igen | Feladási kérése sikeresen beküldésre került. |
| 110 | `booking_confirmed` | `booking_confirmed` | `pre_shipment` | Igen | Felvételi kérelmét megerősítettük. |
| 120 | `awaiting_pickup` | `awaiting_pickup` | `pre_shipment` | Igen | A csomag felvételre vár. |
| 200 | `pushed_successful` | — | — | Nem | A felvételi rendelését elküldtük útvonaltervezésre. |
| 201 | `pushed_failed` | — | — | Nem | A felvételi rendelését nem sikerült elküldeni útvonaltervezésre. Újrapróbáljuk vagy újratervezzük. |
| 300 | `received` | `received` | `inbound` | Igen | Csomagja sikeresen beraktározásra került. |
| 301 | `arrival_scan` | `arrival_scan` | `inbound` | Igen | Order a-scan |
| 400 | `planned` | `in_transit` | `transit` | Nem | Csomagja feldolgozás alatt áll. |
| 401 | `removed_from_route` | `removed_from_route` | `exception` | Nem | Az átvételi tervet hamarosan újraütemezzük, kérjük várja az értesítést. |
| 402 | `route_cancelled` | `route_cancelled` | `exception` | Nem | Az átvételi állapot hamarosan frissítésre kerül, kérjük várjon. |
| 430 | `in_transit` | `in_transit` | `transit` | Igen | Csomagja úton van. |
| 431 | `on_hold` | `in_transit` | `transit` | Igen | Csomagja átmenetileg várakozik. Hamarosan frissítjük az állapotát. |
| 432 | `customs_clearance` | `in_transit` | `transit` | Igen | Csomagja vámkezelés alatt áll. |
| 433 | `loaded` | `package_outbound` | `transit` | Igen | Csomagját felrakodtuk, hamarosan útnak indul. |
| 434 | `collection_on_hold` | `awaiting_pickup` | `pre_shipment` | Igen | Csomagja felvétele átmenetileg szünetel. Hamarosan frissítjük az állapotát. |
| 435 | `facility_received` | `in_transit` | `transit` | Igen | Csomagját átvette a logisztikai központ. |
| 436 | `arrived_at_facility` | `in_transit` | `transit` | Igen | Csomagja megérkezett egy logisztikai központba. |
| 450 | `start_delivery` | `out_for_delivery` | `out_for_delivery` | Igen | A futár úton van az átvételhez, kérjük készítse elő csomagját. |
| 470 | `at_device` | `awaiting_pickup` | `pre_shipment` | Igen | Csomagja egy csomagautomatában várja Önt. |
| 471 | `device_picked_up` | `delivered` | `delivered` | Igen | Csomagját átvették a csomagautomatából. |
| 472 | `device_expired` | `awaiting_pickup` | `pre_shipment` | Igen | Csomagját nem vették át a határidőig, és még a csomagautomatában van. |
| 473 | `device_removed` | `received` | `inbound` | Igen | Csomagját a személyzet kivette a csomagautomatából. |
| 500 | `deliver_success` | `delivered` | `delivered` | Igen | Csomagja sikeresen átvételre került. |
| 501 | `need_rescheduled` | `delivery_rescheduled` | `exception` | Igen | Az átvételt újraütemeztük, hamarosan értesítjük az új átvételi időpontról. |
| 502 | `redelivered_later` | `delivery_rescheduled` | `exception` | Igen | Az átvételt újraütemeztük, hamarosan értesítjük az új átvételi időpontról. |
| 503 | `not_delivered` | `delivery_failed` | `exception` | Igen | Problémába ütköztünk csomagja átvétele során, kérjük lépjen kapcsolatba az ügyfélszolgálattal. |
| 504 | `partial_deliver_success` | — | — | Igen | Ezt a csomagot felvettük. Küldeménye többi csomagját hamarosan felvesszük. |
| 510 | `pickuped` | `picked_up` | `pickup` | Igen | Csomagja sikeresen átvételre került. |
| 800 | `package_outbound` | `package_outbound` | `transit` | Igen | Csomagja elhagyta a(z) {warehouse_name}. |

Az **otep** / **otep phase** oszlopok élőben az `OTEPStatusInput::FROM_TRACKING_EVENT` és `PHASES` forrásból készülnek — ugyanaz a híd, amit a nyilvános tracking API `otep_status`-ként ír minden eseményre. A kötőjel (—) azt jelenti, hogy a parcel profilban nincs OTEP kód (pl. routing push 200/201); az esemény így is tárolódik, és `visible = 1` esetén ügyfélnek látható lehet.

## Saját követési oldal építése

Használja a **nyilvános tracking API-t** márkázott oldalhoz a webhelyén vagy alkalmazásában — bejelentkezés és token nélkül. Ugyanez a végpont hajtja a beépített oldalt és a GraphQL `trackingPublic` műveletet. Kombinálja az ezen az oldalon lévő állapotszótárral és az alábbi folyamatmintákkal.

### 1. Hívja a nyilvános végpontot

Egy GET követési számonként. A keresés lefedi a Superroute számokat, a külső számokat és bizonyos harmadik féles számokat szolgáltatói id nélkül.

```
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. Válassza a leírások nyelvét

A `description` szövegek a kérés locale-ját követik az `Accept-Language` fejlécen keresztül. Küldjön projektnyelvkódot (`en`, `chs`, `hu`, …) vagy aliast, pl. `zh-CN`. Hiányzó fejléc esetén az alapértelmezett nyelv érvényesül.

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

### 3. Megjelenítendő válaszmezők

Csak a nyilvános felület jön vissza — a teljes feladó/címzett címek **nincsenek** benne (csak a hitelesített belső végponton).

| 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. Ajánlott UI folyamat

1. Gyűjtse a számot a látogatótól, és hívja a nyilvános GET-et (opcionálisan `Accept-Language`-dzsel).
2. Ha a `result` false vagy a HTTP 404, mutasson „nem található” üzenetet, és álljon meg.
3. A `data[0]` (legújabb esemény) a fejléc státuszához: szöveg a `description`-ből; ikonok/haladás a `tracking_event_status_id` vagy `otep_status` alapján.
4. Renderelje a teljes `data` listát idővonalként (már legújabb elöl). Ne találjon ki hiányzó lépéseket.
5. Ha a `proofs` nem üres, és a legutóbbi státusz siker (tipikusan 500 vagy 510), kínáljon „bizonyíték megtekintése” lehetőséget; `signed_url` lejáró linkhez, `full_url` állandó útvonalhoz.

### 5. Folyamatjelzők

**Ne** kódoljon be egyetlen láncot minden csomaghoz. Használja az oldal szótárát és folyamatait. Ágazzon `otep_status` vagy `tracking_event_status_id` szerint; a legújabb esemény az irányadó.

### 6. Kézbesítési bizonyíték

A `proofs[]` fotó/aláírás metaadatot hordoz, ha van. Az oldala továbbra is kérhet irányítószámot a megjelenítés előtt; az API normalizált `postcode` mezőt ad. Ne tegyen teljes utcai címeket teljesen nyilvános oldalra.

### 7. Kapcsolódó nyilvános felületek

Válassza a stackjének megfelelőt. Mind nyilvános (token nélkül), hacsak az API dokumentáció mást nem mond.

| 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ális példák

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

## Gyakori követési folyamatminták

Ezek **tipikus sorozatok**, nem kemény állapotgép. A valós idővonalak kihagyhatnak lépéseket, kivételeket szúrnak be, vagy keverik a felvételi és kézbesítési oldali eseményeket ugyanazon a rendelésen. A számok a `tracking_event_status_id`; a nyilvános idővonal csak a `tracking.visible = 1` sorokat mutatja. Ágazzon a `status_id` / `key` mezőkre, és a legújabb eseményt (legnagyobb id) tekintse mérvadónak.

### Raktár → last-mile kézbesítés

A leggyakoribb saját flotta útvonal: rendelés létrehozva, csomag beérkezett, sofőr kézbesít, majd siker vagy kivétel. A 400/401/402 tervezési kódok gyakran léteznek, de **nem** ügyfél-láthatók.

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

### Felvétel / tiszta felvételi szakasz

A sofőr kimegy felvenni, majd sikert (POD lehetséges) vagy felvételi kivételt rögzít. Tiszta felvételi rendelések a felvételi oldalon maradnak; kettős szakasz 510 után a kézbesítési oldalra lép.

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

### Két szakaszos utak (előbb felvétel, aztán kézbesítés)

Ha egy út mind felvételt, mind kézbesítést tartalmaz — felvétellel járó kézbesítés, peer-to-peer, sok multi-leg. Az idővonal tipikusan előbb a **felvételi oldal** mérföldköveit (460 → 510), majd a **kézbesítési oldal**ét (450 → 500) mutatja. Az eseményoldal választja a leírást, nem a rendeléstípus.

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

### Harmadik fél / fuvarozó teljesítés

A fuvarozó foglalás kibocsáthat 110/120-at; a termékpolitika a nyilvános idővonalon **elrejti** őket. A közös látható mérföldkövek a raktár + last mile mintáját követik (300/301 → 800 → 450 → 500). A terminális lemondás 403-at használ (nem 402-t).

```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 (feladat-alapú dispatch)

Saját szótár (nincs a fenti táblákban). Boldog út: benyújtva → futár kiosztva → felvétel felé → felvéve → kézbesítés alatt → kézbesítve. A 411/412 indulás előtt ciklizálhat; 501 sikertelen kísérlet után.

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

### Kivétel- és végkódok (gyors térkép)

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

### Ökölszabályok integrátoroknak

1. Boldog út horgonyai: **100** létrehozva, **300/301** telephelyen, **450** kézbesítés alatt, **500** kézbesítve; felvétel **460** és **510**.
2. Ne feltételezzen rögzített teljes láncot — opcionális scannelések, harmadik féles ugrások (800) és oldalváltások normálisak.
3. A kivételek (501–503, 512–513, 600, 700) jöhetnek „úton…” után; újratervezés után ismét 450/460.
4. A nyilvános oldalon hagyja figyelmen kívül a nem látható sorokat; a webhookok mégis küldhetik őket. Javításkor mindig a legújabb event id-t részesítse előnyben.

Az olyan helyőrzők, mint a `{warehouse_name}`, futásidőben a valódi raktár- vagy helyszínnévvel cserélődnek. Új sorok és láthatóság-változások migrációkkal érkeznek; az oldal minden kérésnél újraolvassa a táblát, így ehhez a környezethez képest nem avulhat el.