FedEx API 整合最佳做法

這是一份快速參考指南，旨在協助 API 取用者瞭解如何改善與 FedEx 的整合體驗，並確保整合解決方案在設計、速度和安全性方面的品質。

為了與 FedEx API 有效整合，開發人員應遵循這些整合最佳做法：

API URI

• 測試與生產的 API URI 各不相同。
• 開發人員應使用測試用 URI 進行開發與整合測試，並使用正式版網址推出正式版。

下列為 API URI：

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

生產：https://apis.fedex.com/

認證管理

• API 金鑰及秘密金鑰

• 您的 API 金鑰及秘密金鑰可用於識別您的應用程式，且需用於您的 OAuth 存取權杖請求。

1. 請以非常安全的方式對待您的 API 金鑰及秘密金鑰。請勿以電子郵件或包含客戶端 JavaScript 的分散代碼散發 API 金鑰或秘密金鑰。
2. 若您的 API 金鑰或秘密金鑰遭竊，您的應用程式將遭到入侵。若您懷疑您的認證遭竊或入侵，請立即重新建立秘密金鑰。
3. 避免記錄如秘密金鑰等敏感資訊。

• 請勿在程式碼中將 API 金鑰及秘密金鑰硬式編碼。
• 您的應用程式應該要能夠動態更新 API 金鑰及秘密金鑰。
• 客戶認證應該存放在保險櫃/安全之處，以免遭到影響。

• OAuth 權杖

• 存取權杖應該要只儲存在網路應用程式伺服器上，絕對不能公開至瀏覽器。
• 請勿在您的應用程式中將權杖硬式編碼。
• 確保這些存取權杖安全無虞，避免它們遭到入侵。
• 避免多次呼叫 OAuth 權杖 API 獲得新的存取權杖。建議快取存取權杖，直到您看到 HTTP 錯誤碼 401。這時再重新產生 OAuth 權杖。
• 請勿將權杖向最終使用者或於應用程式公開。
• 任何 API 交易均需要使用 HTTPS。

編碼做法

• 為維持遵循最新與最安全的資料加密通訊協定，建議您使用 1.2 版或更高版本的傳輸層安全性協定 (TLS)。
• 別忘了為每個 API 請求設定所需要的正確 API 標頭。您將在每個 API 文件頁面下找到標頭資訊。
• HTTP POST 中的「Content-Type」應該要是「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 文件。

顧客支援

如有問題或需更多協助，我們很樂意為您服務！請前往我們的「支援」頁面，查看與我們聯絡的相關資源和資訊。