「進階集成可見性」訂戶可透過「進階集成可見性」Tracking Number Subscription API，利用API端點將查詢號碼與webhook項目關聯起來。「查詢號碼關聯」功能支援兩種處理方式：

• 查詢號碼關聯 — 同步傳回同一個HTTP回應內的處理結果。當需要關聯較少數量的查詢號碼時，此選項最適合用於需即時確認的應用程式。
• 查詢號碼關聯 — 非同步提交背景處理請求並傳回作業ID，該ID可用於日後檢索處理狀態和結果。此選項最適合用於處理較大批量的查詢號碼。

請根據應用程式性能和工作量要求，選擇最切合需求的處理方式。

請注意：

• 您必須擁有「進階集成可見性」項目的管理員或貢獻者權限
• 如需進一步了解「進階集成可見性」及其功能，請參閱「進階集成可見性」說明文件頁面。

「進階集成可見性」Tracking Number Subscription API具有下列優點：

• 您可使用API端點，輕鬆關聯、更新及管理「進階集成可見性」webhook項目的查詢號碼。
• 在單次API請求中關聯多個查詢號碼，需無需個別處理每個查詢號碼。
• 如需即時取得結果，請選擇同步處理方式；如需進行較大批量的操作，請選擇非同步處理方式。

使用下列端點來管理您的「進階集成可見性」項目：

• 查詢號碼關聯 — 同步：允許您將查詢號碼與webhook相關聯，並在同一個HTTP回應中接收最終處理狀態。
• 查詢號碼關聯 — 非同步：允許您將查詢號碼與webhook相關聯，並於日後利用傳回的jobId，透過相關端點查詢非同步作業狀態或下載詳情：
  • 查詢號碼作業狀態
  • 查詢號碼作業詳情

您可於「進階集成可見性」項目概覽中找到這些API。

以下API僅能透過項目概覽（如上截圖所示）存取。

下表總結了同步及非同步「查詢號碼關聯」端點之間的區別。
 

如要即時確認較小批量的查詢號碼，請使用同步端點。如要處理無需即時回應的較大批量，請使用非同步端點。

使用此端點，將一個或以上的查詢號碼與「進階集成可見性」webhook項目相關聯，並在同一個HTTP回應中接收處理結果。

此端點供需要即時確認的應用程式使用，並支援包含最多150個查詢號碼的請求。

必須輸入：

• subscriptionID
• trackingNumber

優點

同步端點具有下列優點：

• 即時處理結果
• 在單一回應中，顯示詳盡的成功和失敗資訊
• 每次請求最多支援150個查詢號碼
• 在處理前驗證請求及執行業務規則
• 機器可讀的錯誤代碼和描述性錯誤訊息
• 交易ID可用於查詢請求及疑難排解

查詢號碼關聯 — 同步端點會強制執行多項驗證規則，包括：

• 必須提供有效及啟用中的subscriptionId
• 每次請求僅允許一個subscriptionId
• 必須提供trackingNumber
• 確保查詢號碼符合FedEx格式要求，包括查詢號碼長度上限為6至22位數字

錯誤回應結構一致，其中errors[]包含易於解析的代碼和訊息。

"errors": [

{

"code": "ERROR.CODE",

"message": "Descriptive error message"

}

交易號碼關聯 — 同步端點允許部分查詢號碼成功。如部分查詢號碼失敗，Synchronous API仍會傳回200 OK，並顯示下列內容：

• failedTrackingNumbers
• 描述性訊息

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "由於驗證或系統錯誤，以下查詢號碼無法上載"

      }

    }

有關其他詳情和規則，請參閱業務規則部分。

使用此端點來提交一個或以上已訂閱的查詢號碼，以在背景程式中處理。

此請求會傳回作業ID，您可將該作業ID與「查詢號碼作業狀態」端點一起使用，以來監察處理情況，並使用「查詢號碼作業詳情」端點，以在作業完成後下載處理結果。

必須輸入：

• 行動
• 查詢號碼詳情

每次請求最多可關聯1,000個查詢號碼。

優點

非同步端點具有下列優點：

• 支援大批量提交最多1,000個查詢號碼
• 允許在背景程式中處理長時間執行的請求
• 可監察作業狀態及下載處理報告
• 當請求的工作量較大時，消除逾時的疑慮

使用此端點以查詢非同步作業(即佇列中的一項或多項連續請求)的狀態，或者所有已提交作業的狀態。

此請求的必須輸入資料為：

• jobID — 請指明您想查詢狀態的作業ID。

請注意：此端點中的作業ID為可選填。若您未有指明作業ID，系統將返回所有已提交作業的狀態。

此請求的成功回應將返回jobID、目前作業狀態，以及作業建立及完成的時間戳記。回應將顯示作業的目前狀態，並還將包含成功訊息、錯誤或警告，以供用戶檢視，以及於適用時進行疑難排解。

• 如作業狀態顯示為「已完成」，即代表所有查詢號碼已成功驗證及處理。
  • 「已完成」僅代表查詢號碼已完成驗證及處理，並不表示所有查詢號碼均已成功新增至「進階集成可見性」項目。
  • 如作業有多個查詢號碼，即使部分號碼無法與項目相關聯，而其他號碼成功關聯，狀態也可視為「已完成」。如需確認原有關聯請求內每個查詢號碼的狀態，請下載批量報告。

請注意：如作業狀態顯示為「失敗」，表示由於多項原因或嚴重錯誤，請求未能處理，用戶必須重試。

下表顯示了作業狀態及其相應說明：

使用此端點來下載處於「已完成」狀態之非同步作業的JSON報告。

與此請求相關的必須輸入資料為：

• jobID — 請指明您想查詢狀態的作業ID。必須為此端點提供作業ID。

請注意：

• 您每次僅能下載一份非同步作業報告。
• 如作業並非「已完成」，而您嘗試下載報告，系統將顯示錯誤訊息。

對此請求成功回應後，您將取得JSON格式的作業報告。

常見業務規則

• 可與「進階集成可見性」項目相關聯的查詢號碼總數不設上限。
• 與「進階集成可見性」項目相關聯的查詢號碼在成功與webhook相關聯40天後，將被取消關聯。
• 收件人地址、收件人簽名、敏感遞送資訊等保密查詢資訊，均無法透過Tracking Number Subscription API提供。

同步端點的業務規則

• 每次請求最多可包含150個查詢號碼。
• 所有查詢號碼必須使用同一個subscriptionId。
• 該特定的「進階集成可見性」webhook訂閱必須為有效及啟用中。
• 請求將於30秒後逾時。

非同步端點的業務規則

• 每次請求最多可包含1,000個查詢號碼。
• 在查詢號碼成功與「進階集成可見性」webhook相關聯後，非同步請求的作業狀態和作業詳情將會保留90天。