OTEP — Open Tracking Event Protocol

Tłumaczenie dla wygody — wersja angielska jest wiążąca.

Status: Wersja robocza v0.1 · Otwarta, neutralna wobec dostawców specyfikacja · Licencja: otwarta (zob. §10)

OTEP to otwarty, neutralny wobec dostawców protokół opisujący cykl życia dowolnego śledzonego obiektu. Definiuje jeden model zdarzeń i jeden słownik statusów, tak aby zdarzenia śledzenia z dowolnego źródła — dostawy własną flotą, przewoźnicy zewnętrzni, etykiety przewoźników i nie tylko — mogły być wymieniane, rozumiane i rzutowane na standardy międzynarodowe bez ponownej integracji dla każdej ze stron.

Ten dokument jest specyfikacją: struktura, pola, tabele statusów, maszyna stanów, mapowania na standardy zewnętrzne oraz reguły zgodności pozwalające zbudować zgodną implementację. Jest niezależny od implementacji — opisuje protokół, a nie wewnętrzne mechanizmy konkretnego dostawcy. Słowa kluczowe RFC-2119 (MUST / SHOULD / MAY) mają charakter normatywny.

1. Co rozwiązuje OTEP

Śledzenie jest rozdrobnione: każdy przewoźnik inaczej nazywa pola i kody statusów, każdy kanał dostawy raportuje we własnej postaci, a połączenie z globalnymi standardami oznacza kolejne integracje od nowa. OTEP daje producentom i konsumentom jeden wspólny język: producent emituje zdarzenia OTEP raz, a każdy konsument OTEP je rozumie i może je rzutować na potrzebny mu standard.

2. Zasady projektowe

Oparte na zdarzeniach (event-sourced). Oś czasu zdarzeń jest źródłem prawdy; „bieżący status” jest zawsze rzutem — statusem najnowszego zdarzenia.
Co / Kiedy / Gdzie / Dlaczego. Każde zdarzenie jest ukształtowane wokół tych czterech wymiarów — tych samych, które dzielą GS1 EPCIS, IATA ONE Record i UN/CEFACT — dzięki czemu standardy te są rzutami wyjściowymi zdarzenia OTEP, a nie równoległymi modelami.
Źródła bez listy nie stanowią przeszkody. Źródło, które udostępnia tylko bieżący status (bez historii), jest obsługiwane przez syntezę jednego zdarzenia na każdą zaobserwowaną zmianę (§5).
Addytywne. OTEP jest udostępniany obok dowolnego istniejącego API śledzenia; jego przyjęcie nigdy nie wymaga niekompatybilnej zmiany w tym, czego konsumenci już używają.

3. Oś czasu OTEP

Oś czasu to koperta przenosząca śledzony obiekt oraz uporządkowaną listę zdarzeń.

{
  "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 */ ]
}

Zdarzenie OTEP

{
  // 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"
  }
}

Każde pole z wyjątkiem subject, occurred_at, status_code i source jest opcjonalne — częściowe źródła wypełniają to, co posiadają. Skany w węzłach/hubach ustawiają location na obiekt skanujący. Wysokoczęstotliwościowa telemetria GPS NIE jest zdarzeniem OTEP; zdarzenie jest emitowane przy zmianie statusu lub skanie w węźle.

4. Słownik

4.1 Kody statusów

20 kanonicznych kodów cyklu życia. phase jest zawsze wyprowadzalna z kodu.

code	phase	terminalny	POD	znaczenie
`information_submitted`	pre_shipment			otrzymano informacje o zamówieniu
`booking_confirmed`	pre_shipment			potwierdzono przewoźnika/rezerwację
`awaiting_pickup`	pre_shipment			gotowe do odbioru
`out_for_pickup`	pickup			w drodze po odbiór
`picked_up`	pickup		✓	odebrano od nadawcy
`pickup_failed`	exception			próba odbioru nieudana
`pickup_rescheduled`	exception			odbiór zostanie powtórzony
`received`	inbound			przyjęto w obiekcie
`arrival_scan`	inbound			skan przyjazdu w węźle
`in_transit`	transit			w ruchu
`package_outbound`	transit			opuściło obiekt
`removed_from_route`	exception			zdjęto z trasy
`route_cancelled`	exception			trasa anulowana
`out_for_delivery`	out_for_delivery			w pojeździe
`delivered`	delivered	✓	✓	dostarczono do odbiorcy
`delivery_failed`	exception			próba dostawy nieudana
`delivery_rescheduled`	exception			zostanie powtórzone / ponowna dostawa
`return_to_sender`	return	✓		powrót do nadawcy
`rejected_by_recipient`	return	✓		odbiorca odmówił
`cancelled`	return	✓		zamówienie anulowane

4.2 Fazy

pre_shipment · preparing · pickup · inbound · in_custody · transit · out_for_delivery · delivered · exception · return. (preparing i in_custody są zarezerwowane dla profili niepaczkowych — §8.)

4.3 Typy źródeł i typy czasu

source.type: self_delivery · third_party_delivery · carrier_label. time_type: actual · estimated · scheduled (domyślnie actual).

4.4 Przyczyny incydentów

Gdy zdarzenie znajduje się w fazie exception, SHOULD przenosić incident_reason z tego znormalizowanego słownika:

Carrier: 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
Retailer/shipper: retailer_cancelled, retailer_incorrect_data, retailer_not_ready, retailer_incorrect_parcel, retailer_incorrect_dimensions, retailer_packaging_issue
Consignee: 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
Customs: customs_delay, customs_documentation, customs_duties_unpaid, customs_prohibited, customs_inspection
Force majeure: weather_delay, natural_disaster, force_majeure
Other: parcel_being_researched, security_issue, regulatory_hold, unknown

5. Maszyna stanów i źródła zwracające tylko status

Fazy postępują naprzód; wyjątki przerywają je i rozwiązują się powrotnie. Stany terminalne (delivered, return_to_sender, rejected_by_recipient, cancelled) zamykają obiekt.

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

Reguły:

Konsumenci MUST porządkować zdarzenia według occurred_at i MUST tolerować przybycie poza kolejnością.
Przejścia do stanu terminalnego są idempotentne; powtórzenia są deduplikowane.
Po statusie terminalnym producent MUST NOT emitować dalszych zdarzeń poza udokumentowanym przepływem RMA / ponownego otwarcia.
Źródło udostępniające tylko bieżący status MUST syntetyzować jedno zdarzenie na każdą zaobserwowaną zmianę (ze stabilnym kluczem deduplikacji), zamiast pomijać historię. Z czasem migawki kumulują się w oś czasu.

6. Mapowania na standardy zewnętrzne

Cztery wymiary OTEP odpowiadają pole w pole głównym standardom, więc każdy z nich jest rzutem wyjściowym zdarzenia OTEP.

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	—
subject (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

Wartości dla poszczególnych kodów (EPCIS CBV bizStep/disposition, ONE Record eventCode, kod UN/CEFACT) są publikowane w odczytywalnym maszynowo zbiorze kodów. Poza tymi standardami międzynarodowymi oś czasu OTEP może być również rzutowana na ślady OpenTelemetry, obserwacje OGC SensorThings oraz popularne platformy handlowe (AfterShip, Shopify, Amazon, Walmart, BigCommerce, Magento, WooCommerce, Etsy).

Pewność: wartości EPCIS CBV to stabilne, standardowe URN. Wartości kodów ONE Record i UN/CEFACT stanowią najlepsze dopasowanie dla ostatniej mili i SHOULD być zweryfikowane wobec oficjalnych list kodów przed użyciem zewnętrznym. „Dostarczono do odbiorcy” nie ma dokładnego CBV bizStep — używane jest najbliższe dopasowanie (receiving + received) lub URN rozszerzenia słownika użytkownika.

7. API OTEP

OTEP jest konsumowany przez niewielką, tylko do odczytu powierzchnię HTTP; wszystkie punkty końcowe są publiczne.

Verb	Ścieżka	Zwraca
GET	`/api/v1/otep/trackings/{tracking_number}`	oś czasu dla numeru śledzenia
GET	`/api/v1/otep/trackings/{tracking_number}/events`	tylko zdarzenia
POST	`/api/v1/otep/trackings/batch`	wiele numerów śledzenia w jednym wywołaniu
POST	`/api/v1/otep/validate`	kontrola zgodności dla przesłanej osi czasu (§9)

Dostępne jest również zapytanie GraphQL udostępniające tę samą oś czasu.

Negocjacja treści

Ta sama oś czasu jest serializowana do dowolnej żądanej reprezentacji, za pomocą parametru zapytania ?format= lub profilu Accept:

Żądanie	Reprezentacja
`?format=otep` (domyślnie)	natywna oś czasu OTEP
`?format=epcis`	GS1 EPCIS 2.0 (JSON-LD `ObjectEvent`s)
`?format=onerecord`	IATA ONE Record (`LogisticsEvent`s)
`?format=uncefact`	status transportu UN/CEFACT
`?format=otlp`	ślady OpenTelemetry
`?format=sensorthings`	obserwacje OGC SensorThings
`?format=aftership` \| `shopify` \| `amazon` \| `walmart` \| `bigcommerce` \| `magento` \| `woocommerce` \| `etsy`	postać śledzenia/realizacji danej platformy

Zdarzenia, którym nie można przypisać kodu w danym rzucie, są pomijane i zliczane (nigdy po cichu odrzucane).

8. Profile domenowe

OTEP jest protokołem ogólnym, a nie paczkowym. Warstwa protokołu (koperta zdarzenia, kręgosłup faz, maszyna stanów) jest uniwersalna; konkretne kody statusów należą do profilu zadeklarowanego na osi czasu poprzez profile. Kody z §4 to profil parcel. Inne domeny — przeprowadzki, dostawa jedzenia, magazynowanie i nie tylko — dodają własne zestawy kodów w ramach swojego profilu, w przestrzeni nazw otep:<profile>:<code>, z których każdy mapuje się na ten sam kręgosłup faz. Dodanie profilu jest rozszerzeniem, a nie zmianą protokołu.

9. Specyfikacja zgodności (normatywna)

Producent lub konsument jest zgodny z OTEP, gdy każde zdarzenie, które emituje lub akceptuje, spełnia te tabele i reguły.

9.1 Koperta osi czasu

Pole	Typ	Wym.	Ograniczenia
`otep_version`	string	MUST	semver, np. `0.1`
`profile`	string	MUST	zarejestrowany profil
`subject`	object	MUST	§9.2
`current_status`	string\|null	SHOULD	kod statusu (§4)
`current_phase`	string\|null	SHOULD	MUST być równe fazie `current_status`, jeśli oba obecne
`delivered`	boolean	SHOULD	`true` wtedy i tylko wtedy, gdy `current_status` = `delivered`
`events`	array	MUST	obiekty zdarzeń (§9.3), porządkowalne według `occurred_at`

9.2 `subject`

Co najmniej JEDNO z tracking_number / order_id / package_id MUST być obecne.

Pole	Typ	Ograniczenia
`tracking_number`	string	niepuste
`order_id` / `package_id`	integer\|null
`external_tracking_number`	string\|null
`gs1_sscc`	string\|null	18 cyfr
`piece_id`	string\|null

9.3 Obiekt zdarzenia

#	Pole	Typ	Wym.	Ograniczenia
1	`occurred_at`	string	MUST	ISO-8601 z przesunięciem
2	`recorded_at`	string\|null	SHOULD	ISO-8601
3	`time_type`	string	MAY (domyślnie `actual`)	`actual` \| `estimated` \| `scheduled`
4	`status_code`	string\|null	MUST¹	kod z §4.1
5	`phase`	string\|null	SHOULD	MUST być równe fazie `status_code`
6	`incident_reason`	string\|null	SHOULD²	przyczyna z §4.4
7	`description`	string\|null	MAY	czytelne dla człowieka
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? }`

¹ Zakodowane zdarzenie MUST przenosić kod statusu z §4.1. Surowy skan, którego nie potrafisz jeszcze sklasyfikować, MAY ustawić status_code = null, ale MUST zachować natywny kod w source.external_event_code i MUST być zliczony, nigdy odrzucony. ² Zdarzenie w fazie exception SHOULD przenosić incident_reason. ³ Zdarzenia ze status_code ∈ {delivered, picked_up} SHOULD przenosić pod.

9.4 `location`

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

9.5 `source`

Pole	Typ	Wym.	Ograniczenia
`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⁴	Twój surowy kod statusu
`raw`	object\|null	MAY	oryginalny ładunek

⁴ MUST być obecne, gdy status_code jest null, tak aby natywny kod nigdy nie został utracony.

9.6 Reguły

Czas. occurred_at MUST parsować się jako ISO-8601. Znormalizuj numeryczne epoki i .NET /Date(ms)/ przy przyjmowaniu; nie emituj tych form.
Porządkowanie / deduplikacja. Konsumenci MUST sortować według occurred_at, tolerować przybycie poza kolejnością i deduplikować na (subject, status_code, occurred_at).
Maszyna stanów. Po statusie terminalnym nie emituj dalszych zdarzeń poza udokumentowanym przepływem RMA / ponownego otwarcia.
Brak cichej utraty. Zdarzenia, których nie można zakodować, MUST być zliczane, nigdy odrzucane.
Wyprowadzanie. phase, current_status, current_phase, delivered są rzutami — jeśli są obecne, MUST być spójne z osią czasu zdarzeń.

9.7 Poziomy zgodności i walidacja

Level 1 — emituje kopertę (§9.1), zdarzenia z wymaganymi polami (§9.3), prawidłowe kody statusów (§4.1), prawidłowe fazy (§4.2) oraz przestrzega maszyny stanów (§5).
Level 2 — dodatkowo emituje co najmniej jeden rzut na standard zewnętrzny (§6) oraz, gdzie to zasadne, kody specyficzne dla profilu (§8).

Zweryfikuj swoje wyjście, wysyłając POST z osią czasu na POST /api/v1/otep/validate. Każdy errors traktuj jako blokujący; zaadresuj warnings. Odczytywalny maszynowo JSON Schema oraz kompletny zbiór kodów (każdy kod statusu, faza i mapowanie zewnętrzne) są publikowane na potrzeby walidacji offline.

10. Otwartość i zarządzanie

OTEP jest otwartą specyfikacją, dostępną za darmo do implementacji przez dowolną stronę.

Normatywne vs informacyjne. Normatywne: koperta zdarzenia, kręgosłup faz, słownik statusów, maszyna stanów oraz mapowania pól na standardy zewnętrzne. To, w jaki sposób implementujący wiąże OTEP ze swoimi wewnętrznymi systemami, jest jego własną sprawą i pozostaje poza zakresem tego dokumentu.
Stabilne identyfikatory. Kody są adresowane jako otep:<profile>:<code>, fazy jako otep:phase:<name>. Po opublikowaniu w wydanej wersji znaczenie identyfikatora jest niezmienne.
Wersjonowanie. Wersjonowanie semantyczne. Dodawanie kodów/profili jest zmianą MINOR (kompatybilną wstecz); zmiana znaczenia istniejącego kodu jest zmianą MAJOR i SHOULD być unikana. Wersja protokołu podróżuje z każdą osią czasu (otep_version).
Rozszerzanie. Nowe profile i kody są proponowane wobec tej specyfikacji, a nie odgałęziane (forkowane), tak aby niezależni implementujący się zbiegali. Eksperymentalne kody MAY używać prefiksu x- (otep:parcel:x-my_code) do czasu rejestracji.
Licencja. Specyfikacja ma zostać wydana na otwartej licencji — do ustalenia, oczekuje na zatwierdzenie.

11. Interoperacyjność dostawców — przynieś własny standard

OTEP zaprasza innych dostawców do wniesienia własnego standardu zdarzeń śledzenia, tak aby OTEP mógł współdziałać z nim w obu kierunkach:

Rzutuj OTEP → swój standard. Zdefiniuj mapowanie z osi czasu OTEP na swój format, ponownie wykorzystując słownik statusów OTEP. To czysta transformacja — oś czasu na wejściu, Twoja struktura na wyjściu — więc mapowanie pisze się raz i każdy producent OTEP może emitować Twój format.
Mapuj swój standard → OTEP. Dostarcz powiązanie (crosswalk) z Twojego słownika statusów na kody OTEP (§4) oraz, w razie potrzeby, profil (§8). Twoje surowe kody są zachowywane w source.external_event_code; niezmapowane kody są zliczane, nigdy odrzucane.

Nawet jeśli nie możesz przyjąć OTEP bezpośrednio, możesz dodać pojedynczy znormalizowany otep_status do własnych odpowiedzi API oraz udostępnić swoje kody zdarzeń śledzenia do mapowania crosswalk. Proponuj mapowania wobec tej specyfikacji (zamiast forkowania), aby implementujący się zbiegali; nowe formaty podłączają się do tej samej negocjacji treści ?format= i nigdy nie psują istniejącego konsumenta.