Advanced Integrated Visibility Tracking Number Subscription API 可讓 Advanced Integrated Visibility 訂閱者使用 API 端點，將追蹤號碼與 Webhook 專案建立關聯。追蹤號碼關聯功能支援兩種處理方式：

• Tracking Number Association – Synchronous (追蹤號碼關聯 – 同步) 在同一個 HTTP 回應中傳回處理結果。此選項適合在關聯少量追蹤號碼時，需要立即確認的應用程式。
• Tracking Number Association – Asynchronous (追蹤號碼關聯 – 非同步) 提交背景處理要求，並傳回一個工作識別碼，該識別碼稍後可用來擷取處理狀態和結果。此選項適合處理大量追蹤號碼。

請選擇最符合您應用程式效能和工作量需求的處理方式。

附註：

• 您必須具有 Advanced Integrated Visibility 專案的管理員或貢獻者存取權
• 如需 Advanced Integrated Visibility 及其功能的詳細資訊，請造訪「Advanced Integrated Visibility 文件」頁面。

Advanced Integrated Visibility Tracking Number Subscription API 具有以下優點：

• 您可以使用 API 端點輕鬆關聯、更新及管理 Advanced Integrated Visibility Webhook 專案的追蹤號碼。
• 在單一 API 要求中關聯多筆追蹤號碼，不必逐一處理每筆追蹤號碼。
• 選擇同步處理以即時取得結果，或選擇非同步處理以進行較大批次的作業。

使用以下端點管理 Advanced Integrated Visibility 專案：

• Tracking Number Association – Synchronous (追蹤號碼關聯 – 同步)：讓您將追蹤號碼與 Webhook 建立關聯，並在同一個 HTTP 回應中接收最終處理狀態。
• Tracking Number Association – Asynchronous (追蹤號碼關聯 – 非同步)：讓您將追蹤號碼與 Webhook 建立關聯，並於稍後使用傳回的 jobId 來檢查非同步工作的狀態或使用相關端點下載詳細資料：
  • Tracking Number Job Status
  • Tracking Number Job Details

您可從 Advanced Integrated Visibility 專案總覽取得這些 API。

僅可依上方螢幕截圖所示，透過專案總覽存取這些 API。

下表總結了同步和非同步 Tracking Number Association (追蹤號碼關聯) 端點之間的差異。
 

若您需要即時確認較小批次的追蹤號碼，請使用同步端點。處理較大批次且不需要立即回應時，請使用非同步端點。

您可使用此端點將一筆或多筆追蹤號碼與 Advanced Integrated Visibility Webhook 專案建立關聯，並在同一個 HTTP 回應中接收處理結果。

此端點適用於需要立即確認的應用程式，並支援最多包含 150 筆追蹤號碼的要求。

必要輸入資訊：

• subscriptionID
• trackingNumber

優點

同步端點具有以下優點：

• 即時處理結果
• 在單一回應中提供詳細的成功和失敗資訊
• 每個要求支援最多 150 筆追蹤號碼
• 在處理前強制執行要求驗證與商務規則
• 電腦可辨讀的錯誤代碼和描述性錯誤訊息
• 用於要求追蹤和疑難排解的交易識別碼

Tracking Number Association – Synchronous (追蹤號碼關聯 – 同步) 端點可強制執行多項驗證規則，包括：

• 要求有效且作用中的 subscriptionId
• 每個要求只允許一個 subscriptionId
• 要求一個 trackingNumber
• 確保追蹤號碼符合 FedEx 格式要求，包括追蹤號碼長度限制為 6 至 22 位數

錯誤回應遵循一致的結構，其中 errors[] 包含代碼和訊息，方便進行解析。

"errors": [

{

"code": "ERROR.CODE",

"message": "描述性錯誤訊息"

}

Transaction Number Association – Synchronous (交易號碼關聯 – 同步) 端點允許部分成功。當某些追蹤號碼失效時，Synchronous API 仍可傳回 200 OK 並顯示以下內容：

• failedTrackingNumbers
• 一則描述性訊息

{

"transactionId":

   "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

   "output": {

      "failedTrackingNumbers":

         [ "XXXXX",

         " YYYYY"

         ],

      "message": "以下追蹤號碼由於驗證或系統錯誤而無法上傳"

      }

    }

請參閱商務規則區段，瞭解更多細節與規則。

使用此端點提交一或多筆已訂閱的追蹤號碼，以進行背景處理。

此要求會傳回一個工作識別碼，您可以搭配 Tracking Number Job Status (追蹤號碼工作狀態) 端點監控處理過程，並在工作完成後透過 Tracking Number Job Details (追蹤號碼工作詳細資料) 端點下載處理結果。

必要輸入資訊：

• 動作
• 追蹤號碼詳細資料

您可以在單一要求中與最多 1,000 筆追蹤號碼建立關聯。

優點

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

• 支援大量提交追蹤號碼的作業，最多 1,000 筆
• 允許在背景處理長時間執行的要求
• 啟用工作狀態監控及可下載的處理報告
• 不再擔心工作量大時會導致要求逾時

使用此端點取得非同步工作 (佇列中一或多個連續請求) 的狀態，或所有提交工作的狀態。

執行此請求的必要輸入資訊包括：

• jobID – 指定您要擷取狀態的工作識別碼。

注意：工作識別碼是此端點的選填輸入資訊。如果您未指定工作識別碼，就會收到所有提交工作的狀態。

此請求的成功回應會傳回 jobID、目前工作狀態，以及建立工作和完成工作時間戳記。回應會顯示工作的目前狀態。此外，回應也會包含成功訊息、錯誤或警告，供使用者查看或疑難排解 (若適用)。

• 如果工作狀態顯示為 COMPLETED，表示成功驗證並處理所有追蹤號碼。
  • COMPLETED 狀態表示成功驗證並處理追蹤號碼。不表示成功將所有追蹤號碼新增至 Advanced Integrated Visibility 專案。
  • 對於具有多筆追蹤號碼的工作而言，即使某些號碼無法與專案建立關聯，而其他號碼成功關聯，其狀態仍可視為 COMPLETED。若要確認原始關聯請求中每筆追蹤號碼的狀態，請下載批次報告。

注意：如果工作狀態顯示 FAILED，表示由於多個原因/硬體故障而無法處理要求，使用者必須重試。

下表顯示工作狀態及個別說明：

使用此端點下載處於 COMPLETED 狀態之非同步工作的 JSON 報告。

與此請求相關的必要輸入資訊為：

• jobID – 指定您要擷取狀態的工作識別碼。必須為此端點提供工作識別碼。

附註：

• 您一次只能下載一份非同步工作報告。
• 如果工作非 COMPLETED 狀態，且您嘗試下載報告，系統會顯示錯誤訊息。

此請求的成功回應會提供您 JSON 格式的工作報告。

通用商務規則

• 與 Advanced Integrated Visibility 專案相關聯的追蹤號碼總數沒有限制。
• 與 Advanced Integrated Visibility 專案相關聯的追蹤號碼在成功與 Webhook 建立關聯 40 天後會取消關聯。
• 無法透過 Tracking Number Subscription API 取得受保護的追蹤資訊 (例如收件人地址、收件人簽名及敏感的遞送資訊)。

同步端點的商務規則

• 每個要求的追蹤號碼上限為 150 筆。
• 所有追蹤號碼都必須使用相同的 subscriptionId。
• 指定的 Advanced Integrated Visibility Webhook 訂閱必須有效且處於啟用狀態。
• 要求逾時時間為 30 秒。

非同步端點的商務規則

• 每個要求的追蹤號碼上限為 1,000 筆。
• 在追蹤號碼成功與 Advanced Integrated Visibility Webhook 建立關聯後，非同步要求的工作狀態和工作詳細資料會保留 90 天。