如何將出貨追蹤數據連接至 Oms:訂單映射及同步規則
要將貨件追蹤資料連接至訂單管理系統(OMS),請先將每個受追蹤包裹對應至內部貨件記錄,然後將該貨件連結至其訂單及履行明細。透過供應商支援的介面接收追蹤更新,保留原始事件,並為重複事件、延遲更新、貨件狀態及訂單完成制定明確規則。不要單獨使用追蹤號碼作為訂單識別碼,也不要讓單一派送事件自動關閉包含多個包裹的訂單。

本指南供負責實施此連接的整合工程師及電子商務營運團隊參考。建議的設計會將承運商觀察結果與業務決策分開:追蹤資料描述包裹的運送歷程,而OMS決定該歷程對履行、客戶溝通及訂單關閉代表甚麼。
界定每項記錄由哪個系統負責
在建立 API 連接前,請與 OMS 管理員、履行團隊及客戶服務團隊確認資料歸屬。否則,即使技術上的整合成功,仍可能覆寫有效的業務資料。
- OMS:負責訂單、訂單明細、所需數量、取消及訂單完成規則。
- 履行系統:負責其建立的貨件或包裹記錄,包括包裝分配及標籤指派。該系統可以是 OMS 本身,也可以是獨立的倉庫系統。
- 追蹤供應商:提供追蹤觀察結果及供應商定義的狀態分類。
- 整合層:負責識別碼交叉參照、事件處理、正規化、重試處理及同步稽核記錄。
請將這些視為建議的界線,而不是對軟件的假設。記錄例外情況。例如,如果倉庫可以更換寄件標籤,整合系統便需要該系統發出的明確更新,而不是自行猜測新發現的號碼取代舊號碼。
在同步狀態前建立訂單至包裹的對應關係
一種實用的關係是 訂單 → 履行 → 包裹 → 追蹤指派。你的 OMS 可能使用不同名稱,或合併其中部分記錄。即使資料庫結構不同,也應保留這些關係。
一張訂單可以有多個履行,而一個履行可以包含多個包裹。包裹亦可能獲得替換的追蹤指派或連結的最後一公里識別碼。這些識別碼不應產生額外的訂購數量。
| 記錄 | 建議欄位 | 用途 |
|---|---|---|
| 訂單 | 租戶或商店 ID、不可變更的 OMS 訂單 ID | 區分不同商戶,避免依賴顯示用訂單編號。 |
| 履行 | 履行 ID、訂單 ID、已分配的明細 ID 及數量 | 識別哪些已購買商品正在履行。 |
| 包裹 | 內部包裹 ID、履行 ID、可用時的包裹分配 | 提供不依賴追蹤標籤的穩定身份。 |
| 追蹤指派 | 指派 ID、包裹 ID、供應商帳戶、承運商識別碼、追蹤號碼、有效期間 | 將傳入的追蹤觀察結果連結至正確的包裹及指派生命週期。 |
透過已儲存的交叉參照比對更新
建立貨件時,請在為其註冊追蹤前保存內部 ID。儲存文件化註冊流程返回的任何供應商追蹤記錄 ID。如果供應商支援商戶參考,請使用不透明的內部參考值,並在本地保留對應關係。
對於傳入的更新,首先在正確的供應商帳戶及租戶內解析已儲存的供應商記錄 ID。如果無法取得該識別碼,請使用文件所述的追蹤號碼、承運商身份、帳戶上下文及指派歷史的組合。將此視為查找策略,而不是該組合在全球範圍內唯一的保證。
不要以客戶姓名、電郵地址或未限定範圍的顯示用訂單編號進行配對。請將追蹤號碼保留為字串,以保留前導零。除非相關承運商或供應商合約允許,否則避免刪除字元或更改大小寫。
如果查找沒有返回匹配結果,或返回多個可能的匹配結果,請將更新隔離以供調查。未解析的事件比自信地將更新套用至錯誤客戶的訂單更安全。
處理拆單而不臆測包裹分配
考慮一張包含三件商品的訂單。包裹 A 載有兩件,包裹 B 載有一件。包裹 A 派送完成,表示有兩件商品具備派送證據;這並不表示整張訂單已派送完成。
如果履行系統只記錄兩個包裹屬於同一個履行,請不要臆測單件商品層級的分配。你仍可計算所有必要包裹是否已派送,但在存在分配資料前,商品層級的派送報告應保持不可用或明確標記為不確定。
透過持久化資料接收層連接追蹤 API
使用將供應商通訊與 OMS 寫入分開的流程:
建立貨件 → 註冊追蹤 → 傳入更新或排程檢索 → 持久化事件儲存 → 對應及正規化 → 更新 OMS → 對賬
對於 17TRACK 實施方案,Tracking API 產品頁面及官方 API 文件是相關的起點。在實施介面卡前,請確認適用的註冊介面、承運商識別碼、更新傳送選項、驗證要求、狀態定義及帳戶限制。本指南中的資料模型是整合建議,並不表示 17TRACK 使用這些欄位名稱,或為你的 OMS 提供原生連接器。
如果你選擇的供應商支援 webhooks,請使用其文件所述的機制驗證傳入請求,並在確認接收前持久化儲存已接受的訊息。將耗時的 OMS 工作放在請求路徑之外。請遵循供應商實際的確認及重試合約,而不要假設特定的回應內容或逾時時間。
如果需要輪詢,請在 API 支援的地方儲存檢索進度、控制並行量,並遵守文件所述的速率限制。無論是收到 webhook 還是輪詢請求成功,都不能證明 OMS 已更新;請分開記錄這些結果。
制定可承受重試及延遲事件的同步規則
1. 使處理具備冪等性
同一觀察結果被處理兩次,不應重複建立貨件、重複增加數量,或再次發送相同的客戶通知。HTTP 不會令任意 POST 操作具備冪等性;整合系統必須實施重複保護。RFC 9110 解釋了 HTTP 方法的冪等性。
在文件有記載且可用時,使用穩定的供應商事件 ID。否則,根據指派 ID 及相關事件欄位定義指紋,例如事件時間戳記、來源狀態及位置。記錄發生碰撞或事件描述變更的可能性。即使原始觀察結果不會產生另一項 OMS 操作,也應予以保留。
分別保護每項副作用。例如,OMS 狀態寫入及電郵通知需要各自的去重控制。使用交易性 outbox 或同等的持久化工作記錄,避免程序崩潰後已接受的事件沒有排程更新。
2. 分開儲存事件時間及接收時間
事件發生時間及整合系統接收時間回答的是不同問題。請同時儲存兩者,以及原始時間戳記表示方式及任何提供的時區偏移。對於時區未知的事件,不要默默套用倉庫時區。
延遲到達的運輸中掃描通常應豐富歷史,而不應取代較新的已派送狀態。然而,單靠時間戳記並不足夠:供應商可能發出更正,而事件可能缺少完整時間資料。在可用時使用文件所述的順序或修訂欄位,並制定明確的更正政策。
3. 正規化狀態但不抹除來源細節
建立 OMS 能理解的小型內部詞彙,例如等待承運商接收、運輸中、派送中、已派送、例外及退回。將供應商文件所述的狀態映射至其中。這些是建議的內部分類,而不是通用的承運商定義。
儲存原始狀態代碼、描述、事件位置、供應商記錄參考及映射規則版本。未映射的值應建立可供審查的情況,而不是預設為已派送或失敗。除非來源事件明確支持該解讀,否則建立標籤不應被視為承運商已實際接收貨件的證明。
4. 使用轉換規則,而不是簡單的數字排名
貨件狀態不一定形成直線。例外狀態之後可能恢復正常運輸,而派送嘗試並不等於已派送。退回運送可能在較早的派送事件後開始。
- 當後續證據支持恢復運送時,允許清除例外狀態。
- 防止普通的歷史掃描悄悄取代已派送狀態。
- 透過受控的修訂路徑允許文件記載的更正。
- 在 OMS 支援的情況下,將退回運送與出庫完成分開追蹤。
- 將含糊或互相矛盾的證據轉交營運隊列。
為這些規則建立版本。映射變更時,決定其只適用於新事件,還是歷史記錄需要受控重新計算。
根據必要的履行義務計算訂單狀態
包裹狀態及訂單狀態應為分開的欄位。標記為已派送的包裹只會為該包裹提供證據;訂單完成取決於剩餘的必要數量及你的業務政策。
一個實用的預設規則是:只有當所有需要派送的數量均具備有效的包裹層級派送證據,且沒有必要的分配尚未解決時,才將訂單標記為全部派送完成。按照 OMS 的取消規則排除已取消數量。數碼商品、自取訂單及其他非運輸義務,應透過各自的完成條件處理。
替換貨件需要明確的關係。如果遺失包裹被替換,請決定替換貨件是否取代原有派送義務。否則,原包裹可能無限期阻礙完成,或兩個包裹都可能被計入履行。請記錄該決定,而不要單靠追蹤狀態推導。
將派送完成與財務結算、退款資格及爭議解決分開。承運商的派送事件不應自動授權退款或結束客戶索賠。
在不遺失稽核軌跡的情況下從故障中恢復
使用有界退避及任何文件所述的重試指引來重試暫時性故障。將暫時性連線故障與無效識別碼、已過期憑證、權限錯誤及結構不相容分開處理。後者需要採取修正措施,而不是無止境重試。
維護失敗工作隊列,包含受影響的租戶、包裹、事件參考、嘗試的操作、錯誤分類及下一步行動。記錄足夠的上下文以便調查,但不要將不必要的客戶資料或憑證複製到日誌中。
除了正常更新路徑外,還要執行對賬。檢查追蹤資料過時的活躍貨件、OMS 寫入失敗的已接受事件、未匹配的觀察結果,以及整合系統計算狀態與 OMS 之間的差異。應根據派送承諾、API 限制及營運風險選擇審查頻率,而不是套用任意的統一時間表。
分配責任:工程團隊處理接收及寫入故障;履行營運團隊解決缺少的包裹關係;客戶服務團隊審查需要與客戶溝通的例外情況。沒有負責人的隊列只是一個儲存位置。
在上線前測試對應及業務規則
使用受控測試資料及有限的正式環境推出。針對事件歷史及最終的 OMS 記錄測試以下情況:
- 單包裹訂單正常進展至派送。
- 拆單中一個包裹已派送,另一個仍在運送中。
- 同一事件被重複接收,但不產生重複副作用。
- 派送完成後才收到較早的運輸掃描。
- 未知承運商或狀態進入審查隊列。
- 替換標籤但不建立另一項履行義務。
- 根據已批准規則,替換貨件取代原包裹。
- 事件被接受後 OMS 無法使用。
- OMS 寫入與確認之間程序重新啟動。
- 兩間商店存在相同顯示用訂單編號,但不進行跨租戶匹配。
當每個已接受事件都有可追溯的處理結果、含糊的匹配無法自動更新訂單,以及操作人員可以安全地重播失敗工作時,才應上線。這些驗收標準比單純展示 API 請求成功更有用。
常見問題
我可以直接將追蹤號碼連接至訂單嗎?
對於嚴格的單包裹流程,直接關係初期可能已足夠。不過,仍應在訂單與追蹤指派之間使用內部貨件身份。這可為拆單、重新貼標籤及替換貨件提供遷移路徑,而無需改變訂單記錄的含義。
整合系統應使用 webhooks 還是輪詢?
使用供應商支援且與你的基礎設施相容的傳送機制。Webhooks 可以減少重複檢索,而輪詢則可在支援的情況下配合基於檢索的流程及對賬。兩種方式都不能免除持久化儲存、重複處理及故障恢復的需要。
當追蹤事件沒有匹配的訂單時應怎樣處理?
將其儲存在未匹配事件隊列中,調查註冊記錄、租戶上下文、承運商身份及貨件建立時間。不要建立訂單,也不要自動將事件附加至看似合理的客戶。修正映射後再重播該事件。
派送通知應由 OMS 還是追蹤系統發送?
為每種通知類型及觸發條件選定一個負責系統。如果兩個系統都能發送相同訊息,請停用其中一條路徑,或共用持久化通知分類帳。亦應決定訊息是指單一包裹還是完整訂單,尤其是在拆單履行的情況下。
例外狀態是否表示訂單已失敗?
不是。例外是需要解讀的觀察結果,不一定是永久結果。保留原因、監察後續事件,並使用你的升級政策決定營運團隊何時需要介入。
來源
- 17TRACK Tracking API — API 整合起點的官方產品參考。
- 17TRACK API documentation — 供應商特定合約的實施參考;部署前請確認適用的介面及帳戶要求。
- RFC 9110, Section 9.2.2: Idempotent Methods — 支持區分方法冪等性與應用程式層級重複保護的 HTTP 語義。


