批量异步创建运单接口

基本信息

• 方法：POST
• 路径：/label/sync-batch-create
• Content-Type：application/json
• 认证方式：OpenAPI Token
• 处理方式：同步受理，异步创建，结果通过回调通知

请求头

Header	类型	必填	说明
Apikey	string	是	API Key
Apisign	string	是	签名
Timestamp	string	是	时间戳，参与签名校验
Content-Type	string	是	固定为 application/json

签名算法与现有 OpenAPI 接口保持一致。

请求参数

顶层结构

{
  "callbackUrl": "https://your-domain.com/callback/batch",
  "items": []
}

字段	类型	必填	说明
callbackUrl	string	是	回调地址，必须是合法 URL
items	array	是	运单列表，单次最多 100 条

items[] 字段

每个 item 在单票创建参数基础上，额外增加批量字段：

字段	类型	必填	说明
itemReference	string	是	调用方自定义子任务标识，同一批次内必须唯一
apiUserCode	string	是*	API 用户编码
serviceCode	string	是*	渠道服务编码
accountId	uint	否	账号 ID
其余字段	—	—	与 POST /label/create 的 Shipment 字段一致

* apiUserCode 或 serviceCode 缺失时，该条会被拒绝，但不影响同批次其他条目受理。

请求示例

{
  "callbackUrl": "https://example.com/webhook/shipment-batch",
  "items": [
    {
      "itemReference": "ORDER-001",
      "apiUserCode": "U10001",
      "serviceCode": "UPS_GROUND",
      "accountId": 0,
      "sellerOrderNumber": "SO-001",
      "shipFrom": {
        "name": "Sender Inc",
        "countryCode": "US",
        "stateCode": "CA",
        "city": "Los Angeles",
        "addressLine1": "123 Main St",
        "postalCode": "90001",
        "phone": "1234567890"
      },
      "shipTo": {
        "name": "Receiver",
        "countryCode": "US",
        "stateCode": "NY",
        "city": "New York",
        "addressLine1": "456 Broadway",
        "postalCode": "10001",
        "phone": "0987654321"
      },
      "packages": [
        {
          "length": 10,
          "width": 8,
          "height": 6,
          "weight": 2.5,
          "quantity": 1
        }
      ],
      "options": {
        "weightUnitCode": "LBS"
      }
    }
  ]
}

受理规则

整批失败

以下情况会直接返回失败，且整批不会受理：

校验项	message
callbackUrl 为空	callbackUrl is required
callbackUrl 格式非法	callbackUrl is invalid
items 为空	items is required
items 数量超限	items exceeds limit {N}
itemReference 为空	itemReference is required
同批次 itemReference 重复	duplicate itemReference in batch

单条拒绝

以下情况只拒绝对应 item，其他合法条目继续受理：

校验项	状态	errorMessage
serviceCode 为空	rejected	serviceCode is required
apiUserCode 为空	rejected	apiUserCode is required

同步响应

通用结构

{
  "code": 200,
  "data": {},
  "message": "success"
}

data 字段

字段	类型	说明
batchId	uint	批次 ID
batchNo	string	批次编号
totalCount	int	提交总数
acceptedCount	int	已受理数量
rejectedCount	int	受理阶段拒绝数量
status	string	批次状态

status 取值

值	说明
processing	存在已受理条目，正在异步处理
partial_success	全部已完成，且存在失败条目
success	全部已受理条目创建成功
failed	全部已受理条目失败，或整批没有受理成功的条目

成功响应示例

{
  "code": 200,
  "data": {
    "batchId": 42,
    "batchNo": "sbl_c8f3k2abc",
    "totalCount": 2,
    "acceptedCount": 2,
    "rejectedCount": 0,
    "status": "processing"
  },
  "message": "success"
}

错误响应示例

{
  "code": 400,
  "data": null,
  "message": "callbackUrl is required"
}

回调通知

接口受理成功后，TMS 会向 callbackUrl 发起 HTTP POST，Content-Type 为 application/json。

单条结果回调

每条 item 到达终态时触发，可能值为 rejected、success、failed。

{
  "batchId": 42,
  "batchNo": "sbl_c8f3k2abc",
  "itemReference": "ORDER-001",
  "status": "success",
  "shipmentNumber": "SH20260611001",
  "trackingCode": "1Z999AA10123456784",
  "errorMessage": ""
}

字段	类型	说明
batchId	uint	批次 ID
batchNo	string	批次编号
itemReference	string	子任务标识
status	string	rejected / success / failed
shipmentNumber	string	运单号，成功时返回
trackingCode	string	主追踪号，成功时返回
errorMessage	string	失败或拒绝原因

批次完成回调

所有已受理条目处理完成后触发；如果整批没有受理成功的条目，也会立即触发。

{
  "batchId": 42,
  "batchNo": "sbl_c8f3k2abc",
  "totalCount": 2,
  "acceptedCount": 2,
  "rejectedCount": 0,
  "successCount": 1,
  "failedCount": 1,
  "status": "partial_success"
}

字段	类型	说明
batchId	uint	批次 ID
batchNo	string	批次编号
totalCount	int	提交总数
acceptedCount	int	受理成功数量
rejectedCount	int	受理拒绝数量
successCount	int	创建成功数量
failedCount	int	创建失败数量
status	string	批次终态

注意事项

• 接口采用“同步受理、异步处理”模式，同步响应只表示请求已受理，不表示运单已创建成功。
• HTTP 状态码固定返回 200，请以响应体中的 code 判断业务结果。
• 同步响应不返回单条 rejected 明细，逐条结果请以回调为准。
• 回调当前不带签名；调用方需保证接口可直接接收来自 TMS 的 POST 请求。
• 回调可能重复投递，调用方应按 batchNo + itemReference 或业务唯一键做幂等处理。
• 回调接收方应尽快返回 HTTP 2xx，否则 TMS 会按重试策略再次投递。

错误码

code	message	说明
200	success	请求受理成功
400	callbackUrl is required	缺少回调地址
400	items exceeds limit 100	超出单批上限
400	duplicate itemReference in batch	批次内引用号重复
401	请传入API授权信息	缺少认证信息
401	签名校验失败	Apisign 无效