OTEP — Open Tracking Event Protocol

Prevod radi praktičnosti — merodavna je verzija na engleskom jeziku.

Status: Nacrt v0.1 · Otvorena, vendor-neutralna specifikacija · Licenca: otvorena (vidi §10)

OTEP je otvoren, vendor-neutralan protokol za životni ciklus bilo kog predmeta koji se može pratiti. Definiše jedan model događaja i jedan rečnik statusa tako da se događaji praćenja iz bilo kog izvora — dostava sopstvenom flotom, kuriri trećih strana, oznake prevoznika i šire — mogu razmenjivati, razumeti i projektovati na međunarodne standarde bez ponovne integracije za svaku stranu.

Ovaj dokument je specifikacija: struktura, polja, tabele statusa, automat stanja, mapiranja na spoljne standarde i pravila usaglašenosti za izgradnju usaglašene implementacije. Nezavisan je od implementacije — opisuje protokol, a ne interne mehanizme bilo kog konkretnog vendora. Ključne reči RFC-2119 (MUST / SHOULD / MAY) su normativne.

1. Šta OTEP rešava

Praćenje je fragmentisano: svaki prevoznik drugačije imenuje polja i statusne kodove, svaki kanal dostave izveštava u sopstvenom obliku, a povezivanje sa globalnim standardima znači ponovnu integraciju iznova i iznova. OTEP daje proizvođačima i potrošačima jedan zajednički jezik: proizvođač jednom emituje OTEP događaje, a svaki OTEP potrošač ih razume i može ih projektovati na standard koji mu je potreban.

2. Principi dizajna

Zasnovano na događajima. Vremenska linija događaja je izvor istine; „trenutni status“ je uvek projekcija — status poslednjeg događaja.
Šta / Kada / Gde / Zašto. Svaki događaj je oblikovan oko ove četiri dimenzije — iste dimenzije koje dele GS1 EPCIS, IATA ONE Record i UN/CEFACT — tako da su ti standardi izlazne projekcije OTEP događaja, a ne paralelni modeli.
Izvori bez liste nisu prepreka. Izvor koji izlaže samo trenutni status (bez istorije) obrađuje se sintetizovanjem jednog događaja po posmatranoj promeni (§5).
Aditivno. OTEP se izlaže uporedo sa bilo kojim postojećim API-jem za praćenje; njegovo usvajanje nikada ne zahteva promenu koja narušava ono što potrošači već koriste.

3. OTEP vremenska linija

Vremenska linija je omotač koji nosi praćeni predmet i uređenu listu događaja.

{
  "otep_version": "0.1",
  "profile": "parcel",                  // domain profile (§8)
  "subject": {
    "tracking_number": "SR123...",      // ≥1 identifier required
    "order_id": 12345,                  // optional
    "package_id": 67890,                // optional
    "external_tracking_number": "1Z...",// optional
    "gs1_sscc": "00...",                // optional — enables EPCIS epcList
    "piece_id": "..."                   // optional — enables ONE Record linkage
  },
  "current_status": "delivered",        // projection of the latest event
  "delivered": true,
  "events": [ /* OTEP events, §4 */ ]
}

OTEP događaj

{
  // WHAT — carried once at the timeline level (subject above)

  // WHEN
  "occurred_at": "2026-06-10T09:30:00-04:00",  // event instant, ISO-8601 with offset
  "recorded_at": "2026-06-10T09:45:23-04:00",  // ingestion instant (optional)
  "time_type": "actual",                        // actual | estimated | scheduled

  // WHERE
  "location": {
    "name": "Toronto Hub",
    "code": "YYZ-2",
    "gln": "0614141000005",                     // GS1 GLN → EPCIS SGLN
    "lat": 43.6777, "lng": -79.6248,
    "country": "CA"                             // ISO 3166-1 alpha-2
  },

  // WHY / WHAT HAPPENED
  "status_code": "out_for_delivery",            // an OTEP status code (§4)
  "phase": "out_for_delivery",                  // derived from status_code
  "incident_reason": null,                       // an OTEP incident reason (§4) when exception

  // WHO
  "actor": { "type": "driver", "name": "Jane D.", "phone": "+1..." },

  // PROVENANCE
  "source": {
    "type": "self_delivery",                    // self_delivery | third_party_delivery | carrier_label
    "provider_id": null,
    "carrier_code": null,
    "external_event_code": null,                 // your raw status code (preserve it)
    "raw": { /* original payload */ }
  },

  // PROOF
  "pod": {
    "photos": [ { "url": "...", "content_base64": null } ],
    "signature": [ { "url": "...", "content_base64": null } ],
    "recipient": "John Smith"
  }
}

Svako polje osim subject, occurred_at, status_code i source je opciono — delimični izvori popunjavaju ono što imaju. Skeniranja na čvorovima/habovima postavljaju location na objekat skeniranja. Visokofrekventna GPS telemetrija NIJE OTEP događaj; događaj se emituje pri promeni statusa ili skeniranju na čvoru.

4. Rečnik

4.1 Statusni kodovi

20 kanonskih kodova životnog ciklusa. phase se uvek može izvesti iz koda.

code	phase	terminalno	POD	značenje
`information_submitted`	pre_shipment			informacije o porudžbini primljene
`booking_confirmed`	pre_shipment			prevoznik/rezervacija potvrđen
`awaiting_pickup`	pre_shipment			spremno za preuzimanje
`out_for_pickup`	pickup			na putu radi preuzimanja
`picked_up`	pickup		✓	preuzeto od pošiljaoca
`pickup_failed`	exception			pokušaj preuzimanja neuspešan
`pickup_rescheduled`	exception			preuzimanje će se ponoviti
`received`	inbound			primljeno u objektu
`arrival_scan`	inbound			skeniranje dolaska na čvoru
`in_transit`	transit			u kretanju
`package_outbound`	transit			napustilo objekat
`removed_from_route`	exception			uklonjeno sa rute
`route_cancelled`	exception			ruta otkazana
`out_for_delivery`	out_for_delivery			u vozilu
`delivered`	delivered	✓	✓	isporučeno primaocu
`delivery_failed`	exception			pokušaj isporuke neuspešan
`delivery_rescheduled`	exception			ponoviće se / ponovna isporuka
`return_to_sender`	return	✓		vraćanje na poreklo
`rejected_by_recipient`	return	✓		primalac odbio
`cancelled`	return	✓		porudžbina otkazana

4.2 Faze

pre_shipment · preparing · pickup · inbound · in_custody · transit · out_for_delivery · delivered · exception · return. (preparing i in_custody rezervisani su za neparcel profile — §8.)

4.3 Tipovi izvora i tipovi vremena

source.type: self_delivery · third_party_delivery · carrier_label. time_type: actual · estimated · scheduled (podrazumevano actual).

4.4 Razlozi incidenata

Kada je događaj u fazi exception, SHOULD nositi incident_reason iz ovog normalizovanog rečnika:

Prevoznik: carrier_damaged_parcel, carrier_sorting_error, carrier_address_not_found, carrier_parcel_lost, carrier_not_enough_time, carrier_vehicle_issue, carrier_capacity_exceeded, carrier_mechanical_delay
Trgovac/pošiljalac: retailer_cancelled, retailer_incorrect_data, retailer_not_ready, retailer_incorrect_parcel, retailer_incorrect_dimensions, retailer_packaging_issue
Primalac: consignee_refused, consignee_business_closed, consignee_not_available, consignee_not_home, consignee_cancelled, consignee_verification_failed, consignee_incorrect_address, consignee_access_restricted, consignee_safe_place_unavailable
Carina: customs_delay, customs_documentation, customs_duties_unpaid, customs_prohibited, customs_inspection
Viša sila: weather_delay, natural_disaster, force_majeure
Ostalo: parcel_being_researched, security_issue, regulatory_hold, unknown

5. Automat stanja i izvori samo sa statusom

Faze napreduju unapred; izuzeci ih prekidaju i vraćaju nazad. Terminalna stanja (delivered, return_to_sender, rejected_by_recipient, cancelled) zatvaraju predmet.

pre_shipment → preparing → pickup → inbound → in_custody → transit → out_for_delivery → delivered ✓
                                       └──────────── exception ──────────┘
                                       └──────────── return / cancelled ✓

Pravila:

Potrošači MUST sortirati događaje po occurred_at i MUST tolerisati dolazak van redosleda.
Prelazi u terminalno stanje su idempotentni; ponavljanja se deduplikuju.
Nakon terminalnog statusa, proizvođač MUST NOT emitovati dalje događaje osim dokumentovanog RMA / re-open toka.
Izvor koji izlaže samo trenutni status MUST sintetizovati jedan događaj po posmatranoj promeni (sa stabilnim ključem za deduplikaciju) umesto da izostavi istoriju. Vremenom se snimci nagomilavaju u vremensku liniju.

6. Mapiranja na spoljne standarde

OTEP-ove četiri dimenzije poklapaju se polje-za-polje sa glavnim standardima, tako da je svaki izlazna projekcija OTEP događaja.

OTEP	GS1 EPCIS 2.0	IATA ONE Record	UN/CEFACT
`occurred_at` (+offset)	`eventTime` + `eventTimeZoneOffset`	`eventDate` + `eventTimeType=Actual`	Event Date/Time
`recorded_at`	`recordTime`	recordedAt	—
subjekat (sscc/piece)	`epcList` (SSCC URN)	`linkedObject` → Piece/Shipment	Consignment
`location` (gln/lat/lng)	`readPoint` / `bizLocation` (SGLN)	`recordedAtLocation` → Location	Location
`status_code`	`bizStep` + `disposition`	`eventCode`	Transport status code
`actor`	sourceList / extension	Actor / Party	Party
`incident_reason`	disposition / ErrorDeclaration	event remark	Status reason code

Vrednosti po kodu (EPCIS CBV bizStep/disposition, ONE Record eventCode, UN/CEFACT kod) objavljene su u mašinski čitljivom kodeksu. Pored ovih međunarodnih standarda, OTEP vremenska linija se takođe može projektovati na OpenTelemetry tragove, OGC SensorThings opservacije i uobičajene komercijalne platforme (AfterShip, Shopify, Amazon, Walmart, BigCommerce, Magento, WooCommerce, Etsy).

Pouzdanost: EPCIS CBV vrednosti su stabilni standardni URN-ovi. ONE Record i UN/CEFACT kodne vrednosti najbolje su prilagođene poslednjoj milji i treba ih proveriti u odnosu na zvanične kodne liste pre spoljne upotrebe. „Isporučeno primaocu“ nema tačan CBV bizStep — koristi se najbliže rešenje (receiving + received), ili URN ekstenzije korisničkog rečnika.

7. OTEP API

OTEP se konzumira preko male HTTP površine samo za čitanje; sve krajnje tačke su javne.

Verb	Path	Vraća
GET	`/api/v1/otep/trackings/{tracking_number}`	vremensku liniju za broj za praćenje
GET	`/api/v1/otep/trackings/{tracking_number}/events`	samo događaje
POST	`/api/v1/otep/trackings/batch`	mnogo brojeva za praćenje u jednom pozivu
POST	`/api/v1/otep/validate`	proveru usaglašenosti za poslatu vremensku liniju (§9)

Dostupan je i GraphQL upit koji izlaže istu vremensku liniju.

Pregovaranje o sadržaju

Ista vremenska linija se serijalizuje u bilo koju reprezentaciju koju zatražite, preko ?format= upitnog parametra ili Accept profila:

Zahtev	Reprezentacija
`?format=otep` (podrazumevano)	izvorna OTEP vremenska linija
`?format=epcis`	GS1 EPCIS 2.0 (JSON-LD `ObjectEvent`s)
`?format=onerecord`	IATA ONE Record (`LogisticsEvent`s)
`?format=uncefact`	UN/CEFACT transportni status
`?format=otlp`	OpenTelemetry tragovi
`?format=sensorthings`	OGC SensorThings opservacije
`?format=aftership` \| `shopify` \| `amazon` \| `walmart` \| `bigcommerce` \| `magento` \| `woocommerce` \| `etsy`	oblik praćenja/ispunjenja platforme

Događaji kojima se ne može dodeliti kod u projekciji se preskaču i broje (nikada se tiho ne odbacuju).

8. Domenski profili

OTEP je opšti protokol, a ne protokol za pakete. Sloj protokola (omotač događaja, kičma faza, automat stanja) je univerzalan; konkretni statusni kodovi pripadaju profilu deklarisanom na vremenskoj liniji preko profile. Kodovi u §4 su profil parcel. Drugi domeni — selidbe, dostava hrane, skladištenje i šire — dodaju svoje skupove kodova pod svojim profilom, sa prostorom imena otep:<profile>:<code>, svaki mapiran na istu kičmu faza. Dodavanje profila je ekstenzija, a ne promena protokola.

9. Specifikacija usaglašenosti (normativno)

Proizvođač ili potrošač je OTEP-usaglašen kada svaki događaj koji emituje ili prihvata zadovoljava ove tabele i pravila.

9.1 Omotač vremenske linije

Polje	Tip	Obav.	Ograničenja
`otep_version`	string	MUST	semver, npr. `0.1`
`profile`	string	MUST	registrovan profil
`subject`	object	MUST	§9.2
`current_status`	string\|null	SHOULD	statusni kod (§4)
`current_phase`	string\|null	SHOULD	MUST biti jednako fazi koda `current_status` ako su oba prisutna
`delivered`	boolean	SHOULD	`true` ako i samo ako je `current_status` = `delivered`
`events`	array	MUST	objekti događaja (§9.3), sortirljivi po `occurred_at`

9.2 `subject`

Najmanje JEDNO od tracking_number / order_id / package_id MUST biti prisutno.

Polje	Tip	Ograničenja
`tracking_number`	string	nije prazno
`order_id` / `package_id`	integer\|null
`external_tracking_number`	string\|null
`gs1_sscc`	string\|null	18 cifara
`piece_id`	string\|null

9.3 Objekat događaja

#	Polje	Tip	Obav.	Ograničenja
1	`occurred_at`	string	MUST	ISO-8601 sa ofsetom
2	`recorded_at`	string\|null	SHOULD	ISO-8601
3	`time_type`	string	MAY (podrazumevano `actual`)	`actual` \| `estimated` \| `scheduled`
4	`status_code`	string\|null	MUST¹	kod iz §4.1
5	`phase`	string\|null	SHOULD	MUST biti jednako fazi koda `status_code`
6	`incident_reason`	string\|null	SHOULD²	razlog iz §4.4
7	`description`	string\|null	MAY	čitljivo za čoveka
8	`location`	object\|null	MAY	§9.4
9	`actor`	object\|null	MAY	`{ type, name?, phone? }`; type ∈ {driver, operator, carrier, system}
10	`source`	object	MUST	§9.5
11	`pod`	object\|null	MAY³	`{ photos[], signature[], recipient? }`

¹ Kodirani događaj MUST nositi statusni kod iz §4.1. Sirovo skeniranje koje još ne možete klasifikovati MAY postaviti status_code = null, ali MUST sačuvati izvorni kod u source.external_event_code i MUST biti izbrojano, nikada odbačeno. ² Događaj u fazi exception SHOULD nositi incident_reason. ³ Događaji sa status_code ∈ {delivered, picked_up} SHOULD nositi pod.

9.4 `location`

name (string) · code (string) · gln (GS1 GLN, 13 cifara) · lat / lng (WGS-84) · country (ISO 3166-1 alpha-2). Sve opciono.

9.5 `source`

Polje	Tip	Obav.	Ograničenja
`type`	string	MUST	`self_delivery` \| `third_party_delivery` \| `carrier_label`
`provider_id`	integer\|null	MAY
`carrier_code`	string\|null	MAY
`external_event_code`	string\|null	SHOULD⁴	vaš sirovi statusni kod
`raw`	object\|null	MAY	originalni payload

⁴ MUST biti prisutno kada je status_code null, tako da se izvorni kod nikada ne izgubi.

9.6 Pravila

Vreme. occurred_at MUST se parsirati kao ISO-8601. Normalizujte numeričke epohe i .NET /Date(ms)/ pri unosu; nemojte emitovati te oblike.
Redosled / dedup. Potrošači MUST sortirati po occurred_at, tolerisati dolazak van redosleda i deduplikovati po (subject, status_code, occurred_at).
Automat stanja. Nakon terminalnog statusa, nemojte emitovati dalje događaje osim dokumentovanog RMA / re-open.
Bez tihog gubitka. Događaji koji se ne mogu kodirati MUST biti izbrojani, nikada odbačeni.
Izvođenje. phase, current_status, current_phase, delivered su projekcije — ako su prisutni MUST biti konzistentni sa vremenskom linijom događaja.

9.7 Nivoi usaglašenosti i validacija

Nivo 1 — emituje omotač (§9.1), događaje sa obaveznim poljima (§9.3), važeće statusne kodove (§4.1), važeće faze (§4.2) i poštuje automat stanja (§5).
Nivo 2 — dodatno emituje najmanje jednu projekciju na spoljni standard (§6) i, gde je primenljivo, kodove specifične za profil (§8).

Proverite svoj izlaz slanjem vremenske linije na POST /api/v1/otep/validate. Tretirajte svaku grešku (errors) kao blokirajuću; rešite upozorenja (warnings). Mašinski čitljiva JSON Schema i kompletan kodeks (svaki statusni kod, faza i spoljno mapiranje) objavljeni su za oflajn validaciju.

10. Otvorenost i upravljanje

OTEP je otvorena specifikacija, besplatna za implementaciju bilo kojoj strani.

Normativno vs informativno. Normativno: omotač događaja, kičma faza, rečnik statusa, automat stanja i mapiranja polja na spoljne standarde. Način na koji implementator povezuje OTEP sa sopstvenim internim sistemima njegova je stvar i van obima je ovog dokumenta.
Stabilni identifikatori. Kodovi se adresiraju kao otep:<profile>:<code>, faze kao otep:phase:<name>. Jednom objavljeno u izdatoj verziji, značenje identifikatora je nepromenljivo.
Verzionisanje. Semantičko verzionisanje. Dodavanje kodova/profila je MINOR (kompatibilna unazad) promena; menjanje značenja postojećeg koda je MAJOR promena i SHOULD se izbegavati. Verzija protokola putuje sa svakom vremenskom linijom (otep_version).
Ekstenzija. Novi profili i kodovi predlažu se u odnosu na ovu specifikaciju umesto forkovanja, tako da se nezavisni implementatori približavaju. Eksperimentalni kodovi MAY koristiti prefiks x- (otep:parcel:x-my_code) dok se ne registruju.
Licenca. Specifikacija je namenjena izdavanju pod otvorenom licencom — TBD, do potvrde.

11. Interoperabilnost vendora — donesite svoj standard

OTEP poziva druge vendore da donesu sopstveni standard događaja praćenja kako bi OTEP mogao da interoperira sa njim, u oba smera:

Projektujte OTEP → vaš standard. Definišite mapiranje sa OTEP vremenske linije na vaš format, ponovo koristeći OTEP rečnik statusa. To je čista transformacija — vremenska linija ulazi, vaša struktura izlazi — pa se mapiranje piše jednom i svaki OTEP proizvođač može emitovati vaš format.
Mapirajte vaš standard → OTEP. Obezbedite ukrštanje sa vašeg rečnika statusa na OTEP kodove (§4) plus, ako je potrebno, profil (§8). Vaši sirovi kodovi se čuvaju u source.external_event_code; nemapirani kodovi se broje, nikada ne odbacuju.

Čak i ako ne možete direktno usvojiti OTEP, dobrodošli ste da dodate jedan normalizovani otep_status sopstvenim API odgovorima i da podelite svoje kodove događaja praćenja za ukršteno mapiranje. Predložite mapiranja u odnosu na ovu specifikaciju (umesto forkovanja) kako bi se implementatori približili; novi formati se priključuju istom ?format= pregovaranju o sadržaju i nikada ne narušavaju postojećeg potrošača.