Skip to main content
首頁博客指南如何透過 API 登記追蹤號碼:請求欄位、承運商代碼及回應

如何透過 API 登記追蹤號碼:請求欄位、承運商代碼及回應

17TRACK

如要透過 API 登記追蹤號碼,請發送經身份驗證的登記請求,其中包含貨件的追蹤號碼,以及在需要時提供承運商識別碼。然後檢查每件已提交貨件的回應,而不只是 HTTP 狀態,並儲存登記成功、失敗或狀態仍不確定的結果。登記會啟動追蹤流程,但並不代表承運商已掃描包裹,也不代表追蹤事件已經可用。

如何透過 API 請求欄位登記追蹤號碼

本指南適用於將訂單管理系統、倉庫應用程式或電子商務平台連接至追蹤 API 的開發者。本文以 17TRACK 作為具體整合範例,並說明哪些詳細資料必須根據你所選 API 版本的文件進行核對。

登記的作用及不包含的內容

登記請求會告知追蹤服務你希望追蹤哪一件貨件。這與購買運輸標籤、預約收件或要求承運商建立貨件不同。在典型的整合流程中,運輸流程會先產生追蹤號碼,然後你的應用程式再登記該號碼。

請在應用程式中分開處理以下三個事件:

  • 已建立貨件:你的運輸系統已分配追蹤號碼。
  • 已接受登記:追蹤服務已接受該貨件進行追蹤。
  • 已收到追蹤資訊:承運商事件已可透過追蹤服務取得。

不要僅因登記成功便將訂單更新為「運送中」。新建立的標籤可能尚未有實體收件掃描。面向客戶顯示的貨件狀態,應根據追蹤事件並透過你的狀態映射規則解讀,而不是根據登記回應。

對於 17TRACK 整合,請先參閱 Tracking API 概覽,並以官方 API 文件作為端點、欄位定義、身份驗證及回應代碼的依據。以下範例集中於登記,而非另行處理取得結果或接收更新的工作。

編寫 API 呼叫前準備請求欄位

最有用的準備工作,是在你的運輸系統與追蹤整合之間建立一份小型欄位契約。決定每個值的來源、是否可以缺失,以及如何驗證。

欄位或值用途實作規則
追蹤號碼識別要追蹤的貨件。以字串形式儲存及傳送;保留開頭的零。
承運商識別碼在追蹤服務供應商的系統中識別承運商。使用供應商文件所列的識別碼,而不是內部倉庫代碼。
內部參考編號將登記與你的貨件記錄連結。如有支援,使用受支援的參考欄位;無論如何都要保留自己的資料庫映射。
其他識別資料當承運商要求的不只是追蹤號碼時,可能有助識別貨件。只提交該整合及承運商文件所列的欄位。
API 憑證驗證呼叫帳戶的身份。保存在伺服器上,並從應用程式日誌中排除。

將追蹤號碼視為識別碼

切勿將追蹤號碼轉換為整數。數值轉換可能會刪除開頭的零,而較大的數值在某些程式設計環境中可能失去精確度。請移除意外的前後空白,但除非相關文件或承運商格式支援該標準化處理,否則不要刪除標點符號或更改字母大小寫。

呼叫 API 前,請先驗證明顯的輸入錯誤:空字串、意外換行,以及誤將訂單號碼複製到追蹤號碼欄位。不要對所有承運商套用單一的長度或字元規則。適用於一間承運商的驗證規則,可能會拒絕另一間承運商的有效號碼。

將訂單參考資料與貨件身份分開

一張訂單可以包含多個包裹,而替換貨件也可能產生另一個追蹤號碼。請在貨件或包裹層級建立登記模型,而不是假設每張訂單只有一個追蹤號碼。

如使用供應商支援的標籤或參考欄位,請優先使用不透明的貨件參考編號,而不是客戶的電郵地址或街道地址。你自己的資料庫應繼續作為訂單、貨件、追蹤號碼及承運商映射之間的權威連接。

選擇正確的承運商代碼

承運商代碼不一定是通用的業界識別碼。追蹤平台識別的值,可能與運輸軟件中儲存的承運商名稱不同。即使兩個系統都使用數字代碼,也可能為同一承運商分配不同數字。

建立從你的運輸服務至追蹤服務供應商承運商識別碼的明確映射。必要時,區分承運商的地區業務或服務與其較廣泛的品牌。當運輸系統使用別名時,僅根據顯示名稱建立的映射可能產生歧義。

  • 已知承運商:在受支援時使用文件所列的承運商識別碼,尤其是在不同承運商的追蹤號碼格式重疊時。
  • 未知承運商:只透過文件所列機制使用自動偵測。不要假設省略、空字串、零及 null 具有相同含義。
  • 結果看似錯誤:在重複登記同一號碼前,先核對原始標籤、運輸服務及映射。

自動偵測很有用,但不能證明某一承運商實際持有該貨件。同樣,有效的承運商代碼也不能保證所提供的追蹤號碼屬於該承運商。

請將承運商映射設為可配置,而不要將其分散在應用程式代碼中。記錄上次核對映射的時間,並在每次更改後,將已知貨件加入回歸測試。

範例:提交 17TRACK 登記請求

以下範例展示 17TRACK v2.2 登記端點、17token 身份驗證標頭,以及包含一個追蹤號碼物件的陣列。部署前,請確認此版本及其請求要求符合你的帳戶和官方文件。追蹤號碼只是佔位符,必須替換為真實貨件識別碼。

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

此簡化範例沒有展示承運商選擇或承運商專用的補充欄位。請查閱登記文件,以確定省略承運商欄位時承運商偵測如何運作,以及你的貨件是否需要額外資訊。如提供承運商,請使用文件所列的 carrier 欄位,以及該 API 版本所要求的識別碼。

請從伺服器端環境執行此請求。不要將 token 嵌入公開商店、瀏覽器指令碼或分發給客戶的流動應用程式中。環境變數適合本機範例;生產部署應使用你所在機構的機密管理控制措施。

在增加請求量前,先測試一件已知貨件並檢查完整回應。然後測試無效輸入,以及同時包含有效和無效項目的批次。這些檢查可揭示你的整合是否真正處理項目級結果,而不只是識別 HTTP 成功回應。

從三個層級讀取回應

可靠的回應處理器會回答三個獨立問題:請求是否到達服務、服務是否接受操作,以及每件貨件發生了甚麼事?

1. HTTP 及傳輸結果

連線逾時、TLS 失敗或回應中斷,不一定能告訴你伺服器是否已處理請求。在可以核對前,請將該結果標記為不確定。HTTP 成功狀態確認 HTTP 交換成功,但你仍須檢查應用程式回應。

2. 請求層級結果

檢查 API 文件所列的頂層結果及錯誤欄位。身份驗證錯誤、格式錯誤的 JSON 及帳戶限制需要不同處理方式。儲存供應商的原始錯誤代碼及訊息,不要將所有失敗簡化為「追蹤不可用」。

不要假設數字應用程式代碼與 HTTP 狀態代碼具有相同含義。兩者來自不同層級,必須分開解讀。

3. 貨件層級結果

對於批次登記,請處理每一個已提交項目。回應可能區分已接受及已拒絕貨件;你的解析器應遵循所選版本文件中列出的確切結構。不要僅因一個項目成功,就將整個批次標記為已登記。

將供應商回應標準化為你自己的穩定應用程式狀態。例如,資料庫可以使用 accepted、rejected 及 uncertain。這些是建議的內部狀態,不是 17TRACK 回應中的實際字面值。根據適當的保留及存取政策,保留原始供應商回應,讓開發者可以調查差異。

實用的登記記錄應包含內部貨件 ID、已提交號碼、承運商選擇、嘗試時間、API 版本、結果及供應商錯誤詳情。請將登記狀態與派送狀態分開。

處理重試,避免建立無限循環

重試政策應取決於失敗原因,而不只是是否發生例外。

  • 輸入無效:重試前先修正欄位。重複提交未更改的格式錯誤請求不太可能有幫助。
  • 身份驗證失敗:核實憑證及帳戶設定。避免重複提交同一個失敗批次。
  • 速率限制:遵循文件所列限制及任何適用的重試指示。使用有上限的退避,而不是立即進行並行重試。
  • 暫時性服務失敗:在明確設定的嘗試次數及時間預算內重試。
  • 提交後逾時:根據文件所列的 API 行為核對貨件登記狀態,再假設首次嘗試失敗。
  • 與重複相關的回應:檢查貨件是否已登記,以及是否正確關聯至你的應用程式記錄。

除非文件明確定義相關行為,否則不要假設登記具有冪等性。應用程式端去重可減少意外重複提交,但不能確立供應商的重複處理政策。

使用適合你的貨件模型的內部唯一性規則。僅以追蹤號碼作為永久鍵,在不同承運商及長期保留期間內可能並不足夠。保留承運商背景及你自己的貨件識別碼,並記錄如何處理替換貨件及修正後的號碼。

分開監察登記與追蹤更新

API 監察應區分整合失敗與貨件只是沒有新的承運商事件。這兩種情況需要不同負責人及不同修正方式。

對於登記,請監察接受及拒絕數量、錯誤類別、不確定結果、重試積壓及回應延遲。對於後續追蹤,請另外監察更新接收或取得失敗。在了解正常流量及供應商文件所列的運作限制前,避免設定數值警報門檻。

實際的生產檢查應回答以下問題:

  1. 每件等待追蹤的貨件是否都有登記記錄?
  2. 每次已接受的登記是否都能追溯至正確包裹?
  3. 被拒絕的項目是否已轉交給能修正根本資料的人員?
  4. 不確定的請求是否得到核對,而不是被放棄或無限重試?
  5. 面向客戶的狀態是否根據貨件事件,而不是登記接受狀態產生?
  6. 憑證及不必要的個人資料是否已從日誌中排除?

對電子商務營運而言,營運交接與 API 呼叫同樣重要。開發者應負責傳輸及解析失敗;運輸或履行團隊則應能調查錯誤標籤、承運商映射及遺失的貨件資訊。

常見問題

我可以在承運商首次掃描前登記追蹤號碼嗎?

登記與承運商掃描是兩個獨立事件。服務可能在追蹤事件可用前接受號碼,具體取決於其驗證規則。不要將接受視為承運商已收到包裹的證明。

我是否總是需要提供承運商代碼?

這取決於 API 文件所列的偵測行為及相關貨件。如果已知承運商,明確且正確映射的識別碼可以減少歧義。如果未知,請使用文件所列的自動偵測方法,而不要自行建立承運商值。

為甚麼 API 返回 HTTP 成功,但貨件卻失敗?

HTTP 請求可以成功,而應用程式仍拒絕個別項目。請讀取頂層應用程式結果及貨件層級結果。這項區分對批次請求尤其重要。

登記請求逾時時,我應該怎樣做?

將結果視為不確定。連線失敗前,伺服器可能已處理請求。查閱供應商文件所列的重複行為及可用的登記或追蹤查詢方法,然後在有上限的政策下進行核對或重試。

登記會自動設定追蹤通知嗎?

不要假設會。登記、追蹤取得及 webhook 設定是不同的整合事項。請核實相關文件,並在依賴其發送客戶通知前,測試完整的更新流程。

來源

  • 17TRACK API 文件 — 登記端點、身份驗證、請求欄位、承運商識別碼、回應結構及錯誤處理的參考。請將實作詳情與你部署的 API 版本匹配。
  • 17TRACK Tracking API 概覽 — 追蹤 API 產品及開發者整合資源的官方起點。