Advanced Integrated Visibility 追踪号码订阅 API 使 Advanced Integrated Visibility 订阅用户能够使用 API 端点将追踪号码与 Webhook 项目关联。 追踪号码关联功能支持两种处理方法：

• 追踪号码关联 - 同步会返回同一 HTTP 响应中的处理结果。这种方法最适合那些在关联少量追踪号码时需即时确认的应用程序。 
• 追踪号码关联 – 异步会提交后台处理的请求，并返回一个工作 ID，该 ID 可用于之后检索处理状态和结果。这种方法最适合处理较大批量的追踪号码。 

选择最符合应用程序性能和工作量要求的处理方法。

注意：

• 您必须拥有 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 项目：

• 追踪号码关联 - 同步：让您可将追踪号码与 webhook 关联并在同一 HTTP 响应中接收最终处理状态。
• 追踪号码关联－异步：让您可将追踪号码与 webhook 关联，并在之后使用所返回的 jobId 来查看异步工作状态或通过相关端点下载详细信息：   
  • 查询号码工作状态
  • 查询号码工作详情

您可从 Advanced Integrated Visibility 项目概览中查看这些 API。

这些 API 只能通过您的项目概览访问，如上图所示。

下表总结了同步与异步追踪号码关联端点之间的差异。
 

当您需要对较小批量的追踪号码进行即时确认时，请使用同步端点。当您处理较大批量的数据且不需要即时响应时，请使用异步端点。

使用此端点，可将一个或多个追踪号码与 Advanced Integrated Visibility 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": "Below tracking numbers failed to upload due to validation or system errors"

      }

    }

有关其他详情和规则，请参见业务规则部分。

使用此端点，可提交一个或多个已订阅的追踪号码，以进行后台处理。

该请求会返回一个工作 ID，您可以将该 ID 与追踪号码工作状态端点结合使用以监控处理情况，并将该 ID 与追踪号码工作详情端点结合使用，以便在相应工作完成后下载处理结果。

必填项：

• 操作
• 追踪号码详情

您可以在单个请求中最多关联 1000 个追踪号码。

优点

异步端点具有下列优点：

• 支持最多含 1000 个追踪号码的大批量提交操作
• 允许在后台处理长时间运行的请求
• 启用工作状态监控功能及可下载的处理报告
• 消除大型工作量的请求超时问题

使用此端点获取异步工作（队列中的一个或多个连续请求）的状态或已提交的所有工作的状态。

此请求的所需输入信息如下：

• jobID  – 指定您要检索状态的工作 ID。

注意：工作 ID 是此端点的选填项。如果您不指定工作 ID，那么您将获得所有已提交工作的状态。

此请求的成功响应将返回 jobID、当前工作状态以及工作创建和工作完成时间戳。响应将显示工作的当前状态。此外，响应还将包含成功消息、错误或警告，以便用户查看并在适用情况下进行故障排除。

• 如果工作状态显示为 COMPLETED，则表示所有查询号码均已成功验证并处理。
  • COMPLETED 状态表示查询号码已成功验证并处理。这并不表示所有查询号码都已成功添加到 Advanced Integrated Visibility 项目中。
  • 对于含多个追踪号码的工作，即使在与项目关联时部分号码失败而其他号码成功，状态也会被列为 COMPLETED。如需确认原始关联请求中每个追踪号码的状态，请下载批量报告。

注意：如果工作状态显示为 FAILED，则表示由于各种原因/硬故障，无法处理请求，用户必须再次重试。

下表显示了工作状态及其各自的描述：

使用此端点可下载处于已完成状态的异步工作的 JSON 报告。

与此请求关联的所需输入信息如下：

• jobID  – 指定您要检索状态的工作 ID。使用此端点必须提供工作 ID。

注意：

• 您一次只能下载一份异步工作报告。
• 如果工作尚未完成并且您尝试下载报告，则会显示一条错误消息。

此请求的成功响应将以 JSON 格式向您提供工作的报告。

常用业务规则

• 可与 Advanced Integrated Visibility 项目关联的追踪号码总数没有上限。
• 与 Advanced Integrated Visibility 项目关联的追踪号码会在成功与 webhook 关联后 40 天内被取消关联。
• 无法通过 Tracking Number Subscription API 提供安全追踪信息，比如收件人地址、收件人签名及敏感递送信息。

同步端点的业务规则

• 每个请求最多 150 个追踪号码。
• 所有追踪号码必须使用相同的 subscriptionId。
• 指定的 Advanced Integrated Visibility Webhook 订阅必须有效且激活。
• 请求会有 30 秒超时限制。

异步端点的业务规则

• 每个请求最多 1000 个追踪号码。
• 在追踪号码与 Advanced Integrated Visibility Webhook 成功关联后，异步请求的工作状态和工作详情会保留 90 天。