UPS Tracking API：入門指南

UPS Tracking API 讓企業擷取貨件狀態，並在自己的網站、應用程式、訂單管理系統或客戶服務工具內顯示派送更新。開始使用通常包括建立 UPS 開發者帳戶、註冊應用程式、取得驗證憑證、發送追蹤請求，以及將回應轉換成對客戶有用的事件。本指南會在不假設你具備 API 使用經驗的前提下，解釋整個流程。

範例會集中介紹追蹤，而不是標籤建立、報價或地址驗證。UPS 維護獨立的 API 產品及文件，因此在建立生產環境流程前，請確認你註冊的應用程式可使用所需的追蹤功能。

UPS Tracking API 的作用

API 是一種結構化方式，讓一個軟件系統向另一個系統請求資料。在追蹤流程中，你的系統會向承運商或追蹤平台發送貨件識別碼，例如追蹤號碼。服務會返回貨件資料，當中可能包括目前狀態、狀態描述、位置資料、日期及包裹里程碑，具體取決於服務、貨件，以及請求當時可用的回應欄位。

這些資料可以支援多項實際功能：

• 嵌入電子商店的追蹤頁面。
• 在訂單管理或企業資源規劃系統內查看貨件狀態。
• 客戶服務畫面，減少手動查閱承運商網站的需要。
• 針對派送異常、延誤或已完成派送的內部提示。
• 根據貨件事件發送的購買後訊息。

API 不會取代你的應用程式邏輯。你仍然需要決定多久請求一次更新、如何儲存回應、如何處理不完整資料，以及如何向客戶解釋承運商狀態。

UPS Tracking API 與 UPS 網站的比較

UPS 網站是為使用者輸入追蹤號碼並閱讀結果而設計。API 則是為軟件而設計。當追蹤資訊需要自動顯示在另一個系統，或觸發內部流程時，API 便十分有用。

這項區別十分重要，因為 API 整合會帶來手動查詢沒有的責任。你的團隊必須保護憑證、驗證使用者輸入、適當記錄請求及回應、處理暫時性故障，並監察承運商平台變更後整合是否仍然正常運作。

UPS 開發者平台是了解目前註冊及技術要求的合適起點。其文件應優先於較舊的教學、程式碼範例或論壇文章，因為驗證方式、API 版本、所需標頭及產品存取規則都可能改變。

發出請求前需要準備的事項

在編寫整合程式前，請準備以下項目：

1. UPS 開發者帳戶。 使用官方 UPS Developer Portal 查看可用 API 並建立應用程式。
2. 應用程式憑證。 準確的憑證名稱及驗證流程應以最新 UPS 文件為準。不要將用戶端密碼放入瀏覽器程式碼、流動應用程式、公開程式碼庫或客戶可見頁面。
3. 用於測試的有效追蹤號碼。 請使用你的機構獲授權存取的貨件進行測試，並避免在日誌中披露個人或商業貨件資料。
4. 伺服器端整合點。 後端服務通常比從公開網頁直接呼叫承運商更安全，因為它可以保護憑證私密性並控制請求量。
5. 回應儲存方案。 決定需要哪些欄位、保留資料多久，以及如何將承運商事件與內部訂單關聯。

適合初學者的整合流程

1. 確認業務需求

首先定義你的產品中的「追蹤」代表甚麼。面向客戶的頁面可能只需要目前狀態及預計派送資料。倉庫或支援儀表板可能還需要掃描記錄、時間戳記、異常描述及原始追蹤號碼。

不要在沒有理由的情況下請求所有可用欄位。較小的資料模型更容易維護，也較不容易披露使用者不需要的資訊。

2. 註冊應用程式

按照目前平台指示，在 UPS 開發者環境中建立應用程式並選擇相關追蹤產品。安全地記錄應用程式識別碼。如果 UPS 要求在生產環境存取前完成審批、帳戶關聯或其他設定，請在承諾正式上線日期前完成這些步驟。

如果平台支援，請為測試及生產環境保留獨立的憑證及設定。這樣可降低測試指令碼影響實際流程的機會。

3. 實作驗證

驗證可證明你的應用程式獲准呼叫服務。請按照最新 UPS 文件所示的驗證方式、權杖端點、範圍要求及標頭格式操作。將存取權杖視為臨時機密，不要將其寫入應用程式日誌。

合理的實作會只在需要時請求權杖，在獲准的有效期內重用權杖，並在權杖過期後取得新的權杖。你的程式碼亦應區分驗證失敗與追蹤號碼錯誤。兩者的處理方式不同：前者需要檢查憑證或設定，後者可能需要驗證輸入。

4. 發送追蹤請求

完成驗證後，使用 UPS 指定的追蹤操作及識別碼格式發送請求。確切的 URL、HTTP 方法、標頭及回應結構，應以你選用的 API 版本官方文件為準。

概念上的請求如下：

POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "trackingNumber": "YOUR_TRACKING_NUMBER"
}

這是一個學習範例，不是可直接複製到生產環境的請求。請以目前 UPS API 參考文件中的值取代操作名稱、端點、標頭及本文。有些 API 會使用路徑參數或不同的請求結構。

5. 正規化回應

承運商回應未必以客戶預期的語言撰寫。請建立包含以下穩定欄位的內部事件模型：

• 內部訂單或貨件 ID。
• 承運商名稱及追蹤號碼。
• 最新承運商狀態代碼及原始描述。
• 應用程式使用的正規化狀態。
• 事件時間戳記，以及在有提供時的位置。
• 上次成功更新時間。

在可能的情況下保留原始承運商狀態。對客戶介面而言，「運送途中」等正規化標籤很有用，但原始描述可以協助支援人員調查異常事件。

6. 決定如何取得更新

有些系統會使用定時輪詢：後端按指定時間間隔檢查符合條件的貨件並儲存變更。其他系統則會在相關平台支援時使用事件通知。不要假設每個 UPS 追蹤產品都提供相同的通知機制。設計以 webhook 為基礎的流程前，請確認最新文件及商業條款。

輪詢應具選擇性。最近寄出或正在運送中的包裹，可能比已派送或已取消的貨件更值得頻繁檢查。針對暫時性故障使用帶退避的重試，遵守文件所述限制，並在終止狀態後停止不必要的請求，除非你的業務流程需要稍後再次確認。

常見錯誤及處理方式

最重要的使用者體驗原則，是不要將缺失資料轉換成肯定結論。「沒有新掃描」不等於「遺失」，而「已建立標籤」也不一定代表「運送途中」。請仔細對應狀態，並讓支援團隊清楚看到異常處理情況。

何時多承運商 API 會更合適

當你的貨件主要由 UPS 處理，而團隊希望直接控制承運商連線時，直接整合 UPS 可能是合理選擇。取捨在於，每增加一個承運商，可能就需要另一套驗證模式、資料結構、錯誤政策及維護流程。

如果你的業務使用多個承運商，多承運商服務可以減少獨立整合的數量。17TRACK's Tracking API 專為基於應用程式的貨件追蹤而設計，而其官方開發者文件則說明可用的整合模式。當實際需求不只是 UPS 追蹤，而是跨承運商的一致追蹤層時，這項服務值得評估。

這並不代表應自動取代直接的 UPS 連線。請比較所需的承運商覆蓋範圍、事件詳細程度、資料保留要求、驗證模式、營運限制、支援流程及整體實作工作量。服務提供者的公開文件應被視為技術概念驗證的起點，而不是代替測試你自己的貨件模式。

生產環境準備清單

• 憑證儲存在密碼管理服務中，且從不暴露給瀏覽器。
• 測試及生產環境清楚分開。
• 請求設有逾時、受控重試及有用的錯誤日誌。
• 追蹤號碼在發送前已經驗證。
• 系統會儲存上次成功更新，並避免以空回應覆蓋該資料。
• 原始承運商訊息及面向客戶的標籤分開處理。
• 輪詢頻率符合服務提供者公布的限制及你的營運需要。
• 監察機制可以偵測驗證失敗、錯誤率上升及長時間沒有更新的貨件。
• 支援人員可以查看足夠詳細資料，以調查客戶問題。
• 當 UPS 更改文件、憑證、端點或回應欄位時，會重新測試整合。

從一條完整路徑開始：完成驗證、追蹤一件測試貨件、儲存回應、顯示簡單狀態，以及處理失敗。只有在這條路徑可靠後才逐步擴展。相較於在了解底層資料及錯誤行為前，先建立大型面向客戶的追蹤體驗，這種方式通常更安全。

常見問題

如果我只追蹤幾件包裹，是否需要 API？

通常不需要。偶爾查詢時，直接在承運商網站手動追蹤可能更實際。當追蹤成為可重複的流程，或必須顯示在另一個應用程式內時，API 才更有價值。

我可以從 Shopify 主題或瀏覽器呼叫 UPS Tracking API 嗎？

直接從瀏覽器呼叫可能會暴露憑證，亦令請求控制變得困難。伺服器端服務或已建立的追蹤整合通常更安全。請在最新 UPS 文件中確認技術要求及獲准的架構。

追蹤 API 會建立運輸標籤嗎？

不一定。追蹤、標籤建立、報價、地址驗證及其他物流功能可能屬於不同的 API 產品。請選擇符合所需操作的產品。

為甚麼有效的追蹤號碼可能只返回少量資料？

包裹可能尚未完成首次掃描，資料可能仍未可用，或者請求不符合 API 所需格式或存取權限。請將空回應或有限回應視為需要調查的狀態，而不是貨件遺失的證明。

我應直接選擇 UPS，還是選擇多承運商追蹤 API？

當 UPS 是主要承運商，而你希望進行專注的整合時，請選擇直接連線。當你的營運目標是在多個承運商之間建立一套追蹤流程時，請考慮多承運商服務。在作出最終決定前，先測試所需承運商及各種事件情境。

資料來源

• UPS Developer Portal
• UPS Tracking API documentation and product resources
• 17TRACK Tracking API
• 17TRACK API documentation