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