FedEx API 整合工作最佳做法

這份快速參考指南旨在幫助 API 使用者了解如何改善 FedEx 的整合體驗，並在設計、速度和安全性三方面確保整合解決方案的質素。

為有效地整合至 FedEx API，開發人員應依循下列整合工作最佳做法：

API 網址

• 測試版及正式版分別設有獨立的 API 網址。
• 開發人員應使用測試網址進行開發及整合測試，於推出正式版本時才使用正式版網址。

API 網址以下所示：

測試：https://apis-sandbox.fedex.com/

正式版：https://apis.fedex.com/

憑證管理

• API 金鑰及秘密金鑰

• 您的 API 金鑰及秘密金鑰乃用於識別您的應用程式，並需在 OAuth 令牌請求時使用。

1. 您應該以非常嚴密的方式處理 API 金鑰及秘密金鑰。切勿透過電郵或分佈式代碼分派 API 金鑰及秘密金鑰，包括客戶端 JavaScript。
2. 如果您的 API 金鑰及秘密金鑰被盜取，您的應用程式將會遭受損害。如果您懷疑您的憑證被盜取或遭受損害，請立即重新建立秘密金鑰。
3. 請避免記錄敏感資料，如秘密金鑰。

• 切勿將 API 金鑰及秘密金鑰寫死在您的編碼中。
• 您的應用程式應能夠動態更新 API 金鑰及秘密金鑰。
• 客戶憑證應儲存在保險庫/安全地點內，避免遭受入侵。

• OAuth 令牌

• 存取令牌應僅儲存在網頁應用程式伺服器上，且務必避免暴露給瀏覽器。
• 切勿將令牌寫死在您的應用程式中。
• 保護存取令牌，以免令牌遭到入侵。
• 嘗試取得新存取令牌時，避免多次呼喚 OAuth 令牌 API。建議緩存存取令牌，直至出現 HTTP 錯誤代碼 401 為止。屆時請重新產生 OAuth 令牌。
• 切勿向終端用戶或應用程式暴露令牌。
• 請在進行任何 API 交易時均使用 HTTPS。

編程做法

• 為繼續符合最新最安全的數據加密通訊協議，建議使用 1.2 版本或以上的傳輸層安全性協定 (TLS)。
• 切勿忘記設定各 API 請求必要的正確 API 標頭。您可以在各 API 文件頁面中找到標頭資訊。
• HTTP POST 內的「內容類型」應為「application/json」。
• 請參閱示例代碼，以開始使用各 API。各個 API 的終端均提供多個示例，助您了解必要的元素、格式及其他詳情。
• 當用戶或開發人員發送的數值包含大量小數點時，會造成奇數錯誤。就重量及貨幣數值/金額而言，僅接納兩位數字的顯式十進制。尺寸不支持小數點，例如長度、寬度及高度。

示例：重量：45.26，貨幣數值/金額：100.52，長：10，寬：25，高：15。

• 避免發送空白元素。

示例：「街道線」：「」

• 僅發送處理請求時必要的資料。

舉例而言，如果是美國國內貨件，應避免寄發商業發票及國際貨件才可能需要的商品資料。

• 開發時，請判斷在非必要回應元素 (如運費) 未有返回的情況下，應有甚麼反應。請在使用資料前評估缺漏元素的交易回應。

舉例而言，即使在報價功能停止運作時，仍能夠託運包裹。請在使用資料前測試缺漏元素下的交易回應。

• 總體而言，請在適當情況下避免強硬依賴 FedEx API 整合工作。
• 為減輕延遲問題及取得準確結果，應採用下列功能：
  
  • 篩選 - 利用您的目標參數，使用此功能縮小搜索範圍。
  • 排序 - 使用此功能為結果排序，並按照若干參數升序或降序排序。
• 在發送交易前，驗證必要欄位內填有資料，例如收件人郵遞區號及包裹重量。驗證該欄位內的資料為適當的資料。此舉將減少交易錯誤。
  

舉例而言，如果是美國郵遞區號，請驗證該欄位資料全為數字，並且格式為 5 位數字或 ZIP+4 位郵遞區號。

• 為避免對 FedEx 系統的可用性和可靠性產生不利影響：
  
  • 切勿在測試或正式版環境進行性能測試。
  • 加入適當的編碼邏輯，以防止同一交易不斷重覆失敗。
• 節流限制設置為 10 秒內 1400 個交易。如果在首數秒內已達到這個限制，將得出 HTTP 錯誤代碼 429 請求過多，而交易將受到限制，直至經過 10 秒為止；交易然後將會恢復。
  

舉例而言，如果我們在頭四秒內已經收到 1400 個請求，那麼將會返回 HTTP 錯誤 429 請求過多 - 「我們在短時間內收到太多請求。請稍等一會，然後再嘗試。」，而交易將在接下來的六秒內受到限制，然後再次恢復。

• 不要以編碼固定貨件的業務規則例如服務類型、包裹類型、重量限制等等，因為這些設定或不時更改。

處理錯誤

每個 API 回應均會包含 HTTP 狀態代碼和回應數據。部分回應在適用情況下會伴隨錯誤、警告或附註。警告及附註並不代表出現錯誤；然而，應記錄及檢查錯誤或警告訊息。妥善地處理錯誤將確保您的 FedEx 整合工作順利進行，有助避免損壞。

HTTP 狀態代碼

費用

• 有兩種方法可以取得報價：
  
  • 指定 serviceType 的報價 - 結果將按照指定的 serviceType 數值篩選。此舉將縮小回應的大小，並加快交易回應時間。
    

    示例：STANDARD_OVERNIGHT

  • 報價商店 – 如未有指定 serviceType，則返回所有適用的服務及其相應的報價。
• 請利用服務選項 API 判斷若干寄件地目的地配對可使用哪些服務、包裹選項及特別服務，並在報價請求中傳送 serviceType 及包裹選項資料。
  

  舉例而言，並非所有郵遞區號配對均可選用 STANDARD_OVERNIGHT (及其他服務或選項)。

• 就應用至貨件的特別服務而言，必須包含特別服務類型及其詳情。
  
  • 附註： 部分特別服務沒有詳情。
• 請閱覽報價 API 文件。

託運

• 請利用服務選項 API 判斷若干寄件地目的地配對可使用哪些服務，並在託運請求中傳送 serviceType 及包裹選項資料。
• 就應用至貨件的特別服務而言，必須包含特別服務類型及其詳情。
  
  • 附註：部分特別服務沒有詳情。
• 請在託運日結束時貨件收件前關閉 FedEx Ground。
  
• 請閱覽託運 API 文件。
  

查詢

• 請將單一查詢請求內的查詢號碼數量限制為 30。此舉將縮小回應的大小，並加快交易回應時間。
  
• 請將包裹查詢次數限制為業務需要所須的次數。
• 就批量查詢而言，請將批次中已返回「已送達」狀態的所有包裹移除。
• 請閱覽貨件查詢 API 文件。

驗證地址

• FedEx 提供的驗證地址僅為建議，並非最終決定。終端用戶需要作出最終決定，根所提供的資料及其業務需要判斷地址是否可用。必須設有程式來處理無法驗證的地址，使訂單得以處理。
• 為確保能享受更好的託運體驗，切勿讓託運程式依賴自選服務，如驗證地址。

舉例而言，如果輸入訂單或託運時驗證地址 API 未能提供服務，應設有應急程序完成託運。

• 請閱覽驗證地址 API 文件。
  

搜尋 FedEx 服務站

• 請提供指定屬性 (如服務站類型、提供的服務等)，收窄搜尋範圍，以取得適當的服務站選項及更快的回應。
• 請閱覽搜尋 FedEx 服務站 API 文件。
  

收件請求

• 預約收件時，切勿輸入過去的備妥時間、過去的日期或太過久遠的未來日期。
• 禁止匿名收件。
  
• 請閱覽收件要求 API 文件。
  

服務選項

• 由於無法指定多個承運人代碼，如要取得多間營運公司的結果，如 FedEx Express (FDXE)、FedEx Ground (FDXG)、FedEx Freight (FXFR) 及 FedEx Ground® Economy，請省略 carrierCodes 元素或發送獨立的服務選項要求。
• 請確保您已獲預先批核，可使用 151 磅以上的獨立棧板及超過 2,200 磅的棧板。
• 如果您的變數選項指定 SATURDAY_DELIVERY，只要服務包含星期六送件選項，均會顯示其星期六送件選項及一般選項。切勿在特別服務欄指定 SATURDAY_DELIVERY，否則僅會返回任何適用的星期六送件選項。
• 請閱覽服務選項 API 文件。

顧客支援

如您有任何疑問，或是需要更多支援，我們樂意為您提供幫助！請前往我們的支援頁面，以取得資源及我們的聯絡資訊。