如何無需等待 Webhook 即可透過 API 取得最新的貨件狀態
如要取得最新可用的貨件狀態而毋須等待 webhook,請向你的追蹤服務供應商的貨件查詢 API 發送經驗證的請求。使用回應立即更新你的應用程式,然後繼續啟用 webhook 以接收後續變更。重要的區別在於,查詢通常只會取得供應商最新儲存的追蹤資料;它不一定會觸發新的承運商查詢。

當客戶開啟訂單頁面、支援人員需要更新,或你的系統需要從遺漏的通知中恢復時,這種方法都非常有用。可靠的實作會結合按需查詢、清晰的新鮮度指示,以及防止重複或次序錯亂更新的保障措施。
決定「最新貨件狀態」的含義
在選擇端點之前,請區分三種聽起來相似但會產生不同結果的操作。
| 操作 | 作用 | 無法確定的事項 |
|---|---|---|
| 讀取你自己的資料庫 | 返回你的應用程式已儲存的追蹤資料。 | 供應商是否已收到較新的更新。 |
| 查詢追蹤 API | 取得供應商查詢操作可提供的資料。 | 該請求期間是否進行了新的承運商查詢。 |
| 要求重新整理追蹤資料 | 如果供應商提供此操作,要求再次進行上游查詢。 | 承運商已有新的掃描,或重新整理會同步完成。 |
需要立即取得答案時,請使用查詢。只有在需要供應商嘗試再次進行上游查詢時,才研究重新整理操作。 不要假設加入防快取參數、重複發送請求,或傳送 HTTP cache-control 標頭,就能強制承運商提供新資料。
貨件可見性包含幾個階段:承運商記錄事件、追蹤服務供應商取得事件,而你的應用程式接收或取得事件。直接 API 請求可以免卻等待通知傳遞,但無法消除該鏈路較早階段的延誤。
編寫程式碼前先檢查查詢合約
整合追蹤服務的開發人員負責這項流程。請以供應商目前的文件為起點,而不要使用從舊整合範例複製的端點。確認以下詳情:
- 貨件識別:查詢接受追蹤號碼、內部貨件 ID,還是追蹤號碼配合承運商識別碼?
- 註冊要求:貨件是否必須先註冊才可以查詢?
- 驗證:需要哪個標頭或驗證機制?
- 回應含義:該操作會返回已儲存資料、開始收集資料,還是返回稍後檢查的工作?
- 結果處理:成功的 HTTP 回應是否可能包含貨件層級的失敗或待處理結果?
- 使用限制:適用哪些速率限制、批次限制及帳戶專屬限制?
- 新鮮度欄位:哪些時間戳代表承運商事件、供應商更新及回應產生時間?
如要整合 17TRACK,相關產品是 Tracking API,而不是消費者追蹤頁面或商店追蹤介面。請使用官方 API 文件,確認適用於你的整合的追蹤資料查詢操作、驗證方式、請求欄位及回應結構。將查詢和 webhook 處理視為兩條獨立的應用程式路徑,但兩者都更新同一貨件記錄。
避免硬編碼有關重新整理行為或查詢頻率的假設。這些細節必須與你實際使用的操作及服務條款相符。
透過你的後端建立按需查詢
實際可行的設計,是在你自己的應用程式中公開一個經驗證的端點。瀏覽器向該端點請求貨件更新;你的伺服器檢查授權、決定是否需要查詢供應商,然後返回標準化結果。
以下路徑是你會在應用程式中建立的端點範例。它不是 17TRACK 端點,也不是供應商請求規格。
GET /api/orders/{order_id}/shipment-status使用訂單識別碼在伺服器上查找貨件。不要讓呼叫者只需替換請求中的追蹤號碼,就能取得其他客戶的追蹤歷史。請將供應商 API 憑證保留在後端,而不要放在瀏覽器 JavaScript 或流動應用程式套件中。
可實作的請求流程
- 授權存取。確認客戶或職員可以查看該訂單。
- 識別貨件。讀取已儲存的追蹤識別碼及承運商資料(如適用)。
- 檢查本地新鮮度。如果已有最近一次成功查詢,便按照應用程式的新鮮度政策重用該結果。
- 需要時查詢供應商。使用有文件說明的操作及有上限的請求逾時設定。
- 驗證結果。同時檢查 HTTP 結果及貨件層級結果。
- 合併資料。套用處理 webhook 事件時使用的相同標準化及調節規則。
- 返回狀態及新鮮度。在可用時,包含最新事件時間及最近一次成功供應商檢查時間。
本地新鮮度政策是工程決定,而不是對承運商更新頻率的陳述。請根據介面要求、供應商限制、貨件數量及觀察到的查詢效用來選擇。客戶反覆點擊更新按鈕,不應產生不受限制的上游請求串流。
標準化回應,但不要捏造新鮮度
即使供應商回應結構不同,你的應用程式仍可返回穩定的內部格式。以下示例物件是你自己的應用程式合約,而不是實際供應商 payload:
{
"shipment_id": "internal-shipment-id",
"status": "in_transit",
"latest_event_at": null,
"provider_updated_at": null,
"last_successful_query_at": null,
"retrieval_state": "success",
"source": "provider_query"
}只有在清楚知道含義時才填入各個時間戳。你的伺服器接收回應的時間應放在查詢中繼資料內;不得將其呈現為包裹移動的時間。如果供應商沒有提供供應商更新時間戳,請將該欄位留空或設為 null,而不要代入其他時間戳。
對客戶介面而言,請分開顯示訊息:「最新承運商事件」描述貨件活動,而「追蹤檢查時間」描述應用程式的取得活動。這種區分可避免未變更的掃描看起來像是新近記錄。
避免 API 查詢及 webhook 互相覆寫
兩種機制同時啟用後,同一事件可能透過查詢及 webhook 到達。它們完成的次序也可能與開始的次序不同。先發出的查詢可能在 webhook 已提供較新資料後才完成。
不要使用「最後回應優先」邏輯。最近收到的 payload 不一定代表最新的貨件狀態。
- 共用一條更新流程。讓查詢結果及 webhook payload 通過相同的驗證、標準化及儲存函式。
- 去除重複事件。優先使用有文件說明的事件識別碼。如果沒有事件識別碼,便根據可用欄位(例如事件時間、狀態、位置及描述)建立定義清晰的指紋。
- 使用含義已知的排序欄位。有文件說明的修訂版本或序號,比假設到達時間代表事件次序更有用。
- 保留歷史。新收到的事件可以填補歷史缺口,而不改變目前貨件摘要。
- 允許修正。狀態並非通用的線性階梯。請遵循有文件說明的修正行為,而不要永久拒絕每個看似倒退的轉變。
當事件次序不確定時,請保留原始 payload 及其來源以供調查。不要透過製造事件時間戳,或假設所有承運商時間戳使用相同時區來消除歧義。
以不同方式處理缺失資料及失敗請求
空結果、未變更結果及失敗請求,不應向客戶顯示相同訊息。
查詢成功但狀態沒有變更
保留現有貨件狀態,並更新最近一次成功查詢時間。不要僅因另一次查詢完成,就產生新的貨件事件。如果客戶需要更多詳情,請顯示現有事件歷史,並說明沒有返回更新的追蹤事件。
貨件尚未有追蹤資料
檢查是否需要註冊、識別碼及承運商是否正確,以及供應商如何表示等待收集。沒有事件本身並不能證明追蹤號碼無效或包裹遺失。保留供應商對未知識別碼、已註冊但等待資料的貨件,以及無法處理的請求之間的區分。
供應商請求逾時或失敗
如果你有之前有效的狀態,請返回該狀態,並明確表示最新檢查未成功。保持之前的成功查詢時間戳不變。網絡錯誤不是配送例外,不應改變包裹的業務狀態。
對適當的暫時性失敗,使用帶有退避及抖動的有限次數重試。不要反覆重試無效憑證或格式錯誤的請求。如果回應提供 Retry-After,請根據供應商合約及 HTTP 語義解讀。HTTP 規範允許該值以秒數延遲或 HTTP 日期表示。
同一貨件收到多個請求
合併並行查詢,讓它們共用一個上游請求。按帳戶及貨件套用限制,並防止自動重試在多個應用程式層級中倍增。如果支援批次操作,請檢查每個貨件的結果,而不要因 HTTP 請求完成就將整個批次視為成功。
將輪詢作為受控後備方案
沒有 webhook 時,排程輪詢可以讓資料庫保持更新,但需要明確的運作政策。決定哪些貨件仍符合條件、失敗如何影響排程,以及何時停止例行輪詢。
對大部分整合而言,混合式設計是合理的起點:webhook 處理背景變更,按需查詢服務互動請求,而調節工作則檢查需要注意的記錄。這是架構建議,並不保證對每個帳戶都能將成本降至最低。
- 優先處理活躍貨件及存在未解決取得錯誤的記錄。
- 避免每次排程執行時查詢所有歷史貨件。
- 定義如何處理已完成貨件,包括你的業務所需的任何修正期限。
- 追蹤查詢真正找到新資料的頻率。
- 調查 webhook 傳遞問題,而不要以越來越頻繁的輪詢掩蓋問題。
監控供應商請求延遲、未成功查詢、速率限制回應,以及查詢資料與 webhook 提供記錄之間的差異。另行監控最新承運商事件的年齡。成功的 API 回應可以與未有變更的追蹤資料並存。
發佈前測試流程
成功請求只是第一項測試。請驗證可能造成誤導性狀態更新的情況:
- 按需查詢仍在執行時 webhook 到達。
- 兩個客戶或職員工作階段同時請求同一貨件。
- 供應商返回 HTTP 成功,但報告貨件層級錯誤。
- 請求失敗,但你的應用程式已持有有效追蹤資料。
- 事件缺少時區,或包含不熟悉的狀態代碼。
- 承運商修正導致之前顯示的結果改變。
- 使用者嘗試存取屬於其他帳戶的貨件。
你的發佈標準應是:應用程式返回已知的最佳貨件資料,準確說明其新鮮度,並且在請求失敗或次序錯亂時不會損壞該資料。
常見問題
查詢 API 會強制承運商掃描或更新包裹嗎?
不會。取得追蹤資料不可能造成實體掃描。請求是否會觸發上游查詢,取決於有文件說明的操作。即使支援重新整理,如果承運商沒有更新事件,也可能返回未變更的資料。
可以不設定 webhook 而使用 API 查詢嗎?
如果供應商支援所需的查詢流程,你可以圍繞按需請求或輪詢建立整合。請先確認註冊及查詢要求。之後,你的應用程式將負責決定檢查時間、控制請求量及偵測變更。
應多久輪詢一次貨件狀態?
沒有通用的間隔。請選擇符合供應商限制、貨件數量及更快找到更新之商業價值的排程。衡量輪詢返回新事件的頻率,然後作出調整,而不要假設頻繁請求會產生更新鮮的承運商資料。
為甚麼 API 返回我已透過 webhook 收到的資料?
兩條路徑都可以公開同一底層貨件記錄。webhook 傳遞通知,而查詢則按需取得資料。透過兩者收到同一事件不一定是錯誤;你的應用程式應將其去重。
更新按鈕應否寫成「重新整理追蹤」?
只有在該措辭準確描述操作時才應如此。如果按鈕取得的是供應商已儲存資料,「檢查更新」會更清晰。請將最近一次承運商事件與應用程式最近一次成功完成檢查的時間分開顯示。
來源
- 17TRACK Tracking API — 本指南所討論的追蹤 API 整合之官方產品參考。
- 17TRACK API 文件 — 供應商特定操作、驗證、請求欄位及回應處理的參考資料。
- RFC 9110,第 10.2.3 節:Retry-After — 定義 HTTP 標頭的 delay-seconds 及 HTTP-date 格式。


