Skip to main content
首頁博客指南追蹤 API 應返回哪些資料?目前狀態以外的 12 個欄位?

追蹤 API 應返回哪些資料?目前狀態以外的 12 個欄位?

17TRACK

A tracking API 應返回的不只是「運輸中」之類的標籤。除了目前狀態外,還應提供貨件識別碼、承運商身份、詳細狀態資料、承運商原始訊息、事件歷史、事件時間戳、地點、預計送達時間、例外情況、承運商交接資料、送貨詳情,以及資料新鮮度中繼資料。這 12 組資料可協助開發人員建立可靠的工作流程,並為營運團隊提供足夠背景以採取行動。

What Data Should a Tracking API Return 12 Fields Beyond

這是為開發人員、技術採購人員及電子商務營運團隊建議的回應合約,並不表示每間承運商或每個 API 都會提供所有欄位。部分數值合理地可能無法取得。更好的設計是明確表示這些缺口,而不是以假設填補。

甚麼令追蹤資料具備實用價值?

目前狀態只能回答一個狹窄問題:貨件的概括狀態是甚麼?它未必能說明發生了甚麼、何時發生、資料是否最新,或下一步應採取甚麼行動。

例如,兩件貨件都可能顯示「運輸中」,但需要不同的處理方式。其中一件可能最近在設施完成掃描,且沒有報告任何問題;另一件則可能在事件歷史中記錄了尚未解決的地址問題。只讀取主要狀態的應用程式可能會忽略這項差異。

根據三項實際任務評估回應:將貨件配對至正確訂單、準確解釋其進度,以及判斷是否有理由採取行動。以下欄位可支援這些任務。欄位名稱僅作示例,並非通用標準或特定供應商的結構。

除目前狀態外需要評估的 12 個欄位

1. 貨件及追蹤識別碼

回應應識別所描述的貨件。實用數值包括提交的追蹤號碼、API 的追蹤記錄識別碼,以及可讓你的系統對應至履行或包裹記錄的客戶參考編號。

不要假設一張訂單等於一件貨件。訂單可能分拆成多個包裹,而換貨或補寄也可能產生另一件貨件。請在包裹或履行層級儲存追蹤記錄,再將其與訂單關聯。追蹤號碼應以字串儲存,以免遺失格式及前導零。

2. 承運商身份

除了易讀的承運商名稱外,亦應尋找穩定的承運商識別碼。如有提供,回應應區分由你的應用程式明確提供的承運商,以及透過自動偵測選出的承運商。

承運商背景資料對解讀追蹤號碼及事件十分重要。如果偵測結果不明確,你的整合方案應能解決這種情況,而不是將不確定的配對默默顯示為已確認。服務層級資料應獨立處理:單憑承運商名稱,不能確定貨件使用的是特快、郵政或其他服務。

3. 標準化狀態詳情

除主要狀態外,應要求有文件說明的詳細代碼或子狀態。廣泛分類可能只將貨件描述為例外,而詳細狀態則指出是派送嘗試、地址問題,還是與海關有關的暫扣。

業務邏輯應使用穩定代碼,展示內容則使用易讀標籤。確認供應商如何將承運商事件映射至這些代碼,包括如何處理未知或未映射事件。標準化標籤可讓不同承運商的資料流更易於使用,但不應抹去支援團隊所需的差異。

4. 承運商原始訊息及代碼

如有提供,應保留原始事件描述及承運商事件代碼。這些數值可為支援人員提供標準化狀態中可能缺少的背景,尤其是承運商使用特定營運措辭時。

原始文字應與翻譯或改寫後的描述分開儲存。否則,面向客戶的解釋可能被誤認為承運商的原文。展示承運商文字時,應將其視為不受信任的輸入:適當轉義,不要將其渲染為可執行 HTML。

5. 追蹤事件歷史

實用的回應應公開貨件時間線,而不只是最新事件。每個事件最好包括識別碼、狀態或代碼、描述、時間戳,以及可用的地點資料。

確認 API 返回的是完整歷史、有限時間範圍,還是分頁結果。同時確定修正及重複觀察如何表示。除非回應合約明確保證排序,否則應用程式不應假設第一項一定是最新項目。

6. 事件時間戳及時區資料

事件發生時間與 API 接收或返回事件的時間並不相同。如有提供,應保留兩者。這項區分有助解釋為何新接收的更新可能描述較早發生的事情。

應要求提供帶有明確 UTC 偏移量或 UTC 標記的時間戳。RFC 3339 定義了適用於互聯網協議的時間戳格式,包括數字時間偏移量。如果來源只提供沒有已知偏移量的本地時間,應保留這項不確定性,而不是默認將其視為 UTC。當底層來源只提供日期時,切勿暗示具備秒級精確度。

7. 事件地點及貨件地理位置

如有提供,應尋找城市、地區、國家及郵政編碼等結構化地點組成部分。如果轉換為結構化欄位可能失去含義,也應保留原始地點字串。

掃描地點不一定是包裹的實時位置。同樣,最後報告的設施也不代表包裹仍然留在該處。面向客戶的頁面應將其描述為最新報告的位置。不要從不完整的掃描文字推斷座標或確切送貨地址。

8. 預計送達日期或時間範圍

預計送達欄位應指出其包含單一日期還是時間範圍、由誰產生,以及最後更新時間。承運商提供的估算與另外計算的預測應保持可區分。

不要將只有日期的估算轉換為精確到達時間。整合方案也應處理經修訂或撤回的估算,避免追蹤頁面保留過時承諾。如果沒有估算,應顯示其不可用,而不是根據沒有依據的假設自行計算。

9. 例外原因及所需行動

例外資料應解釋問題,並在來源支援的情況下指出行動、負責方或限期。一般延誤通知在營運上不同於要求收件人提供資料。

已報告的事實應與你自己的工作流程決定分開。例如,企業可能在一段設定時間沒有更新後建立支援任務。這是內部升級規則,不是承運商已宣布包裹遺失的證據。不要根據含義不明的追蹤文字產生付款指示或敏感資料要求。

10. 承運商交接及相關追蹤號碼

當貨件在不同營運商之間轉移時,實用資料包括下一間承運商、相關追蹤號碼,以及原始記錄與下游記錄之間的關係。當派送環節使用不同識別碼時,這有助維持連續性。

應將已報告的交接視為一種關係,而不是覆蓋原始承運商。不要僅因目的地或追蹤號碼看似相近便合併記錄。如果沒有提供或確認這項關係,應保留未解決狀態,而不是臆造一段連續旅程。

11. 送達結果及證明參考資料

當報告顯示已送達時,回應應提供記錄的送達時間及任何可用的送貨詳情,例如安全放置地點描述或收件人類別。如果承運商及服務提供,送達證明參考資料也可能很有用。

不應將「已送達」狀態視為目標收件人親自接收包裹的證明。簽名、相片、姓名及精確位置可能包含個人資料。應限制存取權限,避免在公開追蹤頁面披露這些詳情,並確認證明連結的授權或有效期要求。

12. 新鮮度、提取狀態及回應中繼資料

應要求足夠中繼資料,以區分最新貨件事件與最近一次成功的資料提取。實用數值包括最近一次成功檢查、最近一次失敗嘗試、回應產生時間,以及返回的資料是否為快取或部分資料。

API 請求成功本身並不能證明承運商已發布新的掃描記錄。HTTP 回應語義描述請求結果;貨件進度則屬於應用程式資料。應將提取錯誤與貨件例外分開保存,以免暫時的連線問題變成錯誤的送達警報。

缺少資料需要明確定義含義

欄位是否存在只是合約的一部分。你的團隊也需要理解缺少數值代表甚麼。送達估算可能是來源沒有提供、尚未提取,或送達後不適用。這些情況不應自動產生相同的客戶訊息。

  • 未知:尚未確定該數值。
  • 未提供:來源沒有在所提取的資料中提供該數值。
  • 不適用:該欄位不適用於此記錄或狀態。
  • 提取失敗:系統無法完成相關查詢。

以上是建議的區分,不是必須使用的字面值。無論選擇何種表示方式,都應記錄說明。避免使用佔位日期、看似有效記錄的空物件,以及可能被誤認為真實位置的預設座標。

整合前如何測試回應

評估來自你的企業實際使用的承運商、服務及運輸路線的有效載荷。結構可以列出可選欄位,但不代表每個底層來源都會填入該欄位。對於 17TRACK 整合,請使用官方 Tracking API 文件檢查回應合約,不要將本指南中的概念欄位名稱視為可直接複製使用的參數。

  1. 建立具代表性的樣本。包括新登記貨件、運送中的貨件、派送嘗試、已完成送達,以及可用的交接案例。
  2. 將欄位追溯至事件。確認顯示的狀態、最新事件及送貨詳情描述的是一致記錄。遇到差異時應調查,而不是隱藏。
  3. 測試延遲及重複更新。重新處理相同有效載荷,並在較新事件後接收較舊事件。確認兩種情況都不會產生重複通知或錯誤地逆轉顯示狀態。
  4. 測試缺少及格式錯誤的數值。包括缺少估算、未知地點、不熟悉的狀態代碼及不完整時間戳。應用程式即使不臆造替代值,也應保持可用。
  5. 分開傳輸失敗與追蹤結果。身份驗證失敗、逾時或格式錯誤的回應應進入整合錯誤流程,而不是貨件例外工作流程。
  6. 驗證客戶視圖。確認內部參考資料、原始診斷詳情及個人資料不會洩露至公開頁面或通知。

對於基於 webhook 的更新,還應根據供應商文件檢查傳送識別碼、身份驗證、重試行為及重播處理。這些是整合要求,而不是貨件事實。接收器應安全處理重複傳送,不應假設接收順序等於事件順序。

驗收標準應切合實際:你的應用程式能否在沒有作出無依據聲稱的情況下解釋貨件,而你的營運團隊能否識別下一個有理由採取的行動?較小但定義清晰的有效載荷,可能比充滿未解釋可選數值的較大回應更有用。

常見問題

每件貨件都需要填滿全部 12 組資料嗎?

不需要。送達證據、下游追蹤號碼及預計送達日期可能不可用或不適用。與其要求所有欄位一律填入,不如要求清晰的欄位定義及可預測的缺失值行為。根據實際運輸組合,檢查最重要的欄位。

我們應儲存原始回應,還是只儲存標準化欄位?

應儲存標準化欄位供應用程式邏輯使用。在符合私隱、安全、合約及保留要求的前提下,保留相關來源有效載荷也有助除錯及處理映射變更。應限制存取權限,不要僅因敏感內容出現在回應中便保留該內容。

哪個時間戳應決定最新事件?

應使用有文件說明的事件時間順序及供應商排序規則,同時考慮時區及修正。接收時間只表示你的系統何時得知事件,不一定是事件發生的時間。如果時間戳不完整或互相矛盾,應保留這項含糊性,而不是聲稱有精確順序。

追蹤 API 能否確認包裹已遺失?

只有在來源明確支援這種解讀時,才可將遺失視為承運商報告的結果。長時間沒有掃描可根據你的營運規則進行調查,但單靠沉默不能證明遺失。應將「追蹤資料過時」及「已報告遺失」視為兩個不同概念。

「已送達」狀態是否足以結束客戶投訴?

不一定。它確立了已報告的追蹤結果,但未必能解決收件人的爭議。應檢查可用的送貨詳情、客戶帳戶及你的支援流程。不要將狀態標籤視為調查矛盾資料的替代品。

來源