首頁博客指南Shipping API 配送狀態：狀態碼、Webhook 及異常警示

Shipping API 配送狀態：狀態碼、Webhook 及異常警示

17TRACK

Shipping API 的配送狀態描述的是包裹的進度，而不是 API 請求是否成功。要建立可靠的追蹤系統，應將 HTTP 回應代碼與貨件狀態分開處理；處理 webhooks 時，不要假設它們只會到達一次或按順序到達；並將需要採取行動的例外轉化為由明確負責人處理的警報。對工程及電子商務營運團隊而言，目標是建立一份可信的貨件記錄，即使承運商更新延遲、重複或被修正，記錄仍然可靠。

Shipping API Delivery Status Status Codes Webhooks and Exception Alerts

本指南將說明如何建立這份記錄、處理傳入的追蹤事件，以及區分配送問題與追蹤整合問題。

分開處理 HTTP 代碼、API 結果及貨件狀態

「狀態代碼」一詞可以指三個不同層面。將它們混為一談會造成誤導性的儀表板及不必要的客戶通知。

層面它告訴你的內容示例解讀
HTTP 回應HTTP 請求的結果200 回應表示 HTTP 層面成功；不代表包裹已送達。
API 業務結果根據供應商的應用程式規則，所請求的操作是否成功回應本文可能會指出追蹤登記被拒絕，即使 API 採用這種設計時，HTTP 回應本身是成功的。
貨件狀態包裹已報告的實際或營運狀態運送中、等待領取或已送達。

HTTP 語義標準定義了 HTTP 回應的含義。例如，202 Accepted 表示請求已被接受處理，但處理不一定已完成。這並不能證明承運商已接收包裹。

同樣地，追蹤請求失敗並不能證明貨件已停止移動。即使實際配送正常進行，你的應用程式也可能暫時失去可見性。應獨立監控這些層面。

建立不丟失承運商詳細資料的狀態模型

並不存在一套所有 Shipping API 及承運商共用的通用數字配送狀態代碼。來自某項整合的數值，不應使用另一家供應商的映射方式解讀。請使用你所實作的特定 API 版本的文件。

實用的內部模型可以將少量標準化狀態與原始承運商事件結合。標準化有助於一致的報告；原始事件則保留調查所需的詳細資料。

示例內部狀態含義營運注意事項
已收到資料電子貨件資料已存在。不要將建立標籤視為已確認的實體交接。
運送中追蹤記錄顯示包裹正在配送網絡中移動。此廣泛分類可能包括不同運輸階段。
派送中包裹據報正在配送路線上。不要將此狀態轉化為無條件的送達保證。
等待領取預期收件人領取包裹。只有在來源支持時，才加入領取指示或期限。
已送達追蹤來源報告已完成配送。單憑配送掃描記錄，不能解決客戶聲稱未收到貨件的問題。
例外某個事件可能需要處理或中斷正常進度。保留具體原因，不要將所有例外都視為遺失。
退回途中或已退回包裹正在退回，或已報告完成退回。將退回進度與送往原收件人的配送分開處理。
未知現有資料無法可靠地映射。調查映射或資料缺口，不要自行捏造配送狀態。

這些標籤是建議的應用程式模型，而不是官方 17TRACK 代碼清單。在可行的情況下，保留供應商的狀態代碼、子狀態、描述、事件時間、時區資料、位置及接收時間。同時保留映射版本，以便日後審核映射變更。

對於多承運商實作，17TRACK Tracking API 是相關的整合選項。請使用其官方 API 文件建立實作合約，不要將示例標籤直接複製到供應商專用欄位。在建立介面卡前，確認適用的狀態定義、webhook 設定、驗證要求及回應語義。

圍繞可靠接收建立 webhook 處理

Webhook 是發送到你的端點、用於報告事件的 HTTP 請求。它可以減少重複輪詢的需要，但不應被視為即時、有序或恰好一次傳送的保證。除非供應商明確保證，否則接收器應設計為能夠容忍重試、中斷及非預期的 payload。

  1. 驗證請求。採用供應商文件所述的驗證方法。如果支持簽名，請使用指定演算法及原始請求位元組進行驗證。不要自行發明簽名標頭，也不要假設每項服務都使用 HMAC。
  2. 驗證 payload。檢查必要欄位、類型、payload 大小，以及它是否關聯到由你的帳戶管理的貨件。處理未知的可選欄位時，不要無必要地破壞向前兼容性。
  3. 確認前先持久化。在發送文件指定的成功回應前，儲存已接受的事件或將其放入持久佇列。如果持久化失敗，不要確認事件已安全接收。
  4. 非同步處理。在可行的情況下，將狀態映射、訂單更新及通知決策放在請求處理程序之外執行。
  5. 讓副作用具備冪等性。重複事件不應建立另一張支援工單，或再次發送相同的客戶訊息。

確切的確認代碼、逾時時間、重試安排及重播行為取決於供應商。請明確查閱這些細節。「返回 200」這種一般指示不能取代 webhook 合約。

使用 HTTPS，並避免將憑證放入 URL 及一般日誌。對已儲存的 payload 實施存取控制，因為追蹤資料可能包含個人資料。OWASP REST Security Cheat Sheet 提供有關傳輸保護、輸入驗證及端點安全的相關指引。

去重事件而不抑制真正的更新

如果有可用的、文件明確記載且穩定的事件識別碼，應優先使用。否則，應從精心選取的貨件身份、事件時間戳、事件代碼及位置組合中建立去重鍵。請使用實際 payload 測試此方法：兩個合法事件可能共用相同時間戳，而同一事件也可能以略有不同的描述文字到達。

對事件接收及下游操作使用分開的去重控制。狀態更新可能需要再次儲存作為修正，但客戶通知則應繼續抑制。為每項通知或工單操作指定其自身的持久身份。

分開處理事件時間及接收時間

假設一個運送中事件在派送中事件之後到達你的系統，但其承運商時間戳較早。將它儲存在歷史記錄中，但不要自動將目前狀態改回運送中。

單靠時間戳排序不足以處理所有情況。缺少時區、修正掃描及來源衝突都需要明確規則。保留時間戳精度及偏移量，記錄系統接收每個事件的時間，並在可行時使用供應商記載的順序資料。不要強行使用只能向前的狀態階梯：配送嘗試、改派、退回及修正都可能造成看似倒退、但實際合理的狀態轉換。

將例外轉化為由負責人處理的行動

例外警報應說明發生了甚麼、需要採取甚麼行動，以及下一步由誰負責。籠統的「貨件例外」訊息會讓營運人員重複相同調查，也可能在沒有提供幫助的情況下令客戶感到擔憂。

  • 地址或存取問題：交由客戶支援核實問題，並查閱承運商可提供的修正流程。在確認可行前，不要承諾可以更改地址。
  • 需要領取：當來源提供可使用的領取指示時，通知收件人。保留任何已核實的期限。
  • 需要海關行動：根據誰需要提供所要求的文件或資料來分配個案。單獨的海關相關事件不能證明需要付款。
  • 配送嘗試未成功：在建議重新派送或領取前，先查看報告中的下一步。
  • 退回寄件人：開啟營運審查。除非你的政策明確授權，否則不要僅根據寬泛的追蹤標籤自動退款。
  • 承運商報告遺失或損壞：交由索償負責人處理並保留事件證據。索償決策應與一般延誤偵測分開。

每個警報應包含貨件識別碼、訂單參考、事件原因、來源時間戳、最新已知狀態、指定負責人及下一步行動。加入相關內部記錄的連結，而不是在共享訊息頻道中暴露不必要的客戶資料。

將「沒有更新」視為獨立狀況

近期沒有掃描記錄的貨件不一定已遺失。它可能正處於檢查點之間、等待首次實體掃描，或受到可見性缺口影響。

應按服務、路線、配送階段及業務承諾定義不活躍門檻，而不是套用一個通用計時器。區分從未收到接收掃描的包裹與進入配送網絡後停止更新的包裹。如果歷史證據有限，應以門檻觸發調查，而不是宣布貨件遺失。

當未有變更的個案仍然開啟時，抑制重複警報。當出現新證據、錯過約定跟進，或客戶配送承諾需要介入時，再作升級。

分開監控整合健康狀況及配送表現

API 監控回答的是追蹤整合是否正常運作。配送監控回答的是貨件正在發生甚麼事。健康的端點可能接收到過時的承運商資料，而不可用的端點也可能錯過正常移動中包裹的更新。

  • 請求健康狀況：追蹤驗證失敗、逾時、速率限制回應、伺服器錯誤及應用程式層面的拒絕。
  • Webhook 健康狀況：追蹤驗證失敗、確認延遲、持久化失敗、重複傳送及處理錯誤。
  • 處理健康狀況：監控佇列年齡、未處理事件、映射失敗及通知失敗。
  • 追蹤新鮮度：分開量度距離最後來源事件的時間，以及距離上次成功接收的時間。
  • 營運結果：追蹤未解決例外、分配負責人的時間及逾期跟進。

對於請求重試，請遵循供應商的速率限制及重試指引。避免盲目重複可能建立重複登記或其他副作用的操作；在可行時使用文件記載的冪等機制。

在支持的情況下，使用協調程序在中斷或懷疑遺漏事件後取得最新追蹤記錄。其頻率應設定在合約及速率限制範圍內。Webhooks 及協調程序有不同用途：前者傳送變更，後者有助於偵測及修復缺口。

在啟用客戶通知前測試失敗情況

先只進行內部處理，檢查具代表性的貨件，然後才允許狀態變更觸發客戶訊息。測試不應只涵蓋從運送中到已送達的正常進度。

  • 重複 webhook 只會建立一個預期的客戶通知。
  • 較早的事件延遲到達時，不會錯誤地取代目前狀態。
  • 未知狀態會被保留並標記，而不是悄悄映射為已送達。
  • 持久寫入失敗不會產生成功確認。
  • 暫時性的下游中斷會讓事件保持可重試。
  • 已送達事件之後出現修正時，仍可進行審核。
  • 多包裹訂單不會因只有一個包裹送達而變成全部已送達。
  • API 中斷會通知工程團隊，而不會自動告知客戶其包裹延誤。

發布標準應是營運一致性：貨件記錄、客戶訊息及支援行動必須與相同的底層證據一致。Webhook 回應成功本身不能證明配送體驗正常運作。

常見問題

HTTP 200 是否代表包裹已送達？

不是。它只表示該請求在 HTTP 層面成功。應分開讀取 API 的業務結果及貨件狀態欄位。對 webhook 而言，成功確認涉及收到通知，而不是包裹實際送達。

我應使用 webhooks 還是輪詢來取得追蹤更新？

當供應商支持時，應使用 webhooks 取得事件驅動的更新。在支持且具備營運理由的情況下，加入受限制的協調輪詢以恢復缺口。當 webhooks 不可用時，單獨使用輪詢可能合適，但其頻率必須遵守供應商限制及你的新鮮度要求。

為甚麼追蹤狀態在「已送達」後仍會變更？

來源可能會修正事件，或你的整合可能收到延遲或互相衝突的資料。保留歷史記錄並評估較新的證據，而不要將已送達視為技術上不可變更。報告的配送完成與客戶確認收到貨件也是兩項不同事實。

例外警報應多快發送？

應根據所需行動及任何已核實期限決定緊急程度。需要收件人採取行動的問題，應與資訊性延誤採用不同處理方式。處理速度無法彌補承運商延遲發布的事件，因此應同時保留來源時間戳及接收時間戳。

客戶應否看到原始承運商狀態？

通常，客戶更需要清晰的解釋及可行的下一步，而不是沒有解釋的代碼。保留原始詳細資料供支援及審核使用。切勿將狀態簡化成比底層事件所支持的更強承諾。

來源

Loading