如何使用 UPS 追蹤 API：逐步設定指南

要使用 UPS Tracking API，請建立 UPS Developer 帳戶、註冊應用程式、取得 OAuth 2.0 憑證、請求存取權杖，並使用有效的 UPS 追蹤號碼傳送經驗證的追蹤請求。入口網站中的確切標籤、審批步驟及 API 要求可能會更改，因此在正式啟用生產整合前，請先在官方 UPS Developer Portal 確認目前的指引。

本指南適用於需要在網上商店、訂單管理系統、倉庫工作流程、客戶服務工具或內部儀表板中顯示貨件狀態的開發人員及電子商貿營運團隊。本指南重點介紹整合流程、影響可靠性的決策，以及避免常見追蹤失敗的檢查項目。

UPS Tracking API 的功能

API 整合讓軟件可以向 UPS 請求貨件資料，無需員工或客戶手動開啟承運商的追蹤頁面。你的應用程式可以使用回應來顯示最新已知狀態、識別派送事件、支援客戶服務調查，或觸發內部工作流程。

API 與追蹤頁面並不相同。追蹤頁面是為人員閱讀而設計；API 回應則是軟件需要解析、儲存及呈現的結構化資料。你的系統仍需負責驗證、錯誤處理、輪詢或事件收集、資料保留、使用者介面設計，以及圍繞派送事件建立的任何業務規則。

開始之前

開啟開發人員入口網站前，請準備以下項目：

• UPS Developer 帳戶，或目前 UPS 開戶流程所要求的帳戶類型。
• 已註冊的應用程式，以及為該應用程式發出的憑證。
• 測試追蹤號碼或其他獲批准的測試方法。如果 UPS 文件提供獨立的測試環境或測試程序，請勿使用實時客戶資料開始測試。
• 清楚決定由哪個系統管理貨件記錄、追蹤事件及面向客戶的狀態訊息。
• 安全儲存用戶端憑證及存取權杖的位置。切勿將機密資料放入瀏覽器程式碼、公開儲存庫、螢幕截圖或使用者可以檢查的流動應用程式中。

你亦應決定應用程式是否只需要追蹤功能，還是需要更廣泛的 UPS 整合。追蹤、報價、運送、地址驗證及文件服務可能採用不同的產品、權限、請求格式及營運要求。

第 1 步：開啟 UPS Developer Portal

請從官方 UPS Developer Portal開始。查看目前的 API 目錄、驗證指引、開戶要求、條款及環境資料。請特別尋找 Tracking API 文件，不要假設其他 UPS 服務的指引同樣適用於追蹤功能。

入口網站是目前請求欄位、授權範圍、回應定義、速率限制、錯誤代碼及環境詳情的適當來源。這些詳情可能會更改，而第三方程式碼範例可能使用較舊的 UPS 介面或過時的驗證方法。

第 2 步：註冊應用程式

在開發人員入口網站中建立應用程式，並選擇應用程式實際需要的 UPS API。對於只需要追蹤功能的項目，除非工作流程需要其他服務，否則只請求追蹤能力。限制權限可以減少配置複雜程度，並讓日後的故障排除更容易。

請將應用程式識別碼及密鑰記錄在伺服器端密鑰管理工具或受保護的環境變數系統中。請將密鑰視為密碼處理。如果密鑰外洩，請按照 UPS 提供的流程輪換密鑰，並檢查日誌是否存在未經授權的使用。

如果入口網站要求提供帳戶、帳單、業務或應用程式資料，請提供準確資訊。不要為了完成測試而捏造生產用途或使用他人的帳戶資料。服務存取權可能取決於帳戶配置及 UPS 當前的審批流程。

第 3 步：實作 OAuth 2.0 驗證

目前的 UPS 開發人員文件對其 API 使用基於 OAuth 的驗證。你的伺服器通常會按照文件所述的權杖流程交換應用程式憑證，並接收存取權杖，然後在 API 請求的授權標頭中加入該權杖。

請將驗證與追蹤邏輯分開。一個實用的設計是由一個元件取得及快取有效權杖，另一個元件呼叫追蹤端點。權杖元件應該：

• 只向文件所述的 UPS 授權端點傳送憑證。
• 使用目前 UPS 文件指定的內容類型及授權類型參數。
• 暫時儲存權杖，並在其到期前重複使用，而不是為每個追蹤號碼請求新權杖。
• 在文件所述的到期條件出現時更新或重新取得權杖。
• 從應用程式日誌、錯誤報告及支援工單中遮蓋憑證及權杖。

不要將瀏覽器工作階段中的權杖複製到永久整合中。後端服務通常是管理憑證較安全的位置，因為它可以讓機密資料遠離公開用戶端程式碼。

第 4 步：建立追蹤請求

請使用官方 Tracking API 參考文件所示的請求格式。典型請求包括路徑或請求參數中的追蹤號碼、授權標頭中的存取權杖，以及 UPS API 要求的標頭。不要假設追蹤號碼是唯一必需值：目前的參考文件可能指定版本、交易、內容類型或相關性標頭。

簡化的請求模式如下：

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

這是結構範例，不是可直接複製貼上的端點。請使用 UPS 文件為你的應用程式發布的端點、版本、標頭及參數名稱。請根據你自己的訂單資料規則將追蹤號碼標準化，但除非承運商文件確認這樣做安全，否則不要移除任何字元。

第 5 步：將事件解析至你的資料模型

承運商回應通常包含比單一狀態標籤更多的資訊。在編寫面向客戶的頁面前，請將回應映射至內部模型，例如貨件識別碼、承運商、最新狀態、事件代碼、事件描述、事件時間戳記、位置、預計派送資料，以及可用時的派送完成時間戳記。

在你的保留及私隱政策允許的情況下，保留原始承運商回應。原始回應有助於診斷映射錯誤，或解釋為何你的標準化狀態與承運商的措辭不同。同時，除非附有易於閱讀的說明，否則避免向客戶顯示技術性事件代碼。

不要將每個狀態都視為最終派送結果。例如，運送中事件、例外情況、派送嘗試及已派送事件，不應合併為相同的客戶訊息。建立明確映射，並定義當 UPS 新增你的程式碼無法識別的事件值時應如何處理。

第 6 步：加入重試、驗證及監控

生產整合不只是開發人員主控台中的一次成功請求。請加入驗證及營運保障措施：

• 輸入驗證：在傳送請求前拒絕空白、格式錯誤或明顯不完整的追蹤號碼。
• 逾時：避免緩慢的承運商回應阻塞整個結帳、支援或倉庫工作流程。
• 重試規則：以退避方式謹慎重試暫時性的網絡或服務故障。不要反覆重試驗證錯誤或無效追蹤號碼。
• 速率意識：遵守 UPS 文件中的限制及使用規則。在業務流程允許的情況下，快取最近的結果。
• 未知狀態：保留無法識別的事件以供檢查，不要錯誤地將其標記為已派送或遺失。
• 可觀測性：記錄請求時間、回應類別及相關性資料，但不要記錄機密資料或不必要的個人資料。

追蹤系統亦應定義重新整理貨件的頻率。過於頻繁的輪詢可能造成可避免的負載，而且未必能產生新資訊；輪詢過少則可能令面向客戶的頁面顯得過時。請根據貨件量、營運緊急程度、承運商規則及使用者實際需要的新鮮度選擇間隔。

第 7 步：使用實際情境進行測試

測試內容不應只有成功派送的貨件。請包括未知追蹤號碼、運送中的貨件、例外情況、包含多個事件的貨件、已過期權杖、逾時、授權失敗，以及包含解析器未預期欄位的回應。如果 UPS 提供獨立的測試環境或測試憑證，請先遵循相關程序。

檢查從請求到使用者介面的完整流程。確認正確的訂單收到正確的貨件、時間戳記以預定時區顯示、重複事件不會建立重複的客戶訊息，以及承運商中斷不會以誤導性文字覆寫先前有效的狀態。

何時多承運商追蹤 API 更適合

當你的業務主要使用 UPS 運送，並需要密切控制承運商工作流程時，直接整合 UPS 可能合適。但當訂單可能經由多個承運商、網上平台、郵政營運商或地區配送公司運送時，直接整合會變得不便。在這種情況下，獨立的憑證、回應格式、狀態詞彙及重試規則可能增加維護工作。

對於需要跨多個承運商追蹤的應用程式，多承運商服務，例如17TRACK Tracking API，可以提供另一種整合模式。你應直接查看其開發人員文件，了解支援的承運商、請求格式、驗證方式、使用條款及可用功能。這並不代表它必然比直接連接 UPS 更好：正確選擇取決於承運商組合、資料要求、對整合的控制程度，以及商業或合規限制。

如果是面向消費者的查詢，而不是開發人員整合，17TRACK 的追蹤頁面可能比建立 API 連接更合適。對於需要品牌化售後更新的網上商店，請另外查看相關平台整合，而不要加入商店並不需要的 API 工作。

常見實作錯誤

• 使用過時範例：程式碼範例可能涉及已停止使用的版本、舊驗證方法或不同的 UPS 服務。
• 將機密資料放入前端程式碼：傳送至瀏覽器的任何內容都應視為可被檢查。
• 假設空白結果代表沒有貨件：在得出業務結論前，請核對追蹤號碼、帳戶權限、環境及回應訊息。
• 只映射文字：狀態描述可能有所不同。請使用文件記載的代碼，並保留未知值以供檢查。
• 忽略帳戶及使用要求：技術程式碼可能正確，但應用程式未必已配置為使用所請求的服務。
• 沒有業務規則地重新整理：不必要的輪詢可能增加成本、負載及營運噪音，卻無法改善客戶體驗。

實用的正式啟用檢查清單

1. 確認應用程式使用目前的 UPS 文件及獲批准的環境。
2. 確認憑證儲存在伺服器端，並可以輪換。
3. 測試驗證失敗、承運商錯誤、格式錯誤輸入及逾時。
4. 將標準化狀態與代表性貨件的原始回應進行比較。
5. 設定重新整理政策並監控請求量。
6. 為未識別事件、延遲更新及客戶升級個案定義負責方。
7. 記錄整合內容，讓其他開發人員可以安全地更新憑證、端點版本及狀態映射。

常見問題

使用 Tracking API 是否需要 UPS 帳戶？

你應在 Developer Portal 查看目前 UPS 的開戶及存取要求。API 存取權可能取決於應用程式註冊、憑證、帳戶配置及所請求的特定服務。不要假設公開追蹤頁面的登入資料可以取代開發人員 API 存取權。

UPS Tracking API 是否免費？

不要假設 API 存取沒有商業或使用條件。UPS 會透過官方渠道發布目前的服務及帳戶資料，而部分要求可能取決於產品、帳戶或協議。在規劃生產預算前，請直接確認適用條款。

可以直接從瀏覽器中的 JavaScript 呼叫 UPS API 嗎？

基於瀏覽器的呼叫可能會暴露應用程式憑證，並造成跨來源、安全性及使用控制問題。伺服器端整合通常是較安全的做法，可用於儲存機密資料、取得權杖、套用重試規則及限制貨件資料的存取。

應用程式應多久請求一次追蹤更新？

請根據承運商文件所述的限制、貨件量、營運緊急程度及使用者所需的新鮮度制定重新整理政策。在適當情況下快取最近的結果，暫時故障後使用退避，並避免將重複輪詢視為取代文件所述事件或通知功能的方法。

應該使用直接 UPS 整合，還是多承運商 API？

直接 UPS 整合可能適合需要承運商特定控制的 UPS 為主工作流程。當貨件使用多個承運商時，多承運商 API 可能減少整合數量。選擇前，請比較支援的承運商、驗證方式、資料欄位、可靠性要求、使用條款及實作工作量。

來源

• UPS Developer Portal — 官方 API 目錄、應用程式存取、驗證及開發人員文件。
• UPS Technology Integration — 有關將 UPS 技術與業務系統整合的官方資料。
• 17TRACK Tracking API — 多承運商追蹤的官方產品及開發人員入口。
• 17TRACK API Documentation — 有關驗證、請求及回應處理的官方 API 文件。