在提交到 API 前如何验证追蹤號碼:需要遵循的 7 條規則
在將追蹤號碼傳送至追蹤 API 前,應分層驗證:先將輸入標準化,檢查其基本結構,確認承運商內容,僅在承運商文件提供校驗碼規則時套用校驗碼,並拒絕明顯不安全或不完整的值。不要依賴單一通用正則表達式。追蹤號碼格式會因承運商、服務、國家/地區及貨件類型而異,因此有效的驗證器應在避免錯誤請求的同時,不阻擋採用不熟悉格式的合法號碼。
本指南適用於將貨件追蹤整合至訂單管理系統、倉庫工作流程、客戶入口網站或電子商務應用程式的開發人員及營運團隊。目標並不是在提交前證明包裹確實存在。語法驗證與貨件狀態驗證是兩個獨立步驟。
驗證可以及不可以確認的事項
提交前驗證器可以識別常見的輸入問題,例如空值、意外空格、不支援的字元、長度過長,或將追蹤號碼放入錯誤欄位。當承運商已知且格式有文件記錄時,驗證器亦可能識別出可能的承運商。
通常無法確認號碼是否屬於真實貨件、包裹是否已由承運商接收,或號碼目前是否可以追蹤。這些問題需要透過承運商或追蹤平台查詢。號碼可能通過格式檢查,但仍然未被使用、存在細微輸入錯誤、已過期,或與其他服務相關聯。
七項規則
1. 在不改變含義的情況下標準化值
使用者及上游系統經常加入前置或尾隨空格、換行、不換行空格或格式化字元。在驗證前,應安全地將這些內容標準化。常見的第一步是移除周圍空白,並將不可列印空白轉換為普通空格。如果承運商記錄的格式允許內部空格或連字符,應決定是在 API 請求中移除它們,還是保留原始值以供顯示及稽核。
在可行的情況下保留兩個值:原始輸入值及標準值。原始值有助支援團隊調查資料質素問題;標準值則用於驗證及提交。避免進行可能改變識別碼的轉換。除非相關承運商或 API 文件明確支援,否則不要自動將字母轉換為數字、替換容易混淆的字元,或移除所有標點符號。
Unicode 處理值得注意。來自另一種字母系統的視覺相似字元,即使看起來像 ASCII 字母或數字,也可能不被 API 接受。將標準值限制在所選整合方案允許的字元集內,有助避免令人困惑的下游錯誤。
2. 拒絕未通過基本結構檢查的值
在套用承運商專屬邏輯前,檢查值是否存在且合理。實用檢查包括最小及最大長度、允許的字元類別,以及值是否只包含空白,或是否為「N/A」、「TBD」或「test」等佔位符。確切限制應來自 API 合約或承運商文件。不要僅因大多數示例都很短,就自行設定通用的最大長度。
結構檢查應保持有意識的保守程度。例如,只允許數字的規則會拒絕有效的英數字元識別碼;要求固定長度的規則可能拒絕服務變體或國際格式。使用通用檢查捕捉明顯錯誤,只有在承運商及服務已知時才套用更具體的檢查。
亦應在應用程式邊界驗證資料類型。追蹤號碼通常應視為字串,而不是整數。數值轉換可能移除前置零,並可能在使用固定寬度數值類型的系統中造成精度問題。完成獲批准的標準化後,應將值完整保留為字串。
3. 使用承運商內容,而不是單憑號碼猜測
沒有承運商資訊的追蹤號碼屬於含糊輸入。不同承運商可能使用重疊的長度、前綴或字元集;對某一承運商看似合理的格式,對另一承運商可能無效。如果訂單、標籤、倉庫系統或商戶帳戶已識別承運商,只要 API 支援,便應將該內容與追蹤號碼一併傳送。
承運商內容可改善驗證及路由。它讓應用程式選擇相關格式規則、減少錯誤匹配,並令錯誤訊息更有用。當多個承運商都可能接受外觀相似的值時,它亦能防止將自動偵測結果當作事實。
如果承運商未知,應採用兩階段方法。首先執行通用安全檢查。接着,僅透過明確支援承運商偵測的 API 流程提交值;如果業務流程要求確認承運商,則將其放入審查佇列。除非該映射有維護及文件記錄,否則不要只根據前綴默默指定承運商。
4. 僅在規則有文件記錄時套用校驗碼
部分識別碼系統使用校驗位,但追蹤號碼並沒有統一的校驗碼標準。校驗碼可以偵測某些抄寫錯誤,但不能證明貨件存在。更重要的是,套用錯誤的校驗碼演算法可能會拒絕有效號碼。
只有在相關承運商、服務、標籤規格或 API 文件定義了演算法及其涵蓋的輸入部分時,才實作校驗碼。記錄規則版本,並使用官方示例進行測試。如果沒有權威規則,應跳過校驗碼,而不是根據小樣本中觀察到的模式猜測。
將校驗碼結果視為其中一項訊號,而不是完整的驗證決定。當規則具權威性時,檢查失敗可以成為阻止提交的理由;檢查通過則應將值推進至下一階段,而不是將其標記為現存貨件。
5. 將格式驗證與 API 資格分開
值的格式可能正確,但仍不適合你正在呼叫的端點。提交前,檢查 API 文件中的必填欄位、接受的承運商識別碼、驗證要求、請求限制、重複處理行為,以及對服務類型或目的地的任何限制。這些是整合規則,而不是追蹤號碼規則,但它們決定有效識別碼能否成功處理。
17TRACK Tracking API 文件正好說明了這種區分的重要性:開發人員需要遵循平台的請求模型及支援的整合行為,而不是根據追蹤號碼的外觀自行設計請求。請參閱最新文件,了解端點要求及回應處理方式:17TRACK API 文件。
將驗證錯誤與傳輸及驗證錯誤分開。「追蹤號碼格式無效」、「未知承運商」、「已達到速率限制」及「授權失敗」需要不同處理方式。單一通用的「提交失敗」訊息會降低重試及營運報告的可靠性。
6. 透過有界輸入、去重及安全重試保護 API
驗證亦是一項營運保障。在解析或記錄前,強制執行有界輸入長度。拒絕控制字元及意外的負載結構。在你自己的應用程式邊界套用速率限制,避免錯誤匯入產生失控的請求突發。
當業務流程不需要重複註冊時,應在提交前進行去重。實用的去重鍵可能包括標準追蹤號碼、承運商、帳戶及貨件內容。正確的鍵取決於你的工作流程;同一識別碼有時可在不同服務或業務記錄中重複使用,因此不要假設號碼本身總是全域唯一。
對暫時性故障使用帶退避的有界重試,並避免重試永久性驗證錯誤。當 API 及你的架構支援時,儲存冪等性或提交記錄。記錄足夠資料以排查請求問題,但要保護憑證、客戶資料及任何敏感貨件詳情。驗證器應減少重複故障,而不是因過度記錄造成第二個安全問題。
7. 提交後確認結果,並監察誤判
最後一項規則是將提交前驗證視為閘門,而不是裁決。請求獲接受後,檢查 API 回應並儲存其狀態、請求識別碼、承運商關聯及任何有文件記錄的錯誤代碼。如果平台接受請求,但尚未能返回流轉事件,這可能表示處理延遲,而不是號碼無效。
為持續未解決的號碼制定跟進政策。時間窗口應反映承運商、服務、貨件來源及你的客戶服務政策;沒有一個通用時段可以證明號碼無效。對缺少承運商、供應商錯誤重複出現、承運商結果互相矛盾,或狀態與訂單記錄不符的記錄進行升級處理。
衡量錯誤拒絕及錯誤接受。嚴格的正則表達式可能減少格式錯誤的提交,但同時錯誤阻擋合法貨件。寬鬆的驗證器可能增加已接受請求,但在下游製造噪音。按承運商及服務檢視失敗樣本,透過版本控制更新有文件記錄的規則,並使用具代表性且保護私隱的測試固定資料集測試變更。
實用的驗證流程
可維護的實作可以採用以下流程:
- 檢查請求是否包含字串值及有效的業務記錄。
- 儲存原始輸入,然後建立有文件記錄的標準形式。
- 拒絕空值、佔位符、不安全字元,以及超出有文件記錄長度範圍的值。
- 從可信的訂單資料解析承運商,或使用明確支援的偵測流程。
- 僅在權威文件支援時,套用承運商專屬語法及校驗碼規則。
- 檢查端點要求、重複狀態及重試資格。
- 提交、分類回應、儲存結果,並為未解決記錄安排跟進。
這個流程讓驗證器更容易測試,因為每項決定都有不同原因。它亦能為營運團隊提供可採取行動的失敗類別,而不是單一不透明的錯誤。
實作清單
- 將追蹤號碼儲存為字串,以保留前置零。
- 在需要可稽核性時,分開保留原始值及標準值。
- 將承運商規則作為有版本的配置維護,而不是散落在硬編碼條件中。
- 測試字母、數字、連字符、空白、Unicode 外觀相似字元、佔位符及邊界長度。
- 只要有可信的承運商內容,就應使用它。
- 不要根據成功的正則表達式匹配推斷貨件存在。
- 將永久性驗證錯誤與暫時性 API 或網絡錯誤分開分類。
- 在更改格式規則或請求邏輯前,先檢視供應商文件。
常見問題
正則表達式可以驗證追蹤號碼嗎?
當承運商及服務格式已知時,它可以驗證有限的模式。但它無法證明號碼存在、屬於特定貨件,或目前仍然有效。通用表達式很可能造成錯誤拒絕或錯誤匹配。
看起來無效的號碼應否提交至 API?
明顯為空、不安全或結構上不可能的值,通常應在提交前停止。對於不熟悉但其他方面安全的格式,不應僅因其不符合內部猜測而拒絕。應先檢查承運商文件或使用支援的偵測流程。
校驗碼足以確認貨件嗎?
不可以。在適用的情況下,校驗碼只能測試該值是否符合數學規則。它不能確認承運商曾發出該號碼,或包裹已進入運輸網絡。
承運商未知時應怎樣處理?
執行通用安全檢查,並在可用時使用明確支援承運商偵測的 API 工作流程。否則,應保留記錄以作資料補充或人工審查,而不是默默猜測承運商。
應如何處理 API 錯誤?
按原因分類。修正格式錯誤的輸入及不支援的承運商值;對暫時性網絡或供應商故障,在限制及退避機制下重試;將驗證或配額錯誤轉交整合負責人。儲存診斷所需的回應詳情,但不要暴露秘密資料。
來源
- 17TRACK API 文件 — 為追蹤 API 開發人員提供請求及整合指引。
- 17TRACK Tracking API — 官方產品資料及 API 使用案例。
- USPS Tracking — 官方承運商追蹤入口及客戶指引。
- UPS Tracking — 官方承運商追蹤入口。


