貨件追蹤 API 工作流程:由登記貨件到擷取追蹤詳情
貨件追蹤 API 工作流程由提交追蹤號碼及任何所需的承運商資料開始,接着檢查註冊是否成功,等待追蹤資料可用,並取得貨件的狀態及事件歷史。對於正式環境整合,開發人員亦需要將每筆追蹤記錄連結至訂單、處理部分失敗、安全地處理更新,以及區分已接受的註冊與實際的承運商掃描記錄。
本指南為連接電子商務平台、訂單管理系統、倉庫應用程式或客戶服務工具的開發人員解釋上述工作流程。內容將應用程式設計建議與供應商特定的 API 要求分開說明。如要整合 17TRACK,請在實作以下範例前,使用官方 API 文件確認請求結構、驗證方式、支援的操作及回應欄位。
了解註冊的作用與不作用
向追蹤服務註冊貨件,意味着提交一個識別碼,讓服務根據其 API 合約追蹤或管理該貨件。這並不等同於購買郵資、產生貨運標籤、預約收件或將包裹交給承運商。
在應用程式中將以下三種結果分開處理:
- 已收到請求:API 已對你的 HTTP 請求返回回應。
- 註冊已接受:服務已接受個別追蹤記錄以進行處理。
- 追蹤資料可用:服務已擁有你的應用程式可以取得或接收的貨件資料。
不應將這些結果合併為單一的「成功」旗標。已接受的追蹤號碼可能尚未有任何承運商事件。同樣地,批次請求成功返回 HTTP 回應,並不代表批次中的每個項目都已獲接受;請檢查供應商定義的應用程式層級結果結構。
1. 準備貨件識別資料及 API 設定
在發出註冊請求前,先決定貨件在你自己的系統中如何識別。單靠訂單識別碼通常不足夠,因為一張訂單可能會拆分成多個包裹。為每件貨件或包裹建立獨立的內部記錄,並將該記錄與相關訂單關聯。
有用的內部記錄可包括以下資料。這些是建議的應用程式欄位,並非 17TRACK 請求結構。
- 內部貨件 ID:你為包裹設定的穩定識別碼。
- 訂單參考:該貨件所屬的訂單或履行記錄。
- 追蹤號碼:由承運商發出的識別碼,應以文字儲存以保留開頭的零。
- 承運商資料:如已知,由你的履行系統提供的承運商身份。
- 供應商參考:追蹤服務返回、日後操作所需的任何識別碼。
- 註冊狀態:你對提交狀態的記錄,例如待處理、已接受、已拒絕或等待核對。
- 追蹤狀態:最新的貨件狀態,與註冊狀態分開維護。
提交前先驗證輸入。移除意外的前後空白,但不要根據對承運商格式的假設改寫追蹤號碼。保留原始值以便排查問題。如已知承運商,應將其對應至供應商文件所列的承運商識別碼,而不是傳送非正式的顯示名稱。
在伺服器端設定驗證。將憑證置於原始碼控制之外,分開開發環境與正式環境的設定,並從日誌中遮蓋機密資料。請確認文件所列的 API 版本、請求限制、批次限制及帳戶要求,不要從無關的整合中套用數值。
2. 註冊貨件並記錄項目層級結果
使用供應商文件所述的註冊操作提交追蹤記錄。只包括必要欄位及具明確用途的選填資料。不要僅因訂單資料庫中已有客戶姓名、地址或其他個人資料,便將其傳送出去。
以下虛擬碼展示應用程式流程。函式名稱僅作示例,並非 API 端點或 SDK 方法。
shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)
result = tracking_adapter.register(shipment)
if result.item_accepted:
save_registration_result(shipment_id, result)
elif result.outcome_unknown:
schedule_registration_reconciliation(shipment_id)
else:
save_registration_error(shipment_id, result)
route_for_retry_or_correction(result)
保存足夠資料以解釋發生的情況:內部貨件 ID、提交時間、嘗試次數、項目層級結果,以及任何供應商請求參考。不要只依賴短暫的工作程序日誌。客戶服務及營運團隊需要一個持久答案,以確認貨件是否已成功登記。
逐項處理批次提交
如果 API 支援批次註冊,請將每個返回項目與原始貨件對應。不要因 HTTP 請求成功完成,便將整個批次標記為已接受。保存已接受的項目,隔離被拒絕的項目,並分開調查結果不明的項目。
這可避免一個格式錯誤的追蹤號碼迫使你不必要地重試已成功的記錄,亦能為營運人員提供一份可直接處理的更正清單。
將逾時視為結果不明
逾時並不能證明註冊失敗。連線中斷前,供應商可能已接受請求。重新提交前,應使用文件所述的冪等行為、重複處理或查詢操作核對結果,避免盲目重新提交。
如果供應商對重複請求的處理方式不清楚,請使用受控記錄進行測試,並在啟用自動重試前確認合約。內部對註冊工作進行去重仍然有用,但不能取代你對遠端服務如何處理重複請求的了解。
3. 預留首次追蹤資料到達的時間
註冊獲接受後,追蹤詳情可能不會立即可用。承運商記錄實際處理事件之前,貨運標籤可能已經存在。資料缺失亦可能需要檢查追蹤號碼、承運商選擇或貨件特定的查詢要求。
應明確表示這種情況。「已註冊;等待追蹤資料」比「運送中」或「註冊失敗」更準確。不要為填補空白介面而虛構送達預計或移動事件。
當記錄仍然為空時,請按實際次序調查:
- 確認個別註冊已獲接受。
- 將已提交的追蹤號碼與履行記錄比較。
- 檢查承運商對應及文件所列的任何額外查詢要求。
- 在承運商自己的追蹤頁面檢查同一件貨件。
- 如果承運商已有事件但你的整合沒有,請檢查取得資料的回應,並向 API 供應商提供已遮蓋敏感資料的診斷資訊。
不要在沒有證據的情況下採用統一等待時間。升級規則應反映運輸服務、預期交接流程及你自己的營運承諾。
4. 取得追蹤詳情並正確解讀
記錄可用後,使用所需的識別碼呼叫文件所述的追蹤詳情操作。不要假設註冊與取得資料接受相同欄位。有些 API 合約會區分追蹤號碼、承運商識別碼及供應商產生的記錄參考。
應用程式應區分三個資料層級:
- 貨件摘要:用於儀表板、訂單頁面及營運篩選的整體狀態。
- 事件歷史:個別觀察結果,包括事件描述、時間戳記及所提供的位置。
- 取得資料中繼資料:應用程式接收或取得資料的時間,以及請求是否成功完成。
查詢成功表示取得操作成功,並不表示包裹自上次查詢後已經移動。在產生通知或下游工作流程前,先將返回的追蹤資料與已儲存記錄比較。
分開保存事件時間與取得時間
將承運商事件的相關時間與系統接收該事件的時間分開儲存。今天下午取得的事件可能描述較早的掃描。以取得時間取代事件時間,會令舊更新看起來像新的實際移動。
保留原始時間戳記及任何提供的時區偏移量。只有在已知時區時,才為比較而標準化時間戳記。如果事件沒有時區資料,應保留這種不確定性,而不是悄悄套用伺服器時區。
在標準化狀態旁保留原始含義
標準化狀態有助於跨承運商分組貨件,但原始事件描述可以更準確地解釋營運問題。在可行時保留兩者。單獨的廣泛異常類別,未必能告訴客服人員下一步是檢查地址、聯絡收件人,還是等待下一次更新。
不要從模糊狀態推斷送達保證、已確認遺失或特定的海關結果。應根據底層資料及你的營運政策進行升級處理。
5. 透過輪詢或 Webhook 持續更新記錄
取得一次詳情足以測試連線,但不足以維持貨件可見性。正式環境的設計需要更新機制。請確認所選供應商支援的機制及其附帶條件。
使用輪詢時,應用程式按時間表請求追蹤詳情。在文件所列限制內安排請求,沒有理由時避免反覆查詢未變更的記錄,並對可重試的失敗使用退避策略。客戶開啟訂單頁面不應自動觸發不受限制的上游請求;儲存的追蹤檢視可先提供頁面,而受控的背景程序則負責更新。
如果使用 Webhook,請使用供應商文件所列的驗證機制驗證傳入請求。按照 Webhook 合約,在確認接收前持久化或可靠地排入已接受訊息,然後非同步處理事件。
除非文件所述的傳遞合約另有保證,否則接收器應能容忍重複訊息及意外的到達順序。如有提供,使用供應商事件識別碼去重;否則,根據合適的事件欄位定義並測試指紋,同時注意該指紋可能需要因應你的資料作出調整。
以 Webhook 為主導的整合亦可使用受控取得操作進行核對。例如,復原工作可以檢查受接收器故障影響的記錄。這是復原能力模式,不代表可以忽略速率限制或供應商特定指引。
6. 將追蹤資料轉化為安全的業務操作
在觸發面向客戶的操作前,先更新內部貨件記錄。持久保存通知及工作流程轉換記錄,避免重複事件產生重複訊息。
將業務操作對應至有意義的變更,而不是每次 API 回應。新觀察到的送達事件可能足以觸發送達通知,但包含相同事件的重複回應則不應觸發。異常可能需要內部審查,但發給客戶的訊息應反映事件實際所述的內容。
定義如何處理在貨件被視為完成後才收到的事件。不要因摘要已達到終止狀態,便刪除事件歷史或永久封鎖所有後續更新。保留、核對及通知規則應容許合理更正,同時避免反覆重新開啟已完成的工作流程。
將工作流程應用於 17TRACK 整合
對於自訂追蹤整合,相關起點是17TRACK Tracking API 頁面及其開發者文件。使用產品頁面評估服務,並使用文件確立實際整合合約。消費者追蹤頁面不能取代 API 規格。
在編寫轉接器前,確認驗證格式、註冊及取得操作、承運商識別規則、項目層級回應處理方式及適用的請求限制。對於基於 Webhook 的處理,亦應確認有效載荷結構、驗證流程、確認接收要求及重試行為。
將這些供應商特定的細節保留在轉接器內,而不是將對回應欄位的假設分散到整個訂單系統。這樣,應用程式其他部分便可使用註冊結果、貨件狀態、事件歷史及上次成功同步等內部概念。
可避免高昂錯誤的上線前檢查
- 已接受但記錄為空:介面顯示追蹤資料待提供,而不是包裹正在移動。
- 批次結果不一致:每件貨件均獲保存各自的結果。
- 提交後逾時:工作程序會核對不確定結果,而不是直接假設失敗。
- 重複事件:貨件時間線及客戶通知均保持去重。
- 較早事件後來才收到:保留該事件,不盲目取代較新的摘要。
- 上游服務不可用:客戶頁面可顯示上次儲存的結果,並提供適當的新鮮度提示。
- 承運商對應錯誤:記錄可透過文件所述的復原途徑修正。
- 拆分訂單:每個包裹保留自己的追蹤狀態及事件歷史。
- 憑證或有效載荷外洩:日誌包含診斷參考,但不洩露機密或不必要的個人資料。
實際完成標準不只是收到成功的註冊回應,而是能夠追蹤包裹由提交至更新的完整過程,解釋空白或失敗結果,並在處理中斷時復原,同時避免遺失事件或重複執行客戶操作。
常見問題
註冊追蹤號碼會建立貨件嗎?
按照本指南所述的流程,不會。追蹤註冊是將現有識別碼提交至追蹤服務。除非特定 API 明確將這些功能合併,否則建立標籤、購買郵資及預約承運商服務都是獨立操作。
為甚麼註冊成功後追蹤詳情仍然為空?
註冊接受與追蹤資料可用是兩種不同條件。承運商可能尚未記錄事件,或者需要檢查追蹤號碼、承運商對應或額外查詢資料。在將記錄視為成功註冊前,請檢查項目層級結果。
每次取得狀態時都應註冊貨件嗎?
不要將重複註冊作為預設的更新機制。儲存已接受的註冊狀態,並使用文件所述的取得或更新機制。按照供應商對更正、重新啟用或重複提交的明確規則操作。
應使用輪詢還是 Webhook?
使用符合文件所述 API 合約及營運要求的機制。輪詢需要受控的請求時間表;Webhook 需要安全、持久的接收器及可安全處理重複訊息的機制。在支援的情況下,Webhook 更新配合針對性核對,可以提供實用的復原途徑。
可以將追蹤號碼作為資料庫唯一的貨件識別碼嗎?
應使用內部貨件識別碼。將追蹤號碼及相關承運商內容作為該記錄的屬性儲存。這樣即使遇到拆分訂單、追蹤號碼更正及供應商特定參考,也能更容易管理,而無需更改內部貨件的身份。
資料來源
- 17TRACK Tracking API — 用於評估 17TRACK API 整合的官方產品入口。
- 17TRACK API 文件 — 有關實作特定請求格式、操作、回應及整合要求的官方參考。本文中的虛擬碼及內部欄位建議是應用程式設計範例,並非對此 API 合約的引述。


