如何透過一個 API 追蹤從中國運往歐洲及美國的貨件

要透過一個 API 追蹤由中國運往歐洲及美國的貨件，請將訂單系統連接至多承運商追蹤服務，使用每件包裹的追蹤號碼及任何所需的承運商資料進行登記，並將追蹤更新整合至共用貨件記錄中。整合方案必須考慮國際交接、掃描延遲，以及獨立的最後一公里追蹤號碼。一個 API 可以集中存取追蹤資料，但無法建立承運商尚未回報的事件。

對開發人員及電子商務營運團隊而言，目標不只是顯示狀態，而是將每件實體包裹連結至正確訂單，在不發送誤導性更新的情況下讓客戶了解進度，並識別需要介入處理的貨件。本指南將說明如何建立這套工作流程，以及如何根據實際運輸路線評估例如 17TRACK Tracking API 的服務。

從運輸路線開始，而不只是目的地國家

由中國寄往歐洲或美國地址的包裹，可能會經過集貨服務、國際運輸網絡、清關處理及目的地派送承運商。有些運輸服務會使用一個追蹤號碼展示整個運輸過程；其他服務則會在運輸途中稍後提供獨立的派送參考號碼。

因此，僅憑國家層面的覆蓋範圍不足以驗證追蹤整合。服務供應商可能識別某個承運商，卻未必能返回特定運輸產品所需的每個事件。同樣，始發地掃描並不能證明目的地派送掃描一定可用。

整合前，請使用業務實際發出的貨件建立路線清單。記錄始發地物流供應商、運輸服務、目的地市場、已知派送承運商及追蹤號碼格式。測試時應逐一處理歐洲市場，不要假設某一國家成功派送就代表整個地區均有覆蓋。

• 營運：識別目前哪些追蹤缺口造成手動工作或客戶查詢。
• 工程：識別哪些系統建立貨件，以及哪些系統需要接收更新。
• 採購：確認路線清單中的特定承運商及服務均獲支援。

一個追蹤 API 應該做到甚麼，以及不能做到甚麼

多承運商 Tracking API 為應用程式提供共用整合層，無需分別處理每個承運商的連接。視乎服務及整合方式，應用程式可能可以取得更新、接收回調，或兩者兼用。在設計正式工作流程前，請先在供應商文件中確認所支援的機制。

有用的抽象化方式是採用一致的貨件模型。訂單管理系統不應需要為每個承運商的用語編寫不同的業務邏輯，但應保留原始資料，以便支援及調查。

集中式追蹤並不保證持續的實體可見性、派送預計時間或完整的清關歷史。API 連接可以正常運作，但承運商可能沒有新的掃描可供回報。追蹤亦有別於購買運輸標籤、準備報關資料及安排派送服務。不要假設這些功能已包括在內。

以包裹層級記錄建立整合方案

1. 分開訂單、貨件及追蹤識別碼

一張電子商務訂單可以包含數件包裹，而這些包裹可能在不同時間送達。使用內部包裹或貨件 ID 作為穩定識別碼。將客戶訂單與該記錄關聯，再把承運商追蹤識別碼附加至該記錄。

實用的內部模型應包括：

• 內部訂單 ID 及包裹 ID。
• 原始追蹤號碼，以及 API 使用的承運商識別碼。
• 任何已確認的目的地承運商追蹤號碼。
• 運輸服務及目的地國家。
• 目前的標準化狀態及承運商原始描述。
• 事件時間、提供的事件地點，以及系統接收更新的時間。
• 登記狀態、上次成功同步時間及未解決的整合錯誤。

這些是建議的應用程式欄位，並不表示每個供應商都會返回這些資料。請將內部結構與供應商的回應格式分開，避免日後 API 變更時需要重新設計訂單資料庫。

2. 從可靠的業務事件登記包裹

當有效號碼分配至包裹時進行追蹤登記，而不是在有人查看訂單頁面時才登記。倉庫或訂單系統發出的「貨件已建立」事件通常是更好的觸發點。如果標籤被作廢或替換，請更新包裹的識別碼關係，不要將已棄用的號碼保留為唯一追蹤參考。

確認號碼存在，且沒有因試算表格式而損壞。保留有意義的前置零。當運輸系統知道承運商時，請保留該資料，不要完全依賴自動識別，因為不同承運商的號碼格式可能重疊。

請在單件貨件層級讀取登記回應。HTTP 請求成功不一定代表批次中的每件貨物均已被接受。將失敗項目儲存於重試佇列，並讓營運人員可以處理無效或不明確的提交。

3. 在連接客戶通知前設計更新傳送方式

如果所選服務支援 webhooks，請使用其文件所述的回調機制接收更新。確認可用的驗證或簽名方式，不要自行創建驗證標頭。將憑證保存在伺服器上，要求使用 HTTPS，並避免在瀏覽器程式碼或面向客戶的連結中包含 API 密鑰。

接收器應在確認更新前先以持久方式接受更新，然後以異步方式處理。請為重複傳送及亂序抵達的事件做好設計。若可用，請使用供應商事件 ID；否則，使用穩定的事件屬性定義有文件記錄的去重規則。

如果必須輪詢，請在供應商文件所述限制及營運需要內安排。收到速率限制回應後應退避，避免同步重試高峰，並根據保留及對帳政策停止對已完成貨件進行不必要的檢查。如果服務允許取回資料，定期對帳工作亦有助於偵測遺漏的更新。

4. 標準化狀態，但不要捨棄其含義

使用一組精簡的內部狀態，讓訂單系統及支援團隊可以一致地理解。例如：已收到資料、運輸中、派送中、已派送、派送異常及已退回。這些是建議的應用程式分類，不是對任何供應商確切狀態代碼的描述。

在標準化狀態旁保留詳細的承運商事件。派送嘗試失敗、地址問題及清關相關延誤都可能需要處理，但所需的回應並不相同。將所有內容映射為一般異常，會令資料更容易儲存，卻降低其實際處理價值。

不要將建立標籤翻譯成已實體收件。同樣，不要僅因某個事件提及清關設施，就將包裹標記為已清關。請使用符合事件實際含義的語言。

明確處理國際交接

最重要的整合測試通常是始發地網絡與目的地派送之間的轉換。保留原始參考號碼及任何已確認的最後一公里參考號碼。新的追蹤號碼應成為同一包裹的另一個識別碼，而不是自動建立第二件貨件。

只有在關係來自可信來源時才連結識別碼，例如物流供應商、追蹤回應或運輸系統。相似的事件時間或相同的目的地國家不足以證明兩個號碼屬於同一件包裹。

將事件時間與資料接收時間分開。較早的事件可能在較新的事件之後才抵達系統，尤其是在資料於不同網絡之間傳遞時。保留提供的時區偏移量，標準化時間戳以便處理，並保留含糊的來源值，不要分配沒有依據的時區。

對客戶顯示最新且有意義的狀態，並清楚展示更新時間。如果目的地承運商尚未回報掃描，請說明追蹤正在等待下一次更新。不要推斷包裹已遺失、仍然實體停留在上次掃描地點，或已經抵達目的地國家。

17TRACK 在此工作流程中的定位

當應用程式需要多承運商追蹤整合時，17TRACK 的 Tracking API 方案便與此相關。其官方 API 文件應作為實施驗證、登記、回應處理及支援的更新工作流程的依據。請使用有文件記錄的 API 合約，不要將面向一般消費者的追蹤頁面視為整合介面。

請以評估自建方案的相同營運要求進行評估：正確的承運商識別、路線上有用的事件、交接連續性、錯誤恢復及可管理的更新傳送。在確定正式設計前，確認商業條款、用量計算、請求限制及任何必要的帳戶設定。

選擇集中式 API 的最主要原因，是降低實際營運路線的整合複雜度。然而，這項優勢仍需使用具代表性的包裹進行驗證。不要僅因供應商的整體覆蓋描述聽起來廣泛，就選擇該供應商。

在推出前進行以路線為基礎的試點

使用包括正常派送及困難個案的測試集。歷史貨件有助於測試狀態映射，而即時貨件則能揭示更新傳送及營運時間。單獨使用任何一種測試都無法回答所有問題。

• 中國至美國派送：驗證始發地事件、任何國際交接及最終派送事件。
• 中國至歐洲派送：測試實際使用的目的地國家及運輸服務。
• 新標籤：確認尚未進行實體掃描的包裹不會被顯示為正在運輸。
• 派送參考號碼變更：確認關係仍附加至正確包裹。
• 派送異常：檢查詳細原因是否傳送至適當的營運佇列。
• 拆分訂單：確認一件包裹派送完成不會關閉整張訂單。
• 重複或延遲更新：確認不會產生重複訊息，或錯誤覆蓋較新的狀態。
• 暫時整合故障：驗證重試、對帳及支援可見性。

在檢視結果前設定驗收標準。衡量登記成功率、錯誤的承運商分配、遺漏的關鍵節點、更新處理延遲及重複客戶訊息。請為業務定義可接受的門檻，不要套用沒有依據的通用基準。若事件遺漏，應先與承運商自身記錄比較，再判斷問題是否由 API 造成。

將資料新鮮度與 API 可用性分開監控

API Monitoring 應回答兩個不同問題：整合是否正常運作，以及貨件資料是否有用？成功的請求只能回答第一個問題。你還需要知道登記是否持續出現錯誤、回調是否失敗，或某條路線是否停止產生預期的關鍵節點。

• 整合健康狀況：驗證失敗、請求錯誤、速率限制回應、回調失敗及佇列積壓。
• 資料質素：未知狀態、格式錯誤的時間戳、未解決的承運商身份及異常的識別碼變更。
• 貨件新鮮度：按路線及運輸服務分類，計算距離最新承運商事件的時間。
• 業務影響：異常處理工作量、失敗通知及被錯誤標記為完成的訂單。

在某項運輸服務中長時間沒有掃描可能是正常情況，在另一項服務中則可能不尋常。使用針對路線的預期及觀察到的貨件歷史來優先調查。將整合錯誤警報與貨件延誤警報分開，確保由正確團隊接收。

客戶通知應跟隨已確認的關鍵節點，而不是每個原始事件。抑制重複訊息，區分派送嘗試與派送完成，並避免承諾底層資料不支持的到達日期。限制追蹤資料的存取權，僅在工作流程需要時保留個人資料。

常見問題

一個 API 可以同時追蹤中國始發地承運商及目的地派送承運商嗎？

當相關服務及識別碼關係獲支援時，多承運商服務可能會整合運輸兩個階段的事件。請使用真實包裹驗證完整路線。僅能識別始發地追蹤號碼，並不能證明目的地派送資料一定可用。

為甚麼包裹離開中國後追蹤便停止更新？

可能原因包括實體掃描之間存在間隔、回報延遲，或交接至另一個派送參考號碼。請檢查原始事件及任何提供的最後一公里號碼，然後與相關承運商記錄比較。單憑追蹤中斷，不能證明包裹已遺失或被海關扣留。

應用程式應使用 webhooks 還是輪詢？

請使用供應商文件所述的機制。在支援的情況下，webhooks 可以減少重複檢查，而獲准的資料取回請求則可支援對帳。無論採用哪種設計，在依賴更新向客戶通訊前，都應建立重複處理、重試控制及監控。

追蹤 API 可以保證派送日期或清關嗎？

追蹤資料不保證以上任何一項。如果提供預計派送日期，請保留其來源並以預計日期呈現。清關相關掃描應按照實際措辭描述，除非明確表示已完成清關，否則不要將其解讀為已清關。

選擇 API 方案前應驗證甚麼？

確認你的承運商及運輸服務、登記要求、更新方式、用量計算、請求限制、資料可用性及支援安排。了解替換號碼、重複登記及歷史查詢在商業上如何處理。對於會影響預算或架構的要求，請使用最新文件及書面確認。

來源

• 17TRACK Tracking API — Tracking API 方案的官方產品參考資料。
• 17TRACK API documentation — 實施整合的官方技術參考資料。開發前請在此確認確切的請求格式、支援的工作流程及限制。