一. 什麼是物流追踪
物流追蹤是了解物流運輸過程的一種服務能力，透過該服務可以監測運輸路線、異常情況和重要的狀態變化。
Tracking API 的主要功能如下：
一次訂閱自動追蹤並推送查詢結果，期間不再扣費（非同步接口，不建議使用在前台網頁、小程式、APP中）。
企業級的資料處理能力，每小時可訂閱 40萬個物流單號。
整合全球 2000+ 運輸商，統一的呼叫方式、回應結構、狀態節點，進而降低開發成本。
強烈建議在您的伺服器或儲存服務中保留物流資訊。
資料的唯一識別碼透過物流單號 + 運輸商組合實現。
運行流程概述：訂閱單號 >> 服務定時追蹤 >> 服務檢查變更 >> 推播結果
二. 使用前必備事項
2.1 建立 17TRACK 帳號
API 帳號不區分使用環境，建議測試和生產帳號分開使用。請造訪 17TRACK - Api 開通帳號。
2.2 物流單號和運輸商代碼
準備好的物流單號，可以訪問 17TRACK - 全球物流查詢平台 進行驗證。
可以存取 運輸商清單 查看已整合的運輸商。
什麼是運輸商代碼？運輸商代碼是專為使用 Tracking API 制定參數規範，請參考 運輸商代碼。舉例：USPS的運輸商代碼 是 21051
三. 對接指引
3.1 自研系統對接方案
使用者畫像
頭部物流商、頭部商家、服務商、系統商
第一步
（若只是簡單驗證，可使用 https://webhook.site 驗證推送效果）
請確認伺服器能被公網存取（防火牆、閘道等設定已完成調整）。
請完成接收訊息的介面開發，確認介面能承受高併發的訪問，建議有獨立服務來分發資料（如：佇列、快取等）。
在接收資訊介面中完成簽章驗證邏輯，以確保資訊來源安全有效。請參考 驗證簽章流程，範例程式碼如下：
/**
* requestText {String} 原始通知報文
* key {String} 金鑰
* return {String} 產生簽章內容
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {
String src = requestText + "/" + key;
MessageDigest md = MessageDigest.getInstance("SHA-256");
byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));
BigInteger number = new BigInteger(1, hash);
StringBuilder hexString = new StringBuilder(number.toString(16));
while (hexString.length() < 64) {
hexString.insert(0, '0');
}
return hexString.toString();
}
第二步
取得金鑰，請登入 存取 API 設定頁 Api-設置
設定接收資訊接口，請登入 存取 API 設定頁 Api-設置，在 WebHook 區域填入接口 URL。
第三步
呼叫註冊介面（/register）訂閱物流單號，建議把業務系統中資料 ID 透過 tag 傳入，以方便接收推送結果後使用。 （介面參考：註冊物流單號）
第四步
監聽接收訊息介面運作情況，為確保追蹤結果及時有效的被業務使用，要注意：推送可能是持續的並發狀態， 每次推送是全量數據，若無法正常接收時臨時返回非200 狀態碼，17側補償推送請參考這裡推送策略，如果找不到追蹤結果，有可能是以下幾種情況：
正在跟踪需要等待。 （正常情況下首次抓取在 1 分鐘內會有結果，後續每 24 小時抓取 3~4 次直到簽收）
檢查物流單號，如果有錯誤，請呼叫刪除單號介面 (/deletetrack)，再重新訂閱。
檢查運輸商，如果有錯誤，請呼叫修改運輸商介面 (/changecarrier)處理。
有可能是因為運輸商介面異常導致未回傳資料。
有可能是運輸商未更新資料（未上網）。
有可能是部分頻道訂閱時未填附加追蹤參數，如：手機尾號、郵編等。
有可能是連續 30 天運輸商未更新資料系統將停止自動追蹤。
3.2 第三方系統商對接方案
使用者畫像
中小型物流商、中型商家
系統產品：ERP、TMS、WMS、CRM等
第一步
（若只是簡單驗證，可使用 https://webhook.site 驗證推送效果）
請系統商確認，目前所使用的系統可支援 Webhook 方式接收推播追蹤資料。 [區別於自研系統]
請系統商確認，如果不支援推送，是否支援備選方案：透過呼叫取得詳情介面 (/gettrackinfo) 定時拉取資料。 （此方式不能保證與推送方式一樣的資料回傳效率，也是17不建議的方式。）[區別於自研系統]
請系統商確認，是否支援17TRACK API接取使用？如支援則要確認目前的接取版本是否能滿足業務需要，如不能則要與系統商協商選擇版本再接取。 [區別於自研系統]
如果支援推送，那麼在接收資訊介面中完成簽章驗證邏輯，以確保資訊來源安全有效。請參考 驗證簽章流程，範例程式碼如下：
/**
* requestText {String} 原始通知報文
* key {String} 金鑰
* return {String} 產生簽章內容
*/
private String getGeneratedSignature(String requestText, String key) throws NoSuchAlgorithmException {
String src = requestText + "/" + key;
MessageDigest md = MessageDigest.getInstance("SHA-256");
byte[] hash = md.digest(src.getBytes(StandardCharsets.UTF_8));
BigInteger number = new BigInteger(1, hash);
StringBuilder hexString = new StringBuilder(number.toString(16));
while (hexString.length() < 64) {
hexString.insert(0, '0');
}
return hexString.toString();
}
第二步
取得金鑰，登入 API 控制台，在設定頁取得金鑰並將金鑰交給系統商負責接取業務的服務人員。 （請造訪 Api-設定）[區別於自研系統]
若係統商不支援推送方式則跳過此步驟。若支援請聯絡系統商提供推送介面(URL)。 （請造訪 Api-設定）[區別於自研系統]
第三步
建議客戶讓系統商在呼叫註冊介面（/register）訂閱物流單號時，把業務系統中資料 ID 透過 tag 傳入，以方便接收推送結果後使用。 （介面參考：註冊物流單號）[區別於自研系統]
第四步
請客戶登入所使用的系統，在物流追蹤板塊查看抓取情況（具體請系統商客服來支援和解答）。 [區別於自研系統]
監聽接收訊息介面運作情況，為確保追蹤結果及時有效的被業務使用，要注意：推送可能是持續的並發狀態， 每次推送是全量數據，若無法正常接收時臨時返回非200 狀態碼，17側有補償推送請參考這裡推送策略，如果找不到追蹤結果，有可能是以下幾種情況：
正在查詢中需要等待。 （正常情況下首次抓取 1 分鐘內會有結果，後續每 24 小時抓取 3~4 次直到簽收）
檢查物流單號，如果錯誤請刪除單號重新訂閱。
檢查運輸商，如果指定錯誤，請呼叫修改運輸商介面(/changecarrier)處理。
有可能是因為介面異常運輸商未回傳資料。
有可能是運輸商未更新資料（未上網）。
有可能是部分頻道訂閱時未填附加追蹤參數，如：手機尾號、郵編等。
有可能是連續 30 天運輸商未更新資料系統自動停止追蹤。
四. 版本說明
主版本
差別
V1.0
V2.0 (2022年5月)
請求地址
https://api.17track.net/track/v1
https://api.17track.net/track/v2
註冊介面(/register)簡化自動識別操作
生效方式：
{
carrier : null ,
auto_detection : true
}
生效方式：
預設開啟
簡化簽名驗證
通知類型+/+提取推播報文data內容 + / + 金鑰
推播報文 + / + 金鑰
報文結構化+節點語意化
無
有
獨立查詢附加參數
無，與物流單號拼接使用，理解複雜
有
豐富運送/目的地資訊
無
有，如：國家簡碼、州、市、郵編、街道等。
時效資訊
無
有，訂單時長、運送時長。
物流狀態數量
7個
增加到9個主狀態，27個子狀態
包裹附屬資訊
無
重量、體積等（需運輸商支援）
運輸商資訊
無
增加名稱、別名、官方電話、官網等。
物流軌跡翻譯
無
有，支援 8 種語言
子版本
v2.1（上線時間 2023年8月）更新內容：
增加 3 個清關子狀態，
增加事件狀態節點。
註冊接口支援訂單編號和備註參數。
取得清單介面增加訂單編號、時效等資訊回傳。
v2.2（上線時間 2023年10月）更新內容：
增加物流事件發生時間的原始資訊結構。