如何使用貨件追蹤 API 發送主動配送通知
要透過貨件追蹤 API 發送主動式配送通知,請將每件包裹與其訂單關聯,接收追蹤更新,將這些更新轉換為與客戶相關的事件,然後透過你的電郵、SMS 或應用程式通知服務觸發訊息。在傳入的追蹤資料與傳出的訊息之間加入持久佇列及重複檢查,避免重複或延遲的更新產生令人困惑的提醒。
本指南適用於建構此工作流程的開發人員及電子商務營運團隊。目標不是轉發承運商的每次掃描,而是告知客戶何時發生有意義的變化、變化代表甚麼,以及他們是否需要採取行動。
連接 API 前先設計通知工作流程
貨件追蹤 API 提供追蹤資料;你的應用程式決定如何使用這些資料。即使你選用的服務同時提供貨件可見度及客戶通訊,也應將兩者視為獨立職責。
實用的架構包括六個階段:
- 訂單關聯:在需要時,將追蹤號碼及承運商識別碼與內部貨件記錄關聯。
- 追蹤登記:按照供應商的整合要求提交或登記貨件。
- 接收更新:接收 webhook 回調、透過 API 請求取得更新,或結合兩種方式。
- 事件處理:驗證、標準化、去重及評估傳入事件。
- 通知決策:決定是否通知、通知對象,以及使用哪個渠道和範本。
- 訊息傳送:發送通知並記錄訊息服務的回應。
除非整合確實需要,否則請將客戶聯絡資料保留在你自己的訂單或訊息系統內。一般而言,追蹤服務不需要客戶的電郵地址,僅為讓你的應用程式將追蹤事件與訂單關聯。
1. 確認整合合約
在編寫接收器之前,請查閱供應商文件,了解驗證、貨件登記、承運商識別、支援的更新方式、回應格式、請求限制及錯誤處理。對於 webhook 整合,亦應確認回調如何驗證、哪種回應代表已收到,以及傳送失敗時如何處理。
如要實作 17TRACK,請先查看 17TRACK Tracking API page 及其 official API documentation。整合時應依照已記錄的合約,而不要將本指南中的示例欄位名稱視為 17TRACK 的請求或回應欄位。實作前請確認回調設定、安全要求及帳戶專屬限制。
根據整合合約選擇更新方式:
- Webhooks:在受支援且適合你的基礎設施時使用回調。供應商發送更新後,應用程式即可處理,而不必重複請求同一貨件。
- 輪詢:當回調不可用或不適合時,按排程取得追蹤資料。請將排程維持在已記錄的請求限制內。
- 結合方式:使用回調進行正常處理,並在供應商支援此工作流程時,選擇性地透過 API 取得資料,以協調更新似乎過時的貨件。
不要因為使用 webhooks 就向客戶承諾即時通知。上游追蹤資料尚未提供承運商事件前,你的應用程式無法報告該事件。
2. 建立能應對真實訂單的貨件記錄
使用內部貨件 ID 作為主要參考,而不是只使用追蹤號碼。一張訂單可以包含多件包裹,也不應假設追蹤號碼永遠在全球範圍內唯一。
有用的內部記錄包括:
- 內部訂單 ID 及貨件 ID。
- 追蹤號碼及承運商識別碼(如已知)。
- 供應商提供的貨件參考資料(如有)。
- 目前的標準化狀態及最近一次有意義的事件。
- 承運商事件時間,包括可用時的時區或偏移量。
- 你的系統收到更新的時間。
- 客戶通訊偏好的參考資料。
- 通知歷史及任何有效的例外處理流程。
請將事件時間與接收時間分開儲存。較早發生的掃描可能在較新的掃描之後才到達。如果應用程式只按到達順序排序,可能會錯誤地將已送達的貨件改回運送途中。
對於拆單,請將通知連結至受影響的包裹。當另一件包裹仍在運送時,「你訂單中的一件包裹已送達」比「你的訂單已送達」更準確。
3. 將追蹤事件映射至客戶決策
承運商描述是營運資料,不是可直接使用的客戶訊息。建立標準化層,在保留原始事件的同時,為事件指派通知規則能夠理解的內部類別。
以下類別是建議的應用程式概念,並非通用的 API 狀態詞彙:
| 內部類別 | 通知決策 | 訊息界線 |
|---|---|---|
| 已收到貨件資料 | 只有在有用時才發送準備更新。 | 不要僅憑建立標籤就暗示承運商已實際接收貨件。 |
| 運送途中 | 考慮在首次有意義的移動時通知。 | 除非會改變客戶下一步行動,否則抑制例行設施掃描。 |
| 派送中 | 受支援事件表示此狀態時通知。 | 不要將狀態轉化為保證的送達時間。 |
| 派送嘗試或需要取件 | 發送可採取行動的通知。 | 只有在已確認時才加入期限或領取指示。 |
| 派送例外 | 評估原因及客戶是否需要採取行動。 | 不要將每個例外都描述為包裹遺失。 |
| 已送達 | 發送包裹層級的確認。 | 不要捏造收件人、送達位置或送達證明。 |
保留不確定性。未識別事件應進入審查或備用流程,而不是被強行歸入最相近的熟悉類別。保留原始描述,讓支援人員能夠進行故障排除。
4. 接收更新而不遺失或重複處理
你的 webhook 端點應驗證請求、持久儲存已接受的更新,並返回供應商要求的確認回應。請非同步產生訊息,不要在回調請求期間等待電郵或 SMS 服務。
實作供應商已記錄的回調驗證方式。不要自行創造簽名標頭,也不要假設每個供應商都使用相同的驗證方案。同時強制使用 HTTPS、請求大小限制、載荷驗證及適當的存取控制。
簡化的處理流程如下。這些是應用程式層級的操作,不是可運作的 SDK 示例:
receive callback
verify request using documented provider mechanism
validate payload
persist accepted payload and enqueue processing atomically
return documented acknowledgment
process queued update
find internal shipment
normalize relevant events
ignore already-processed events
evaluate chronology and state transition
create notification job if policy permits
commit state and job together
send notification job
check recipient preferences and suppression rules
submit message to messaging service
record result and retry only when appropriate
原子步驟十分重要。如果應用程式儲存狀態變更後,在建立通知工作前崩潰,客戶可能永遠收不到提醒。交易式 outbox 是其中一種設計選擇:在同一資料庫交易中儲存狀態變更及待處理工作,然後由工作程式派送該工作。
明確處理未知的貨件參考資料。將其隔離以供調查或協調,而不要猜測應向哪位客戶發送通知。
5. 加入重複防護及時間順序檢查
設計接收器以容許重複回調及工作程式重試。若文件中提供穩定的供應商事件識別碼,應優先使用。否則,使用合適欄位建立確定性的事件指紋,例如內部貨件 ID、事件代碼、事件時間及位置。在依賴指紋前,請先使用實際載荷測試。
事件去重與通知抑制解決的是不同問題。去重可阻止同一事件被處理兩次;抑制則可防止數個不同的掃描產生基本相同的客戶訊息。
圍繞業務事件定義通知識別。送達確認可以使用貨件 ID 及已送達里程碑。派送嘗試可能需要以嘗試次數為識別,因為之後的嘗試可能是真正的新事件。
對於順序錯亂的更新,請比較事件時間戳並評估允許的狀態轉換。不要假設回調只包含新的掃描;請確認其已記錄的結構代表單一事件、快照還是歷史記錄。將矛盾更新交由協調流程處理,而不是默默丟棄所有修正。
6. 編寫說明下一步的訊息
每項通知都應說明相關包裹、已確認的變更及客戶下一步行動。加入安全的追蹤連結及易於識別的訂單參考資料。避免在 SMS 訊息及鎖定畫面預覽中公開完整地址或不必要的個人資料。
例如:
- 派送中:「你的訂單 {order_reference} 包裹現正派送中。請在此查看進度:{tracking_link}。」
- 派送嘗試:「承運商報告曾嘗試派送你的包裹。請查看追蹤頁面了解可採取的下一步:{tracking_link}。」
- 已送達:「承運商已將你訂單 {order_reference} 的包裹標記為已送達。查看可用的送達詳情:{tracking_link}。」
只從已驗證的資料呈現佔位符。如果有適合顯示的預計送達時間,請標明為估計時間。如果缺少該資料,請省略,而不要捏造日期。
對於例外,請區分貨件問題與客戶任務。故障可能只需要解釋;已確認的地址問題可能需要採取行動。不要僅根據不受信任的追蹤自由文字內容,將客戶導向付款或上載文件頁面。
根據客戶偏好、渠道權限、緊急程度及適用規則選擇渠道。請檢視你所使用司法管轄區及訊息渠道的同意、退訂及免打擾時段要求。將配送服務通知與推廣活動分開,不要假設兩者使用相同的權限。
7. 定義追蹤沒有更新時的處理方式
主動式通訊應涵蓋進度缺失及新事件,但單靠沉默並不能證明貨件延誤或遺失。
根據服務級別、路線、最近一次有意義的事件及任何受支援的預計送達時間,建立追蹤過時規則。根據營運資料及支援流程設定門檻,而不是對所有貨件套用一個統一等待期。
規則觸發時,請檢查是否有遺漏的處理,在受支援的情況下與追蹤來源協調,並決定是否建立內部支援工作。如果通知客戶,措辭應反映你所知道的內容:「我們尚未收到新的追蹤更新」不同於「你的包裹已遺失」。
為未解決的例外指定負責人。反覆宣佈問題卻沒有解決途徑的通知系統,可能會增加客戶的不滿。
8. 啟用自動發送前測試完整流程
先以影子模式執行工作流程:接收真實或已批准的測試事件、產生建議通知,並在不聯絡客戶的情況下檢查結果。
- 重播完全相同的回調,確認不會建立另一則訊息。
- 在已送達事件後處理較早的運送事件,並檢查最終狀態。
- 測試缺少時間戳、未知狀態及格式錯誤的載荷。
- 模擬確認前的資料庫故障,以及持久儲存後的工作程式故障。
- 測試訊息逾時,包括服務可能已接受訊息但回應不確定的情況。
- 確認拆單會產生針對個別包裹的措辭。
- 檢查已退訂收件人、無效聯絡資料及免打擾時段處理。
- 確認追蹤連結不會公開其他客戶的訂單資料。
監察已接受的回調、處理失敗、佇列年齡、通知工作、重複抑制及訊息結果。分開量度從系統收到更新起的處理延遲及承運商事件的年齡。這種區分有助於判斷通知緩慢是源於上游資料可用性,還是你自己的流程。
先從一小組易於理解的里程碑開始。只有在支援及營運團隊同意訊息準確、可採取行動且值得接收後,才擴展規則。
FAQ
貨件追蹤 API 會自動發送電郵或 SMS 嗎?
不一定。追蹤資料存取及客戶訊息是兩項獨立能力。請查閱服務已記錄的範圍。在自訂整合中,你的應用程式可以處理追蹤更新,並透過獨立的訊息服務發送通知。
我是否應通知客戶每次追蹤掃描?
通常不需要。優先處理有意義的里程碑及需要採取行動的事件。數次設施掃描可能只是正常運送,並沒有改變客戶需要知道的內容。將詳細歷史記錄保留在追蹤頁面。
我可以保證即時配送通知嗎?
你可以在系統收到更新後設定及監察處理目標,但無法保證承運商何時記錄或發布掃描。請使用能反映這項依賴的措辭描述服務。
如何防止重複的送達訊息?
使用持久事件去重、針對每個業務里程碑的獨立通知識別,以及交易式工作建立。在訊息服務支援冪等性時,請將其作為另一項防護。單靠記憶體中的重複檢查無法應對重新啟動或多個工作程式。
如果承運商修正已送達狀態,應如何處理?
保留兩個事件並協調貨件狀態。如果修正對客戶有重大影響,請根據你的政策發送清晰的修正通知或轉交支援。不要為了簡化程式碼而將已送達狀態永久設定為不可逆。
Sources
以下官方資源是上述 17TRACK 整合的實作參考。指南中的內部結構、通知規則及處理流程是架構建議,而不是引用的 API 合約。
- 17TRACK Tracking API — 評估 API 整合的官方起點。
- 17TRACK API documentation — 供應商特定請求格式、驗證、追蹤操作及整合要求的參考。


