Skip to main content
首頁博客指南如何在一個 API 請求中傳送多個追蹤號碼(批次限制與部分失敗)

如何在一個 API 請求中傳送多個追蹤號碼(批次限制與部分失敗)

17TRACK

如要在一次 API 請求中傳送多個追蹤號碼,請使用明確接受批次請求的 Tracking API 端點,按照其請求結構為每件貨件設定格式,並將較大的清單拆分成符合文件所述限制的批次。然後檢查 HTTP 回應及每件貨件的結果:HTTP 請求成功並不一定代表每個追蹤號碼都已被接受。只重試符合條件的失敗項目,並在重新提交整個批次前,先處理結果不確定的項目。

如何在一次 API 請求中傳送多個追蹤號碼

本指南適合將貨件追蹤連接至訂單管理系統、倉庫平台、電子商務應用程式或內部儀表板的開發人員。目標不只是減少請求次數,而是在不造成重複工作或遺失失敗記錄的情況下,確保每件貨件都得到處理。

首先,確認批次端點實際執行的操作

追蹤整合可能涉及多項不同操作。登記貨件、取得最新追蹤資料,以及接收後續更新,並不是可互相替代的操作。

  • 登記:提交貨件,讓服務開始或繼續追蹤這些貨件。
  • 查詢:根據端點的資料取得規則,要求取得貨件的追蹤資料。
  • 配送更新:透過支援的機制(例如 Webhook)接收後續變更,或透過定期請求取得更新。

請查閱文件,確認所需的確切操作。接受多筆記錄的登記端點,並不代表查詢端點也接受相同數量、使用相同結構或共用相同速率限制。

如要整合 17TRACK,請先查看 Tracking API 產品頁面,並使用官方 API 文件確認操作、驗證方法、請求格式及回應欄位。以下範例應視為實作模式,而非取代該 API 合約。

批次限制不只是貨件數量上限

Tracking API 並沒有通用的批次限制。限制可能因供應商、端點、API 版本及帳戶設定而異。在實作批次處理前,請分別記錄以下限制。

限制需要確認的事項對實作的影響
每次請求的項目數特定操作可接受的最大記錄數傳送前拆分輸入清單
請求本文大小文件列明的任何位元組限制考慮可選欄位及序列化後的大小
請求速率指定時間間隔內允許的請求數透過共用限制器控制請求速度
並行數任何同時請求限制限制活躍工作執行緒的數量
用量計算用量按請求、貨件或其他單位計算將用量與請求量分開估算

例如,假設某端點每次請求允許 25 筆記錄,63 筆記錄便需要三次請求,分別包含 25、25 及 13 筆記錄。這些數字只用於示範分批方式,並非 17TRACK 所列明的限制。

不要假設批次處理會減少可計費用量。它可以減少 HTTP 請求開銷,但對費用的影響取決於供應商實際的計費規則。同樣地,符合要求的批次大小也不代表可以無限制地並行發送請求。

建立請求前準備記錄

大部分可避免的批次失敗都始於輸入準備。在將貨件加入批次前,先驗證每件貨件,但要避免規則意外拒絕來自不同承運商的有效追蹤號碼。

  1. 將追蹤號碼保留為字串。將其轉換為數字可能會刪除開頭的零,或改變較長的識別碼。
  2. 移除意外的前後空格。除非相關規格允許,否則不要移除內部字元或更改大小寫。
  3. 驗證必要欄位。某些工作流程可能需要承運商識別碼或其他貨件資料。只使用文件列明的欄位名稱及值。
  4. 明確選擇去重範圍。同一追蹤號碼並不一定在每個承運商、商戶或歷史貨件中都屬於重複項目。
  5. 保留本地貨件識別碼。即使 API 不接受自訂參考欄位,也要儲存外發項目與訂單或貨件記錄之間的關係。

對於跨多個網絡的 Carrier Tracking,除非在你的特定工作流程中這種推斷可靠,否則不要僅根據追蹤號碼的長度或前綴推斷承運商。如果 API 支援承運商識別,請遵循其文件所述的歧義處理方式。

示例請求結構

以下 JSON 展示批次 payload 的概念。包裝結構、屬性名稱及識別碼只作示例,並不是 17TRACK 的請求結構。部分 API 要求頂層為陣列,而不是包含陣列的物件。

{
  "shipments": [
    {
      "tracking_number": "EXAMPLE000001",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    },
    {
      "tracking_number": "EXAMPLE000002",
      "carrier_id": "DOCUMENTED_CARRIER_ID"
    }
  ]
}

請透過 JSON 序列化工具建立 payload,而不是串接字串。透過文件指定的機制傳送驗證憑證,並將其排除在原始碼管理、傳送至瀏覽器的程式碼及一般日誌之外。

在兩個層級處理回應

批次請求同時有傳輸層級結果及應用程式層級結果。你的整合必須同時評估兩者。

第一層:請求是否收到可用回應?

先檢查 HTTP 狀態、回應標頭及回應本文。驗證錯誤、格式錯誤的請求、速率限制及伺服器故障,可能會阻止正常處理項目。網絡逾時則有所不同:用戶端可能不知道伺服器是否收到或處理了請求。

HTTP 語義定義於 RFC 9110。不過,供應商的文件決定其應用程式層級結果欄位如何對應至實際貨件結果。

第二層:每件貨件發生了甚麼事?

如果回應支援項目層級結果,請為每筆已提交記錄分類。不要假設 HTTP 200 代表每筆記錄都成功,也不要假設結果清單會保留請求順序,除非合約明確保證這一點。

  • 已接受:根據端點文件所述的定義,操作已成功。
  • 永久性輸入失敗:在再次嘗試前修正或調查該記錄。
  • 可重試失敗:按照供應商的重試指引安排再次嘗試。
  • 結果不明:回應遺失、不完整,或無法安全地與已提交記錄配對。

在了解文件所述含義前,請將「已經登記」或類似的重複相關回應分開處理。這些回應可能表示所需狀態已存在,但不應自動視為成功取得擁有權、設定或訂閱確認。

處理回應後,每筆輸入記錄都應有且只有一個本地結果。一項有用的對賬檢查是:已提交記錄 = 已接受記錄 + 永久性失敗 + 可重試失敗 + 結果不明。這是本地記帳規則,而不是 API 必須採用的回應格式。

處理部分失敗,避免重放成功記錄

假設一個示例批次包含十件貨件:七件已接受、兩件缺少有效必要欄位,另一件遇到文件列明的暫時性錯誤。儲存七件成功結果,將兩筆無效記錄交由修正流程處理,並只重試暫時失敗的項目。

重放全部十筆記錄會造成不必要的流量,並使重複處理更加複雜,也更難區分原本的拒絕與其後的重複相關回應。

結果建議操作
欄位無效或值不受支援修正輸入;不要在不作變更的情況下重試
驗證或權限失敗暫停受影響工作,修復憑證或存取權限
速率限制回應按照文件指引及適用的回應標頭延遲請求
暫時性項目層級錯誤以有限次數及退避方式重試該項目
提交後逾時標記為不確定;進行對賬,或使用文件列明的重試安全保證
無法識別或不完整的結果保留證據並進行調查,不要假設成功

HTTP 429 表示請求過多,其回應可能包含 Retry-After 標頭,如 RFC 6585 所述。不要假設該標頭一定存在。如果沒有提供明確的重試延遲,請使用符合 API 文件的有限退避策略。

加入隨機抖動,分散多個工作執行緒的重試;設定最大嘗試次數或重試期限,並將耗盡重試次數的記錄送至審查佇列。無限重試可能掩蓋持續存在的設定問題。

為甚麼逾時需要特別處理

逾時並不能證明請求被拒絕。連線失敗前,伺服器可能已接受該批次。因此,自動重放會改變狀態的請求可能導致工作重複。

如果端點支援文件列明的冪等性金鑰,請遵循其規則,包括金鑰範圍及保留期限。不要自行創建冪等性標頭並假設伺服器會遵守。否則,請使用支援的查詢或對賬工作流程,在重新提交前確認所需狀態是否已存在。本地去重有助協調自有工作執行緒,但不能保證伺服器端的冪等性。

實用的批次處理工作流程

將供應商特定的細節保留在 adapter 中,讓佇列、重試排程器及監控邏輯不必依賴原始回應欄位名稱。

驗證記錄並保留本地貨件 ID
在預期的業務範圍內解決重複項目
按照文件列明的項目及 payload 限制拆分記錄

透過有限工作執行緒池處理每個批次:
    傳送前持久化儲存嘗試記錄
    等候共用速率限制器
    使用供應商專用 adapter 傳送

    如果結果不確定:
        加入對賬佇列
        繼續

    分類請求層級及項目層級結果
    為每筆已提交記錄持久化儲存一個結果
    只安排符合條件的失敗項目重試
    將無效或已耗盡重試次數的記錄送交審查

讓結果儲存及重試排程具備可恢復性。例如,持久化工作記錄或交易式佇列模式可以防止程序崩潰導致重試決策遺失。工作執行緒重新啟動時,應能區分尚未傳送的工作,以及遠端結果仍然不確定的工作。

將批次大小設定為與相關端點綁定的可配置設定,而不是散落在整個程式碼庫中的常數。排查問題或隔離異常記錄時,較小的批次可能更有用;最大允許批次並不一定是最佳操作大小。

監控貨件結果,而不只是 HTTP 正常運作時間

API Monitoring 應顯示貨件是否達到預期狀態。只報告 HTTP 成功率的儀表板,可能忽略成功回應內的部分失敗。

  • 項目接受率:已接受記錄除以已提交記錄,並清楚定義重試的處理方式。
  • 失敗分佈:按端點、文件列明的錯誤代碼及相關承運商背景統計數量。
  • 結果不明:尚未完成對賬的記錄,以及其維持未解決狀態的時間。
  • 重試積壓:待重試項目、最早重試的時間及已耗盡的嘗試次數。
  • 請求健康狀況:延遲、逾時、速率限制及伺服器錯誤。
  • 追蹤資料新鮮度:已接受貨件其後是否收到可用的追蹤資料。

登記獲接受並不代表出現新的承運商掃描記錄。請將 API 處理狀態與貨件移動及資料新鮮度分開,避免將整合事故與配送延誤混淆。

在可用時記錄本地批次 ID、貨件參考、嘗試次數、文件列明的錯誤代碼及供應商請求 ID。遮蓋憑證及不必要的個人資料。只在操作上有需要時使用追蹤識別碼,並避免將原始貨件識別碼放入高基數指標標籤。

投入生產前測試以下情況

在可用時使用文件列明的沙盒或受控測試環境。不要假設自行編造的追蹤號碼會在生產環境產生可預測的回應。

  1. 在文件列明的項目上限下提交有效批次,然後測試用戶端如何防止超大批次。
  2. 確認序列化及儲存過程會保留帶有開頭零的追蹤號碼。
  3. 測試同時包含已接受及被拒項目的批次,且不要重試成功記錄。
  4. 模擬速率限制,確認多個工作執行緒遵守相同限制。
  5. 模擬提交後逾時,並驗證對賬流程。
  6. 在收到回應與本地持久化儲存之間重新啟動工作執行緒。
  7. 測試缺失、不熟悉或無法配對的項目結果。
  8. 確認無效記錄會進入可見的修正佇列,而不是無限重試。

可投入生產的整合應能說明每件已提交貨件的狀態,包括結果暫時不明的貨件。減少請求次數固然有用,但維持這種可追溯性才是更重要的設計目標。

常見問題

我可以在一次請求中傳送多少個追蹤號碼?

請使用確切端點及 API 版本所列明的限制。同時檢查請求大小、速率限制及任何帳戶特定限制。不能在不同 Tracking API 之間,或同一 API 的不同操作之間套用一個安全的通用數字。

一個無效追蹤號碼會令整個批次失敗嗎?

可以,取決於端點的驗證規則。有些 API 會返回個別拒絕結果,另一些則可能在項目處理前拒絕整個請求。請同時檢查請求層級錯誤及項目層級結果;不要假設每個批次端點都支援部分接受。

HTTP 回應成功時,我應否重試批次?

不要自動重試。先解析文件列明的應用程式層級狀態及項目結果。儲存成功記錄,只重試符合條件的失敗。如果無法安全解讀結果,請將其分類為不確定並進行調查。

我可以在同一批次中混合不同承運商嗎?

只有在端點支援該請求結構時才可以。確認承運商資料是否按貨件提供、是否支援自動識別,以及識別結果不明時會如何處理。多承運商服務本身並不能證明每個端點的批次規則。

批次處理會令追蹤更新更快到達嗎?

批次處理可以減少應用程式發送的請求數量,但不會令承運商事件本身更早出現。登記、資料取得、承運商掃描可用性及更新傳送,是工作流程中不同的部分。

來源