查询订阅详情

请求

GET /openapi/tracking-subscriptions

查询参数

参数	类型	必填	说明
taskId	uint	二选一	订阅任务 ID
trackingNumber	string	二选一	运单号

taskId 与 trackingNumber 必须且只能传其中一个。

请求示例

按任务 ID 查询：

GET /openapi/tracking-subscriptions?taskId=1001

按运单号查询：

GET /openapi/tracking-subscriptions?trackingNumber=123456789012

响应参数

字段	类型	说明
taskId	uint	订阅任务 ID
carrierCode	string	承运商代码
trackingNumber	string	运单号
externalReferenceNo	string	外部业务单号
standardStatus	string	标准状态
carrierStatus	string	承运商原始状态
estimatedDeliveryAt	datetime/null	预计收货时间；承运商未返回或解析失败时为 null
originAddress	object	发货地址；字段缺失时对象内对应字段为空字符串
originAddress.country	string	发货国家
originAddress.state	string	发货州/省
originAddress.city	string	发货城市
originAddress.postalCode	string	发货邮编
originAddress.address	string	发货详细地址
destinationAddress	object	收货地址；字段缺失时对象内对应字段为空字符串
destinationAddress.country	string	收货国家
destinationAddress.state	string	收货州/省
destinationAddress.city	string	收货城市
destinationAddress.postalCode	string	收货邮编
destinationAddress.address	string	收货详细地址
events	array	轨迹事件列表
events[].eventTime	datetime	事件时间
events[].eventCode	string	事件代码
events[].status	string	状态
events[].statusInfo	string	状态信息
events[].description	string	描述
events[].exceptionDescription	string	异常描述
events[].country	string	国家
events[].state	string	州/省
events[].city	string	城市
events[].postalCode	string	邮编
events[].address	string	地址
latestWebhook	object	最近一次 Webhook 状态
latestWebhook.status	string	状态：pending / sending / success / retry_wait / failed
latestWebhook.attemptCount	int	尝试次数
latestWebhook.nextRetryAt	datetime	下次重试时间
latestWebhook.lastAttemptAt	datetime	上次尝试时间
latestWebhook.responseStatusCode	int	响应状态码
latestWebhook.errorMessage	string	错误信息

响应示例

{
  "code": 200,
  "data": {
    "taskId": 1001,
    "carrierCode": "FEDEX",
    "trackingNumber": "123456789012",
    "externalReferenceNo": "ORDER-001",
    "standardStatus": "in_transit",
    "carrierStatus": "In Transit",
    "estimatedDeliveryAt": "2026-06-30T18:00:00Z",
    "originAddress": {
      "country": "US",
      "state": "CA",
      "city": "Los Angeles",
      "postalCode": "90001",
      "address": "123 Main St"
    },
    "destinationAddress": {
      "country": "US",
      "state": "NY",
      "city": "New York",
      "postalCode": "10001",
      "address": "456 Broadway"
    },
    "events": [
      {
        "eventTime": "2024-01-15T10:30:00Z",
        "eventCode": "PU",
        "status": "in_transit",
        "statusInfo": "Picked Up",
        "description": "Shipment picked up",
        "exceptionDescription": "",
        "country": "US",
        "state": "CA",
        "city": "Los Angeles",
        "postalCode": "90001",
        "address": "123 Main St"
      }
    ],
    "latestWebhook": {
      "status": "success",
      "attemptCount": 1,
      "nextRetryAt": null,
      "lastAttemptAt": "2024-01-15T10:35:00Z",
      "responseStatusCode": 200,
      "errorMessage": ""
    }
  },
  "msg": "success"
}

业务逻辑

1. 只能查询当前 API 用户自己的订阅
2. 查询参数 taskId 与 trackingNumber 必须且只能传其中一个
3. 按 trackingNumber 查询时，若同一 API 用户下存在多条相同运单号订阅（不同承运商），返回最新创建的一条（id 最大）
4. 轨迹事件按时间升序排列
5. Webhook 状态为最新一条记录
6. 预计收货时间、发货地址、收货地址为任务级字段，只在成功拉取且承运商返回对应信息后更新；承运商未返回时保留已有值