Fedex Tracking Api：如何逐步追蹤包裹

要透過應用程式追蹤 FedEx 包裹，請建立 FedEx Developer 帳戶、取得 API 憑證、要求 OAuth 存取令牌、提交追蹤請求，並將回應映射至你的訂單或貨件工作流程。FedEx Tracking API 適用於需要貨件狀態資料的軟件系統，而 FedEx 網站通常更適合手動查詢單件包裹。

本指南說明整合流程、需要驗證的資料、常見實作錯誤，以及一個適合需要多承運商追蹤而非僅連接 FedEx 的企業的替代方案。在部署至生產環境前，始終應根據最新的 FedEx 文件確認確切的請求欄位、驗證規則、環境及服務可用性。

先選擇合適的追蹤方式

最佳方法取決於由誰採取行動，以及需要監控多少件貨件。

• 單次查詢：當客戶或支援人員只需要查詢單件貨件時，使用 FedEx 追蹤頁面。
• 內部應用程式：當訂單管理系統、倉庫應用程式、客戶入口網站或支援工具需要以程式方式取得狀態資料時，使用 FedEx Tracking API。
• 多承運商運作：當企業接收來自 FedEx 及其他承運商的貨件，並希望使用一個標準化整合、一套狀態模型或一個面向客戶的追蹤體驗時，請考慮使用追蹤平台。

僅限 FedEx 的 API 整合可提供直接控制，並可能適合以 FedEx 貨件為核心建立的系統。但這亦意味着你的團隊必須自行管理驗證、請求限制、回應變更、承運商特定的狀態邏輯、錯誤處理，以及任何額外的承運商整合。

使用 FedEx Tracking API 前需要準備的資料

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

• FedEx Developer 帳戶，以及 FedEx developer portal 的存取權。
• 所選 FedEx 環境所需的 API 憑證。FedEx 文件可能會將憑證稱為 client ID 和 client secret。
• 如果所選 API 操作需要，請準備 FedEx 帳戶關係或其他帳戶資料。
• 用於存放憑證的安全伺服器端位置。不要在瀏覽器 JavaScript、流動應用程式或公開儲存庫中公開 client secret。
• 至少一個有效的貨件識別碼供測試使用，例如 FedEx tracking number。測試資料應代表你的應用程式將處理的貨件類型及服務。
• 儲存最後已知狀態、事件時間戳記、位置資料，以及最近一次成功查詢時間的方案。

FedEx 將開發者存取權、驗證、API 環境及營運要求分開處理。成功登入 developer portal 本身並不代表已準備好發出生產請求。請查閱最新產品文件，確認帳戶先決條件、審批要求、環境 URL 及任何使用限制。

步驟 1：在 FedEx developer portal 建立應用程式

從官方 FedEx Developer Portal 開始，並找出 Track API 產品。建立或選擇一個應用程式，然後記錄你打算使用的環境所提供的憑證。請將開發環境和生產環境的憑證分開。

在此階段，確認以下四項資料：

1. 哪個 API 產品包含你需要的追蹤操作。
2. 哪個基礎 URL 屬於測試或生產環境。
3. 需要哪種驗證方法及 scope（如有）。
4. 請求是否需要 FedEx 帳戶號碼或其他帳戶層級欄位。

在確認最新文件前，不要直接複製舊程式碼範例中的 URL 或欄位名稱。承運商 API 可能會變更端點版本、必要標頭、回應結構或註冊規則。

步驟 2：要求 OAuth 存取令牌

FedEx API 通常使用 OAuth 2.0 client credentials 進行驗證。你的應用程式會將 client credentials 傳送至 FedEx 授權端點，並接收一個短期有效的存取令牌。之後，應用程式會在追蹤請求的 Authorization 標頭中傳送該令牌。

簡化的命令列範例如下：

curl -X POST "<FEDEX_OAUTH_URL>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>"

請將此視為實作模式，而不是取代最新 FedEx 驗證文件的方案。生產程式碼應讀取令牌到期值、安全地快取令牌，並在令牌到期或 API 回傳驗證失敗時要求新的令牌。除非官方限制及你的流量模式確實需要，否則避免為每個追蹤號碼都要求新令牌。

有用的驗證安全措施包括：

• 將密鑰儲存在伺服器端密鑰管理器或受保護的環境變數中。
• 絕不要將存取令牌或 client secret 寫入應用程式日誌。
• 在平台支援的情況下，為開發環境和生產環境使用不同的憑證。
• 驗證失敗時向用戶返回受控錯誤；不要公開承運商的原始回應。
• 將令牌失敗與無效追蹤號碼失敗分開監控。

步驟 3：建立追蹤請求

取得有效令牌後，根據最新 FedEx Track API 文件建立請求。請求通常會識別一個或多個貨件記錄，並可包含影響所返回詳細資料的選項。確切的 JSON 屬性名稱及必要欄位必須以你所使用的 FedEx 端點版本為準。

代表性的請求模式如下：

curl -X POST "<FEDEX_TRACK_BASE_URL>/track/v1/trackingnumbers" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingInfo": [
      {
        "trackingNumberInfo": {
          "trackingNumber": "<FEDEX_TRACKING_NUMBER>"
        }
      }
    ],
    "includeDetailedScans": true
  }'

使用前，應根據即時 FedEx 文件核對上述端點路徑及欄位名稱。某些整合可能需要不同的請求格式、帳戶號碼、以參考資料為基礎的查詢，或其他詳細掃描選項。不要假設屬於其他承運商的追蹤號碼可以傳送至僅限 FedEx 的端點。

步驟 4：將回應解析為業務欄位

不要直接將完整的承運商回應傳送至面向客戶的頁面。首先，將其映射至穩定的內部模型。實用的貨件記錄可能包括：

• 承運商：FedEx。
• 追蹤識別碼：提交至 API 的識別碼。
• 目前狀態：你標準化後的狀態，例如已建立標籤、運送中、派送中、已送達、異常或未知。
• 承運商狀態：原始 FedEx 狀態或代碼，供支援及除錯使用。
• 最新事件：FedEx 返回的最近事件描述及時間戳記。
• 預計送達時間：僅在回應提供時儲存，並以預計而非保證的方式顯示。
• 送達確認：使用承運商回應判斷是否已報告送達。
• 最後查詢時間：由你的系統記錄的時間戳記，與 FedEx 報告的事件時間不同。

狀態標準化需要編輯及營運方面的判斷。例如，異常不應自動顯示為派送失敗，而已建立標籤事件亦不一定表示包裹正在網絡中運送。請保留原始承運商事件及標準化狀態，讓支援人員可以調查兩者之間的差異。

步驟 5：處理錯誤及不完整資料

生產環境的追蹤整合必須區分不同的失敗類型。格式錯誤的請求、已過期的令牌、無效的追蹤號碼、暫時性的承運商服務中斷，以及成功回應但沒有有用事件，並不是同一種情況。

情況	建議處理方式
驗證失敗	更新憑證或令牌處理方式；如果問題持續，通知整合負責人。
無效請求	重試前驗證 payload、必要標頭、識別碼格式及環境。
找不到追蹤號碼	顯示未解決或不可用狀態；沒有額外證據時，不要告訴客戶包裹已遺失。
暫時性逾時或伺服器錯誤	使用有上限的重試及退避機制，並保留最後已知狀態。
沒有最近掃描記錄	顯示最近一次已確認的事件及其時間，而不是捏造目前位置。

重試邏輯應保持審慎。重複請求可能增加負載、造成過多警報，或違反 API 限制。請設定逾時、指數退避、冪等處理，並監控重複失敗。確切的速率限制及服務承諾應以你的 FedEx 協議或最新文件為準，不應從範例應用程式中自行假定。

步驟 6：安排更新，避免造成不良客戶體驗

大多數貨件系統不需要每隔幾秒便要求最新結果。請根據貨件狀態制定更新策略。新貨件在建立標籤後可能需要更頻繁查詢，而已送達貨件通常應停止輪詢。異常情況可能需要獨立的支援工作流程，而不是加快自動輪詢。

向客戶展示結果時，請包括最近承運商事件的時間，並清楚說明送達日期是否為預計日期。如果 API 暫時不可用，請保留上一次已驗證的結果，並說明狀態尚未更新。這比將已知狀態替換為一般錯誤更有用。

步驟 7：測試完整工作流程

測試內容不應只有成功回應。實際的測試計劃應涵蓋：

• 具有多個掃描事件的有效追蹤號碼。
• 追蹤歷史有限的新建立貨件。
• 已送達貨件。
• 異常或延遲貨件（如有具代表性的測試資料）。
• 無效或不完整的追蹤號碼。
• 已過期或已撤銷的憑證。
• 逾時、速率限制回應及暫時性伺服器錯誤。
• 重複事件及按錯誤順序到達的事件。
• 不同時區及夏令時間轉換。
• 在日誌中遮蔽憑證、令牌、個人資料及完整承運商 payload。

正式上線前，請將你的標準化狀態與受控樣本的 FedEx 追蹤頁面進行比較。兩個視圖未必會在完全相同的時間更新，因此目標是確認解析器能正確解讀回應，而不會將缺失資料轉化為確定性聲明。

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

當 FedEx 是主要承運商，而你的團隊希望自行管理完整應用程式邏輯時，直接整合 FedEx 是合理的選擇。當訂單可能經由多個承運商、市場平台、郵政營運商或地區配送服務運送時，直接整合的效率會較低。在這種情況下，企業可能需要承運商識別、通用狀態模型、webhook 或輪詢協調、品牌化追蹤頁面，以及一個支援視圖。

17TRACK 提供獨立的 Tracking API，並在 api.17track.net 發佈開發者文件。當需求不僅限於 FedEx 追蹤時，可以將其評估為多承運商方案。合適的選擇取決於你的項目在測試期間能夠核實的承運商、國家或地區、事件詳細程度、整合模式、商業條款及營運控制。多承運商服務並不會免除測試承運商特定異常，或驗證事件對你自身貨件組合的準確性及時間性的需要。

實際實作檢查清單

• 確認 FedEx API 產品符合你所需的查詢類型。
• 核實最新的驗證端點、基礎 URL、請求結構及必要標頭。
• 將 client secret 及存取令牌保留在伺服器上。
• 安全地快取及更新 OAuth 令牌。
• 傳送請求前驗證追蹤識別碼。
• 同時儲存原始承運商狀態及標準化狀態。
• 將承運商事件時間與系統擷取時間分開記錄。
• 使用有上限的重試，並分開監控驗證、驗證資料、逾時及承運商錯誤。
• 在終止狀態後停止例行輪詢，但須遵守你的營運規則。
• 在向客戶顯示狀態訊息前，測試實際回應的不同變化。
• 變更 API 版本或擴展貨件類型時，重新查閱 FedEx 文件。

常見問題

我可以使用 FedEx 網站而不是 API 嗎？

可以。FedEx 網站通常是手動查詢的最簡單選項。當軟件必須自動取得追蹤資料、將狀態事件連接至訂單，或在另一個應用程式內展示追蹤資訊時，API 便會發揮作用。

每次追蹤請求都需要 OAuth 令牌嗎？

通常，應用程式會取得存取令牌，並在令牌到期前隨後的 API 請求中傳送該令牌。請安全地快取令牌，並遵循最新 FedEx 驗證文件中關於到期及更新行為的說明。不要將令牌公開給瀏覽器或客戶。

API 可以準確告訴我包裹的位置嗎？

它可以返回 FedEx 為該貨件提供的追蹤事件及其他資料。結果可能會顯示掃描位置或設施，但不應被解讀為持續的即時 GPS 定位。只顯示實際返回的位置及事件詳細資料。

為甚麼追蹤號碼有時沒有更新？

貨件可能已建立但沒有最近的掃描記錄，識別碼可能不正確，事件可能尚未在回應中提供，或承運商服務可能暫時不可用。請保留最後一次已確認的結果，顯示查詢時間，並調查重複失敗，而不是宣稱貨件已遺失。

電子商務企業應否為每個承運商建立獨立 API？

對於以 FedEx 為主且具備強大工程資源的營運，這可能是合理的做法。透過多個承運商運送貨件的企業，可能更希望使用多承運商追蹤層，以減少整合工作並標準化事件。在作出選擇前，請比較承運商覆蓋範圍、資料詳細程度、可靠性、文件、成本，以及對面向客戶體驗的控制程度。

資料來源

• FedEx Developer Portal: Track API
• FedEx Developer Portal: Authorization API
• FedEx Developer Portal
• 17TRACK Tracking API
• 17TRACK API Documentation