跳到主要内容

批量获取物流轨迹

一次请求查询多个跟踪号的物流状态和历史轨迹事件。

接口地址: POST /api/track-points/batch

所需权限 (Scope): track-points:read

请求​

请求体:

名称类型是否必填描述
TrackingNumbersstring[]是要查询的跟踪号列表。

请求体示例​

{
  "TrackingNumbers": ["TRACK123456", "TRACK404"]
}

响应​

返回包装在 结果 Result 中的 批量结果 BatchResult:

  • 批量结果中每一项的 Request 为 跟踪号
  • 批量结果中每个成功项的 Data 都是一个 物流轨迹对象。

BatchResult 会保留每个请求项各自的成功或失败状态。因此，即使 HTTP 请求本身成功 + 最外层的 Result 成功，批量结果中仍可能包含失败项。

成功响应示例​

{
  "Data": {
    "AllSucceeded": false,
    "Items": [
      {
        "Request": "TRACK123456",
        "Result": {
          "Succeeded": true,
          "Data": {
            "TrackingNumber": "TRACK123456",
            "Status": "DataReceived",
            "Events": [
              {
                "TimeLocal": "2026-03-09T19:36:34",
                "TimeUtc": "2026-03-10T02:36:34Z",
                "TimezoneOffset": "-07:00",
                "CarrierEventCode": "GX",
                "Description": "Shipping Label Created, USPS Awaiting Item",
                "Location": {
                  "CountryCode": "US",
                  "City": "WALNUT",
                  "Province": "CA",
                  "Postcode": "91789"
                }
              }
            ]
          },
          "Error": null,
          "SystemError": null,
          "CapturedValues": null
        }
      },
      {
        "Request": "TRACK404",
        "Result": {
          "Succeeded": false,
          "Data": null,
          "Error": {
            "Code": "TRACK_FAILED",
            "Message": "error message here"
          },
          "SystemError": null,
          "CapturedValues": {}
        }
      }
    ]
  },
  "Succeeded": true,
  "Error": null,
  "CapturedValues": {}
}