TMS 运单开放接口-批量下单

基本信息

• 方法：POST
• 路径：/label/sync-batch-create

用途

接收一次批量下单请求，落库批次与明细，并异步执行。每条明细处理完成以及整批完成时，会向 callbackUrl 发起 POST 回调通知。

公共请求头

所有 TMS 运单开放接口都需要传以下请求头：

Content-Type: application/json
Apikey: {{api_key}}
Apisign: {{api_sign}}
Timestamp: {{timestamp}}

请求参数

字段	类型	必填	说明
callbackUrl	string	是	回调地址，必须为带 scheme 与 host 的合法 URL
items	array	是	批量下单明细列表，至少 1 条，上限由系统配置决定（默认 100）

items 字段

每条元素内嵌运单结构，下表只列出非嵌入字段。

字段	类型	必填	说明
itemReference	string	是	明细外部唯一标识；同一批次内不允许重复
apiUserCode	string	是	该明细对应的客户编号；缺失会被预校验拒绝（apiUserCode is required）
serviceCode	string	是	该明细使用的服务代码；缺失会被预校验拒绝（serviceCode is required）
accountId	int	否	指定账号 ID；当前未消费
shipFrom	object	是	发件地址，结构同运单创建接口
shipTo	object	是	收件地址，结构同运单创建接口
packages	array	是	包裹列表，结构同运单创建接口
products	array	否	商品列表，结构同运单创建接口
options	object	否	附加选项，结构同运单创建接口
sellerOrderNumber	string	否	卖家订单号

请求示例

{
  "callbackUrl": "https://client.example.com/tms/batch-callback",
  "items": [
    {
      "itemReference": "ITEM-001",
      "apiUserCode": "CUST-001",
      "serviceCode": "UPARCEL_GROUND",
      "accountId": 0,
      "shipFrom": {
        "name": "Sender Company",
        "countryCode": "US",
        "stateCode": "CA",
        "city": "Los Angeles",
        "addressLine1": "123 Main St",
        "postalCode": "90001",
        "phone": "1234567890",
        "isResidential": false
      },
      "shipTo": {
        "name": "Receiver Company",
        "countryCode": "US",
        "stateCode": "NY",
        "city": "New York",
        "addressLine1": "456 Madison Ave",
        "postalCode": "10001",
        "phone": "1234567890",
        "isResidential": false
      },
      "packages": [
        {
          "length": 10,
          "width": 8,
          "height": 6,
          "weight": 5.5,
          "quantity": 1,
          "declaredValue": 120
        }
      ],
      "options": {
        "shipDate": "2026-06-26",
        "dimensionUnitCode": "IN",
        "weightUnitCode": "LBS",
        "declaredValueCurrencyCode": "USD"
      },
      "sellerOrderNumber": "SO-20260626-001"
    },
    {
      "itemReference": "ITEM-002",
      "apiUserCode": "CUST-001",
      "serviceCode": "FEDEX_GROUND",
      "shipFrom": {
        "name": "Sender Company",
        "countryCode": "US",
        "stateCode": "CA",
        "city": "Los Angeles",
        "addressLine1": "123 Main St",
        "postalCode": "90001",
        "isResidential": false
      },
      "shipTo": {
        "name": "Receiver Company",
        "countryCode": "US",
        "stateCode": "TX",
        "city": "Houston",
        "addressLine1": "9100 Southwest Freeway",
        "postalCode": "77036",
        "isResidential": false
      },
      "packages": [
        {
          "length": 12,
          "width": 10,
          "height": 8,
          "weight": 7.5,
          "quantity": 1
        }
      ]
    }
  ]
}

成功响应示例

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

返回字段说明

字段	类型	说明
data.batchId	int	批次 ID
data.batchNo	string	批次号，格式为 sbl_ + xid
data.totalCount	int	总条数
data.acceptedCount	int	预校验通过条数
data.rejectedCount	int	预校验拒绝条数（如缺 serviceCode/apiUserCode）
data.status	string	批次状态，见下方

批次状态

取值	含义
pending	待处理（无 accepted 项时短暂出现）
processing	处理中
partial_success	部分成功
success	全部成功
failed	全部失败（含 accepted=0 的情况）

明细状态

取值	含义
pending	待处理
processing	处理中
success	成功
failed	失败
rejected	预校验拒绝

回调通知

回调由系统侧主动发起，POST 到请求里的 callbackUrl，Content-Type: application/json，HTTP 状态码 2xx 视为成功，否则按配置上限重试。

明细级回调（每条处理完成时）

{
  "batchId": 1001,
  "batchNo": "sbl_d4g8m1abc",
  "itemReference": "ITEM-001",
  "status": "success",
  "shipmentNumber": "S202606260001",
  "trackingCode": "1Z999AA10123456784",
  "errorMessage": ""
}

字段	类型	说明
batchId	int	批次 ID
batchNo	string	批次号
itemReference	string	明细外部标识
status	string	明细状态，success / failed / rejected
shipmentNumber	string	成功时回填的 TMS 运单号
trackingCode	string	成功时回填的跟踪号
errorMessage	string	失败/拒绝原因

批次级回调（整批处理完成时）

{
  "batchId": 1001,
  "batchNo": "sbl_d4g8m1abc",
  "totalCount": 2,
  "acceptedCount": 2,
  "rejectedCount": 0,
  "successCount": 2,
  "failedCount": 0,
  "status": "success"
}

字段	类型	说明
batchId	int	批次 ID
batchNo	string	批次号
totalCount	int	总条数
acceptedCount	int	预校验通过条数
rejectedCount	int	预校验拒绝条数
successCount	int	实际下单成功条数
failedCount	int	实际下单失败条数
status	string	批次最终状态

接口说明

• 接口只做请求受理，不阻塞等待下单结果
• 预校验仅检查 serviceCode/apiUserCode 是否为空，以及 itemReference 是否重复；其余业务校验在异步处理阶段完成，失败原因通过明细回调 errorMessage 返回
• 失败的明细会重试，达到上限后标记为 failed 并停止
• items[].accountId 当前未使用
• 异步处理依赖 Redis 队列与定时补偿扫描；Redis 不可用时吞吐会下降

错误响应示例

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

code	message	场景
401	请传入API授权信息	缺少 Apikey
401	请传入apiSign授权签名信息	缺少 Apisign
400	由 Gin 绑定错误文本决定	参数绑定失败
400	callbackUrl is required / callbackUrl is invalid	缺失或非法 callbackUrl
400	items is required	缺失 items
400	itemReference is required / duplicate itemReference in batch	itemReference 缺失或重复
400	items exceeds limit 100	超过单批上限

响应码约定：

• 成功时响应体 code = 200
• 参数校验或业务失败时，通常返回 code = 400
• 鉴权失败时，通常返回 code = 401
• 这套开放接口的成功码不是后台私有接口常见的 0