貨件追蹤 API：運作方式及如何提升可視性

貨件追蹤 API 將訂單或物流系統連接至承運商追蹤資料，然後返回企業可用於客戶通知、支援工作流程、儀表板及配送作業的貨件事件。它們以可重複的資料流程取代手動查詢，從而提升可見性，但不會建立承運商尚未接收或發布的掃描事件。

對於電子商務營運者、開發人員或物流團隊而言，實際問題不只是 API 能否「追蹤包裹」，而是整合能否可靠地識別貨件、統一不同承運商的狀態、處理例外情況，並在適當時間將有用更新傳送至正確系統。

甚麼是貨件追蹤 API？

貨件追蹤 API 是一種軟件介面，讓一個應用程式可以從另一項服務請求或接收貨件狀態資訊。商戶的訂單管理系統、客戶入口網站、服務台、倉庫平台或流動應用程式，都可以使用該介面，而不必每次處理追蹤號碼時都要求人員瀏覽承運商網站。

在典型設定中，企業會將追蹤號碼及承運商識別碼（如已知）傳送至追蹤服務。該服務會檢查其可用的承運商連接，並返回結構化資料，例如目前狀態、事件歷史、可用的位置詳細資料、時間戳記、承運商提供的預計送達資訊，以及例外訊息。具體欄位會因供應商及承運商而異。

「API」一詞描述的是連接方式，而不是資料質素的保證。追蹤 API 可以彙整多家承運商的資訊，但結果的質素及時間仍取決於承運商的系統、貨件識別碼、服務級別，以及掃描事件是否可用。

貨件追蹤 API 如何運作

1. 建立或識別貨件

流程通常始於訂單或履行系統建立貨件記錄。記錄可能包含訂單 ID、追蹤號碼、承運商、目的地國家、服務類型及客戶聯絡資料。穩健的整合會將內部訂單 ID 與承運商追蹤號碼分開保存。這種區分有助於將多個包裹與一張訂單關聯，或將一個包裹與多筆內部記錄關聯。

承運商識別十分重要，因為追蹤號碼未必能確定顯示承運商。有些系統可以根據號碼格式推斷承運商，而其他系統則要求商戶提供承運商代碼。選擇錯誤的承運商時，即使貨件有效，API 仍可能返回沒有結果或不完整的結果。

2. 應用程式提交追蹤請求

客戶端應用程式會透過 HTTPS 傳送經身份驗證的請求。視乎供應商而定，請求可能會建立追蹤工作、取得現有追蹤記錄，或要求最新狀態。身份驗證通常使用 API 金鑰、權杖或其他有文件記載的憑證。請求應從安全的伺服器端環境發出，而不是將憑證暴露在瀏覽器或流動應用程式中。

整合亦應記錄供應商的回應、請求識別碼及時間戳記。這些詳細資料有助於開發人員調查請求失敗、更新延遲、重複事件，以及內部儀表板與承運商頁面之間的差異。

3. 追蹤服務取得承運商事件

多承運商追蹤服務會透過其自身支援的整合連接至承運商資料來源。它可能會輪詢變更、接收承運商更新，或結合使用多種方法。使用 API 的企業通常不需要為每家承運商建立獨立的技術連接，但仍需確認其航線所涉及的承運商及服務均獲支援。

這是一項重要區分：「多承運商」並不代表每家承運商、郵政營運商、貨運供應商或本地配送公司都會自動提供服務。在投入生產環境前，應按承運商、國家、服務及使用情境檢查覆蓋範圍。

4. 統一不同承運商的事件

承運商會以不同名稱及詳細程度描述類似事件。一家承運商可能將包裹描述為「運送中」，另一家則使用更具體的掃描訊息。追蹤平台可以將來源事件映射至通用狀態模型，例如已收到資料、已提取、運送中、派送中、已送達、例外或已退回。

統一化可令報告及自動化更容易，但不應刪除有用的詳細資料。在可用的情況下，應保留原始承運商訊息、事件時間戳記及位置。面向客戶的頁面可能需要簡單說明，而營運團隊則可能需要原始事件，以判斷是否發生地址問題、海關問題或派送嘗試。

5. 更新傳送至企業系統

常見的傳送模式有兩種。在輪詢模式下，企業會重複要求取得最新追蹤狀態。輪詢方式直接，但頻繁請求可能產生不必要的流量，而輪詢間隔過長則可能延遲更新。在事件驅動傳送模式下，追蹤服務會在發生相關變更時傳送 webhook。Webhook 可以減少重複請求，但接收系統必須驗證請求、處理重試，並安全地處理重複事件。

許多生產環境整合會同時使用兩種模式：以 webhook 取得及時更新，以排程提取進行核對。正確設計取決於供應商文件、營運要求，以及對通知延遲或重複的容忍程度。

追蹤 API 可以提供甚麼資訊？

可用的回應會因供應商及承運商而異。常見類別包括：

• 貨件身份資料，包括追蹤號碼及承運商關聯。
• 目前的統一狀態及最新已知事件。
• 帶有時間戳記，以及在可用時包含位置的歷史事件。
• 比概括狀態標籤提供更多背景資料的承運商訊息。
• 承運商或追蹤服務提供的預計送達資訊。
• 視乎承運商資料是否可用而定的例外或退回相關事件。
• 在支援的情況下，協助使用者開啟追蹤檢視的連結或參考資料。

預計送達日期並不等同於送達承諾。隨着新事件到達，日期可能會變更，而部分承運商可能完全不提供預計日期。介面應清楚標示預計日期，除非已另行核實合約服務承諾，否則避免將其呈現為保證。

API 如何提升貨件可見性

單一營運檢視

沒有 API 時，團隊可能需要在承運商網站、試算表、電郵串及訂單記錄之間切換。API 可以將貨件事件帶入現有訂單或物流平台。這可減少在不同環境間切換的需要，並更容易識別需要處理的貨件。

更早處理例外情況

企業可以為地址問題、派送嘗試、海關延誤或長時間沒有活動等狀態定義處理措施。例如，例外事件可能會建立支援工作、向客戶發送訊息，或將貨件轉交至營運隊列。自動化不能取代人類判斷，但可以令交接更快及更一致。

更一致的客戶溝通

追蹤資料可以支援訂單狀態頁面、電郵更新、SMS 工作流程及支援人員檢視。一致的狀態模型有助避免一個渠道顯示「運送中」，而另一個渠道仍顯示過時事件。由於承運商資料可能延遲、不完整或經修訂，客戶溝通仍需謹慎措辭。

更完善的跨承運商報告

統一化資料支援跨承運商及航線比較。團隊可以按狀態歸類貨件、衡量包裹在某個階段停留的時間，並調查反覆出現的例外模式。只有在企業一致定義指標時，這些報告才有用。例如，「運送時間」應有記錄在案的開始及結束事件，而不是根據不一致的時間戳記推算。

貨件追蹤 API 與承運商追蹤頁面的比較

考慮因素	承運商追蹤頁面	追蹤 API
主要使用者	查詢貨件的個人	系統、工作流程或應用程式
資料存取	手動，每次一件貨件	程式化及可重複
承運商範圍	通常為一家承運商	可能涵蓋多家承運商，視乎有文件記載的覆蓋範圍而定
自動化	有限	支援通知、路由及報告工作流程
實施工作	手動使用時較低	需要開發、安全、測試及監察

追蹤 API 並非對每間企業都自動較佳。偶爾才有貨件的小型團隊可能只需要承運商頁面或現成的追蹤工具。擁有多家承運商、大量支援需求或客戶入口網站的機構，通常可從結構化整合中獲得更多好處。

如何評估貨件追蹤 API

檢查重要的承運商

從實際運送資料開始，而不是從一般承運商數量開始。列出企業使用的承運商、服務、始發國家、目的地國家及貨件類型。確認覆蓋範圍是否適用於所需的具體服務及地區。亦應確認如何加入新承運商，以及如何處理不支援的追蹤號碼。

檢視狀態模型及事件詳細資料

實用的 API 應能區分正常運送與例外或退回。檢視範例回應、狀態定義、時間戳記慣例、原始承運商訊息，以及未知或不活躍貨件的處理方式。不要只根據狀態名稱清單批准整合。

了解傳送方式

確定服務支援提取、webhook，或兩者皆支援。確認 webhook 身份驗證、重試行為、事件排序、重複處理方式，以及接收端點是否必須快速確認事件。如果整合會使用輪詢，應記錄請求間隔及核對規則。

評估限制、錯誤及生命週期規則

閱讀身份驗證、請求限制、錯誤代碼、資料保留、版本變更及測試環境的文件。生產環境設計應區分暫時性故障、無效追蹤號碼，以及有效但近期沒有掃描的貨件。

保護貨件及客戶資料

追蹤記錄可能與姓名、地址、訂單價值及聯絡資料相關聯。只儲存工作流程所需的資料，限制存取權限、保護憑證、加密流量，並定義保留規則。API 整合亦應提供撤銷或輪換憑證的方法，而不會中斷整個訂單系統。

使用 17TRACK 進行追蹤 API 整合

17TRACK 官方 Tracking API 頁面將產品定位為用於程式化貨件追蹤，而其開發人員文件則提供開發人員在建置前需要核實的實施詳細資料。對於希望在多種承運商關係中使用單一追蹤整合，而不是為每家承運商建立獨立連接的團隊而言，這是一個相關選項。

評估服務的正確方式，是測試企業實際使用的承運商及貨件類型。根據最新文件確認所需請求欄位、返回的事件結構、更新行為、身份驗證方法、使用限制，以及 webhook 或輪詢工作流程。相比假設廣泛的多承運商產品描述能保證每條路線都有相同資料，這些檢查更可靠。

對於不需要自訂開發的機構而言，預先建立的追蹤體驗可能比 API 專案更實際。17TRACK 追蹤頁面面向直接貨件查詢，而當追蹤資料必須嵌入內部或面向客戶的系統時，API 則是更合適的途徑。

實用實施清單

1. 定義業務成果，例如減少「我的訂單在哪裏？」的查詢，或識別停滯貨件。
2. 記錄訂單至貨件的資料模型，包括多個包裹及部分履行。
3. 使用具代表性的追蹤號碼確認承運商及服務覆蓋範圍。
4. 為有效、無效、新建立、已送達、已退回及例外貨件建立測試流程。
5. 在營運調查需要時，同時儲存原始事件及統一狀態。
6. 使事件處理具備冪等性，確保相同 webhook 或回應不會觸發重複訊息或操作。
7. 為遺漏的 webhook、延遲事件及維持不變的記錄定義核對工作。
8. 監察錯誤率、更新延遲、不支援的承運商，以及需要人工審核的貨件數量。
9. 先以有限的承運商或市場範圍推出，待工作流程通過實際營運測試後再擴展。

需要預先規劃的常見限制

追蹤 API 會報告可用的物流事件；它們不會控制包裹，也不保證每次移動都會產生掃描。貨件可能因為正在設施之間移動、承運商尚未發布新事件，或追蹤資料有所延遲，而看起來沒有變化。因此，「沒有更新」的狀態應被視為需要定義閾值的工作流程狀態，而不應自動視為遺失的證明。

承運商術語及更新頻率亦各有不同。統一狀態可提升一致性，但不能令兩家承運商提供同等詳細的資料。海關、最後一公里交接、地址更正及退回可能產生特別不一致的資料。企業應向客戶提供有用的說明，而不應承諾超出底層事件所支持的精確程度。

最後，整合質素是一項持續責任。承運商連接、API 版本、憑證、流量模式及內部訂單邏輯都可能變更。監察及定期測試貨件是維持可見性的一部分，而不是推出後才可選擇加入的附加項目。

常見問題

貨件追蹤 API 可以追蹤每一家承運商嗎？

不可以。覆蓋範圍取決於供應商支援的承運商、服務、國家及資料連接。請核實企業實際使用的特定承運商及航線，而不要依賴一般性的覆蓋範圍聲稱。

輪詢與 webhook 有甚麼分別？

輪詢是指應用程式重複要求取得最新追蹤狀態。Webhook 則是指追蹤服務在有更新可用時，向端點傳送事件。輪詢較容易理解，但可能產生不必要的請求；webhook 可以更快傳送事件，但需要安全且可承受重試的處理方式。

追蹤 API 會提供即時 GPS 位置嗎？

一般而言通常不會。大部分貨件追蹤 API 提供承運商掃描事件及相關狀態資訊。確切位置詳細資料、更新頻率及任何即時功能，取決於承運商及服務。

API 可以預測送達日期嗎？

當供應商或承運商提供相關資料時，API 可能會返回預計送達日期。預計日期可能會變更，除非相關服務條款支持該聲稱，否則不應將其呈現為保證的送達承諾。

小型企業應否自行建立追蹤整合？

當貨件資料必須驅動現有系統、工作流程或客戶體驗，而企業能夠支援測試及維護時，可以建立自訂整合。如果需求只是偶爾查詢，現成的追蹤頁面或應用程式可能更經濟及更易操作。

來源

• 17TRACK Tracking API — 官方產品資訊。
• 17TRACK API Documentation — 有關整合詳細資料的官方開發人員參考文件。
• 17TRACK Tracking — 用於貨件查詢的官方追蹤體驗。
• Shopify Webhooks Documentation — 事件驅動整合概念及 webhook 處理的參考資料。
• MDN: An overview of HTTP — 網絡 API 所使用的客戶端—伺服器請求及回應背景資料。