OTEP 開放協定 開發者中心 首頁
開放協定

OTEP

開放追蹤事件協議
一個事件,無限旅程。

一套開放、廠商中立的事件協定,適用於追蹤、配送、履約與物流作業。從承運商與快遞員,到倉庫、智能櫃、路線,乃至未來的移動網路,OTEP 為每一個營運事件提供共通的語言。

使命
透過共享的事件語言,讓物流系統得以互通。

什麼是 OTEP?

OTEP(Open Tracking Event Protocol)是一套開放、廠商中立的協定,涵蓋任何可追蹤主體的完整生命週期。由 Superroute 發起並維護,任何人皆可免費實作。它將自配送、第三方配送、承運商追蹤、配送證明、異常、節點掃描與司機軌跡,統一為單一事件流與單一狀態詞彙,並設計為可延伸至搬家、外送、倉儲等領域。

它解決的問題

追蹤是碎片化的。每家承運商對欄位命名各不相同,每個配送通道各自為政,而要連接到全球標準就意味著一次又一次地重新整合。

碎片化的詞彙

每家承運商都使用自己的狀態碼與欄位名稱。使用者必須為每一次整合撰寫客製化的對應。

孤立的來源

您自己的司機、第三方車隊與標籤承運商各自以不同的格式回報追蹤資訊,因此不存在單一的時間軸。

無法互通

若要與夥伴在 GS1 EPCIS、IATA ONE Record 或 UN/CEFACT 上共享追蹤資訊,就得為每一種標準建立並維護一套獨立的匯出。

運作方式

OTEP 採用事件溯源(event-sourced):事件時間軸即為事實來源,而目前狀態只是最新的事件。每個事件都圍繞四個維度構成——What、When、Where 與 Why——這正是 EPCIS、ONE Record 與 UN/CEFACT 共享的相同維度,因此這些標準成為單純的投影,而非平行的模型。對於只提供目前狀態(無歷史)的來源,會以每次變更合成一個事件來處理,因此缺少事件清單絕不會成為阻礙。

What When Where Why

主要特色

統一時間軸

自配送、第三方配送與承運商貨件,依每個追蹤號碼合併為單一且有序的事件時間軸。

單一狀態詞彙

一套標準化的生命週期,包含正規的狀態碼與階段,從每個來源對應而來——不再需要逐家承運商揣測。

標準互通

只需一個請求參數,即可將任何時間軸投影為 GS1 EPCIS 2.0、IATA ONE Record 或 UN/CEFACT。

設計即通用

一套通用協定搭配領域設定檔——今日為包裹;下一步為搬家、外送與倉儲——皆建立於同一個共享的事件主幹之上。

開放且廠商中立

一份任何人皆可實作的公開、版本化規範。具備穩定的識別碼、已發布的狀態分類法與狀態機。

附加且不破壞既有

透過一個全新的公開 API 與既有 API 並行提供。您現有的整合不會有任何變動。

端點

公開、唯讀,位於既有的 /api/v1 前綴之下。加上 ?format= 即可取得外部標準的投影。

GET
https://api.superlabel.ca/api/v1/otep/trackings/{tracking_number}
某個追蹤號碼的統一 OTEP 時間軸。
GET
https://api.superlabel.ca/api/v1/otep/trackings/{tracking_number}/events
僅取得某個追蹤號碼的事件清單。
POST
https://api.superlabel.ca/api/v1/otep/trackings/batch
在單次呼叫中解析多個追蹤號碼。

輸出格式

輸入一條時間軸,輸出四種表示形式——由 ?format= 或 Accept 設定檔選擇。

format=otep

原生 OTEP 時間軸(預設)。

format=epcis

GS1 EPCIS 2.0 ObjectEvents(JSON-LD)。

format=onerecord

IATA ONE Record LogisticsEvents(JSON-LD)。

format=uncefact

UN/CEFACT 運輸狀態事件。

format=otlp

OpenTelemetry OTLP 追蹤——將旅程視為一條 trace,每個事件為一個 span。

format=aftership

相容 AfterShip 的追蹤物件,含檢查點。

format=shopify

Shopify FulfillmentEvent 清單。

format=amazon

Amazon Shipping(SP-API)追蹤事件歷史。

format=walmart

Walmart Marketplace 訂單明細狀態與追蹤(粗略)。

format=bigcommerce

BigCommerce 訂單狀態與追蹤(粗略)。

format=magento

Magento 訂單狀態與追蹤(粗略)。

format=woocommerce

WooCommerce 訂單狀態與追蹤(粗略)。

format=etsy

Etsy 收據狀態與追蹤(粗略)。

format=sensorthings

OGC SensorThings 觀測值(IoT)。

狀態生命週期

每個事件都對應到一個正規狀態,並歸入各階段——從出貨前,歷經取件、運輸、外出配送,直至終態(delivered、returned、rejected 或 cancelled)。

pre_shipment pickup inbound transit out_for_delivery delivered

開放標準

OTEP 以開放規範形式發布——由 Superroute 發起並維護,任何人皆可免費實作。它並非私有格式:事件信封、階段主幹、狀態詞彙與狀態機,即為公開、規範性的協定。

規範性與資訊性

協定(信封、詞彙、狀態機、標準對應)屬規範性。實作者對其自身內部系統的綁定屬資訊性,且可能有所不同。

穩定且版本化

採用語意化版本控制。新增狀態碼或設定檔可向後相容;已發布識別碼的意義永不變更。協定版本隨每個事件一同傳遞。

穩定識別碼

狀態碼以 otep:<profile>:<code> 表示,階段以 otep:phase:<name> 表示,因此詞彙在各實作者間保持全域明確無歧義。

開放且廠商中立

一份任何一方皆可採用的公開規範,附帶開放授權與公開的擴充流程——以提案新設定檔與狀態碼取代分叉。

建立相容實作

生產者與消費者只需對協定整合一次,而非每家承運商各整合一次。四個步驟即可達成符合規範的實作。

1. 將事件建模為 What / When / Where / Why

發出每個事件時,附上其主體(What)、發生與紀錄時間(When)、位置(Where),以及正規狀態加上可選原因(Why)。除主體、時間與狀態外,每個欄位皆為可選——有什麼就填什麼。

2. 對應到正規詞彙

將您的原始狀態碼轉換為 OTEP 狀態碼與階段。對於只提供目前狀態的來源,以每次變更合成一個事件。

3. 遵循狀態機

依發生時間排序事件,容忍亂序抵達,並將 delivered/returned/rejected/cancelled 視為終態。在註冊前,以 x- 前綴標記實驗性狀態碼。

4. 消費或投影

讀取原生 OTEP,或請求 EPCIS/ONE Record/UN-CEFACT 投影——同一事件,一個參數。新的輸出標準只不過是一個新的序列化器。

符合性層級

Level 1

層級 1 — 發出通用狀態碼、階段與有效的狀態轉移。

Level 2

層級 2 — 額外發出設定檔特定的狀態碼,以及至少一種外部標準投影。

國際互通

OTEP 的四個維度與各大全球標準逐一欄位對齊,因此每一種標準都成為輸出投影,而非平行整合。

GS1 EPCIS 2.0

每個 OTEP 事件成為一個 ObjectEvent;狀態對應至 CBV bizStep + disposition;位置對應至 readPoint。穩定的標準 URN。

IATA ONE Record

每個事件成為一個帶有 eventCode 與 eventTimeType 的 LogisticsEvent;時間軸附加至 Shipment/Piece。

UN/CEFACT

每個事件成為一個 TransportEvent,帶有 Consignment 之下的運輸狀態碼。

欄位對應(OTEP → 標準)
OTEPGS1 EPCIS 2.0IATA ONE RecordUN/CEFACT
occurred_ateventTimeeventDateOccurrence Date/Time
status_codebizStep + dispositioneventCodeTransport status code
locationreadPoint / bizLocationrecordedAtLocationLocation
subjectepcListlinkedObjectConsignment
incident_reasondispositionevent remarkStatus reason code

EPCIS CBV 值為穩定的標準 URN。ONE Record 與 UN/CEFACT 的狀態碼值為最後一哩的最佳近似,於對外使用前應對照官方代碼清單進行驗證。

未來互通 藍圖

OTEP 的設計能持續吸納各項標準。以下列於互通藍圖之中。

MCP AI
透過 MCP 將 OTEP 時間軸開放給 AI 助理,以實現自然語言追蹤。
OGC SensorThings IoT
將 OGC SensorThings 的 IoT 遙測資料(溫度、位置、震動)擷取為 OTEP 感測器事件。

評估中: 其他市集(TikTok Shop、Temu、Shein 等)正在評估中,待其公開履約 API 趨於穩定後將陸續加入。

尚無法完全採用 OTEP?我們仍可以互通。

即使您因任何原因無法直接使用 OTEP 標準,我們也誠摯歡迎您與我們各退一步、相向而行——並且樂於在互通性層面上合作。

開發者資源

建立並驗證符合 OTEP 規範的整合所需的一切——離線規格、機器可讀的結構描述與代碼簿、即時符合性驗證器、MCP 設定,以及一個開發技能。

線上閱讀

規範

在瀏覽器中閱讀完整的規範性協議文件。

線上檢視

Codebook

線上瀏覽每個狀態碼、階段與對應。

線上檢視

範例

可直接複製貼上的整合範例。

線上檢視

符合性驗證器

POST 一條時間軸以檢查其是否符合規範;取回確切的錯誤與警告。

POST https://api.superlabel.ca/api/v1/otep/validate

離線下載

開始建置

OTEP 端點已於 /api/v1/otep 上線。在 REST API 參考文件中探索它們。

開啟 API 參考文件