批量订阅轨迹

请求

POST /openapi/tracking-subscriptions/batch

请求参数

字段	类型	必填	说明
items	array	是	订阅项数组，最小 1 条
items[].carrierCode	string	是	承运商代码
items[].trackingNumber	string	是	运单号
items[].callbackUrl	string	是	回调 URL
items[].externalReferenceNo	string	否	外部业务单号

请求示例

{
  "items": [
    {
      "carrierCode": "FEDEX",
      "trackingNumber": "123456789012",
      "callbackUrl": "https://example.com/webhook/tracking",
      "externalReferenceNo": "ORDER-001"
    },
    {
      "carrierCode": "UPARCEL",
      "trackingNumber": "987654321098",
      "callbackUrl": "https://example.com/webhook/tracking",
      "externalReferenceNo": "ORDER-002"
    }
  ]
}

响应参数

字段	类型	说明
results	array	每项订阅结果
results[].index	int	原始数组索引
results[].trackingNumber	string	运单号
results[].carrierCode	string	承运商代码
results[].taskId	uint	订阅任务 ID
results[].result	string	操作结果：created / reused / validation_error / unsupported_carrier
results[].message	string	提示信息

响应示例

{
  "code": 200,
  "data": {
    "results": [
      {
        "index": 0,
        "trackingNumber": "123456789012",
        "carrierCode": "FEDEX",
        "taskId": 1001,
        "result": "created",
        "message": "success"
      },
      {
        "index": 1,
        "trackingNumber": "987654321098",
        "carrierCode": "UPARCEL",
        "taskId": 1002,
        "result": "reused",
        "message": "success"
      }
    ]
  },
  "msg": "success"
}

业务逻辑

1. 批量大小上限由配置项 MaxBatchSize 控制（默认 100）
2. 逐项调用订阅逻辑，单条失败不影响其他项
3. 已存在的订阅返回 reused（而非 updated）
4. 校验失败返回 validation_error，不支持的承运商返回 unsupported_carrier