info-icon


Webhook開發人員指南

簡介

FedEx的查詢Webhook會在貨件的整個生命週期內,提供近乎實時的貨件更新。

有別於必需應用程式來要求貨件狀態的查詢API,當有新資訊可用時,Webhook會自動傳送貨件更新。

本指南涵蓋:

  • 三項整合原則
  • Webhook的運作方式
  • 處理Webhook數據
  • 顧客通知
  • 時間戳記
  • 最佳做法及常見整合問題

三項整合原則

要確保Webhook成功整合,必須遵循三項原則。

將每筆Webhook數據作為貨件狀態更新來處理

請勿假設每筆數據均代表新的查詢里程碑。每當有新的貨件資訊可用時,FedEx會發佈新的數據。

數據可能包含:

  • 新的查詢事件
  • 最新的遞送預測
  • 送達證明資訊
  • 收件人資料
  • 其他貨件資料更改

多筆數據可共用同一個查詢里程碑,但各筆數據可能包含不同的貨件資料。

儲存並合併貨件資料

每筆數據可能包含新或最新的貨件資料。請儲存每筆Webhook數據,並將新資訊合併至現有貨件記錄。

請勿使用最新數據覆寫現有的貨件記錄。取而代之,請保留先前收到的貨件資料,並納入新資訊,以在貨件的整個生命週期內保持貨件記錄為完整及最新。

根據業務規則來決定後續操作

根據業務規則來決定何時更新系統或通知顧客。

請勿僅根據事件代碼觸發操作。在更新顧客專用的應用程式或傳送通知前,請先評估:

  • 查詢里程碑
  • 貨件可用性
  • 通知時機
  • 業務要求

建議處理模型

以下圖表說明了在一般實施情況下,這三項Webhook整合原則如何互相配合。每筆Webhook數據均會作為貨件狀態更新來處理,合併至中央化貨件記錄,並根據業務規則作評估,然後才會更新應用程式或向顧客傳送通知。


Webhook的運作方式

每當有貨件資訊出現變化或可用時,FedEx會發佈新的Webhook數據。貨件在整個生命週期內可生成多筆數據,包括與同一項查詢里程碑相關聯的多筆數據。

額外數據可能包括:

  • 查詢里程碑:已收件、運送中、已在送件和已送達。
  • 貨件資料:送達證明 (PPOD)、簽收證明 (SPOD)、GPS送達證明 (GPS POD) 及收件人資訊。
  • 遞送預測更新:預計送達日期及時間更改。
  • 未能送達事故:貨件及未能送達事故更新及原因。
  • 貨件中繼資料更新:地址更新、參考資料及服務詳情。
  • 營運修正:其他查詢里程碑及previousEvents更新。

請注意:已送達貨件未必會提供相片證明。相片證明是否可用,需視乎遞送類型、簽收要求及其他業務規則而定。

每筆數據代表貨件的已知最新狀態。請處理每筆數據,確保您的貨件記錄為完整及最新。

理解Webhook更新

下列例子展示了在同一件貨件的整個生命週期內,系統如何為其生成多筆Webhook數據。部分數據會引入新的查詢里程碑。其他數據則會新增貨件資訊,例如遞送預測、送達證明數據或貨件詳情。

重要事項:系統可能會為同一項查詢里程碑生成多筆Webhook數據。請處理每筆數據,確保系統會將新的貨件資訊納入貨件記錄。


處理Webhook數據

請將每筆Webhook數據作為貨件狀態更新來處理。

請勿假設每筆Webhook數據均代表新的查詢里程碑。每當有新的貨件資訊可用時,FedEx會傳送新的數據。以已送達的貨件為例,當系統新增或更新送達證明資訊、收件人資訊或其他貨件資訊時,可能會生成額外數據。

針對每筆數據,請思考以下問題:

  • 哪個查詢里程碑出現變化?
  • 哪些貨件資訊出現變化?
  • 此項更新會影響顧客專用的應用程式嗎?
  • 此項更新會觸發通知嗎?

處理貨件記錄

同時監察scanEvent和previousEvents。

  • scanEvent包含與數據相關聯的目前查詢里程碑。
  • previousEvents包含其他貨件記錄,包括可能不會顯示為目前scanEvent的里程碑。

部分查詢里程碑會在previousEvents中顯示,而非發佈為新的scanEvent。如應用程式僅處理scanEvent,便可能會遺漏貨件更新,並生成不完整的貨件記錄。請處理兩個系列的數據,全面掌握貨件狀況。

維護貨件記錄

請儲存每筆Webhook數據,並將新資訊合併至現有貨件記錄。

完整的貨件記錄可涵蓋以下各項,提供近乎實時的貨件查詢功能:

  • 貨件查詢儀表板
  • 顧客服務應用程式
  • 訂單管理系統 (OMS)

請以每筆數據來更新貨件記錄,確保盡量保持貨件狀況準確完整。


顧客通知

請根據您的業務需要,以及您希望提供之貨件資訊的詳盡程度,選擇一項通知策略。

FedEx查詢Webhook會以近乎實時的方式,傳送查詢里程碑及貨件資料變化的更新。請運用業務規則來判斷哪些更新與業務相關,以及哪些更新可以忽略。

常見的通知策略包括:

近乎實時的通知

當發生查詢里程碑後,立即傳送通知。

優勢

  • 最快捷的顧客通訊
  • 最少延遲

注意事項:額外貨件資料可能尚未提供。

豐富詳盡的通知

當達到某個查詢里程碑後,請等候數分鐘,待額外貨件資訊傳入。

例如當某筆里程碑傳入後,請等候數分鐘以收集:

  • 送達證明 (POD)
  • 簽收證明 (SPOD)
  • GPS送達證明
  • 收件人資料

優勢

  • 為顧客提供更完整的貨件更新
  • 減少後續通知
  • 減少顧客聯絡顧客服務部的次數

FedEx建議於里程碑傳入後等待約五分鐘,因為系統通常會在首項遞送事件後的短時間內,新增送達證明資訊。

通知時機建議

通知時機因應顧客和使用個案而異。不過,下列建議一般適用於購買後向收件人傳送的通知。如為其他通知類型(例如向企業用戶、顧客服務部代表等不同對象傳送的通知),請選擇適合相關使用個案的通知策略。

  • 預計送達:在承諾日期和首個預計送達日期均可供查閱後,等待約15分鐘。
  • 已在送件:立即傳送,或者根據您的業務時間表傳送(例如每日早上8:00)。
  • 已送達:等候約5分鐘,待遞送附加資訊傳入。
  • 嘗試遞送:採用與已送達事件相同的做法,待遞送資訊傳入。

按照業務資料建立通知規則

並非每項貨件更新都需要通知。制定切合您業務需要的通知規則。

建議做法

請勿僅根據eventCode觸發通知。

評估:

  • 查詢里程碑
  • 所需的貨件資料
  • 業務規則

僅當所需資料可供查閱時,才生成通知。

此做法有助防止:

  • 重複通知
  • 缺漏遞送資訊
  • 遞送通知不完整
  • 不必要的後續通知

時間戳記

請根據您的使用個案,採用合適的時間戳記。

  • eventCreateTime:貨件事件的發生時間。用於向顧客顯示的查詢記錄。
  • 訊息傳送時間:FedEx傳送Webhook數據的時間。僅用於偵錯及監察,不應用於顧客專用的體驗。

eventCreateTime反映貨件事件的發生時間。FedEx在日後新增額外貨件資訊時,不會更新此值。例如,即使後續數據新增送達證明資訊或其他貨件更新,已傳入的事件仍會保留其原有的eventCreateTime。因此,應使用eventCreateTime來識別事件的發生時間,而非使用新增相關貨件資訊的時間。

在部分情況下,事件時間可能無法提供。在此情況下,時間戳記可能會包含預設值00:00:00。當有更準確的時間戳記可用時,額外數據可能會包含該時間戳記。


最佳做法及常見整合問題

最佳做法

  • 處理每筆Webhook數據 — 每則訊息都可能包含新的查詢事件或貨件資料更新。
  • 將增量更新合併至您現有的貨件記錄。
  • 同時監察scanEvent和previousEvents,全面掌握貨件記錄。
  • 根據業務規則來觸發客戶通知,而非僅依據原始事件。
  • 在通知顧客前,先等待預期的附加資訊(例如送達證明圖像、簽收證明、GPS等)傳入。
  • 設計具備冪等性的彈性處理機制,管理重複及亂序訊息。

常見整合問題

  • 假設每筆數據均代表新的查詢里程碑。
  • 使用最新數據覆寫貨件記錄。
  • 僅依賴scanEvent。
  • 僅根據eventCode觸發通知。
  • 假設首筆傳入數據包含所有遞送詳情。
  • 假設Webhook訊息僅會傳入一次,或者會按時間順序傳入。

摘要

請將每筆Webhook數據作為貨件狀態更新來處理。儲存並合併貨件更新,同時監察scanEvent和previousEvents,並根據業務規則決定何時更新應用程式或通知顧客。

此做法有助確保貨件狀況資訊準確、查詢記錄完整,並讓顧客掌握更全面的資訊。