TMS 运单开放接口-下单

基本信息

方法：POST
路径：/label/create

用途

同步创建 TMS 运单、扣费、并向承运商下单，返回 TMS 运单号、主跟踪号、面单地址、跟踪号列表和费用明细。

公共请求头

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

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

请求参数

请求体顶层是 shipment.Shipment 结构，并通过同一个 body 解析出 accountId、serviceCode、apiUserCode。

字段	类型	必填	说明
apiUserCode	string	是	客户编号；必须与鉴权用户一致
serviceCode	string	是	服务代码，例如 `UPARCEL_GROUND`；为空会返回 `serviceCode is required`
accountId	int	否	指定账号 ID；当前未消费，预留字段
orderUserReferenceCode	string	否	外部参考号
shipFrom	object	是	发件地址
shipTo	object	是	收件地址
returnAddress	object	否	退件地址
packages	array	是	包裹列表，至少 1 条
products	array	否	商品列表，国际件建议传
options	object	否	附加选项
sellerOrderNumber	string	否	卖家订单号；`options.isUniqueSellerOrderNumber` 为真时不允许重复提交
shipmentTrackingManifestType	int	否	Manifest 类型；用户 `ManifestShippingType=2` 且未传时默认 `2`
user	object	否	用户对象；当前未消费

地址对象字段

用于 shipFrom、shipTo、returnAddress 等字段。

字段	类型	必填	说明
code	string	否	地址编码
name	string	否	名称/公司名
attentionName	string	否	联系人姓名
countryCode	string	是	国家代码，如 `US`
stateCode	string	否	州/省代码，如 `CA`、`NY`
city	string	否	城市
addressLine1	string	是	地址行 1
addressLine2	string	否	地址行 2
addressLine3	string	否	地址行 3
postalCode	string	是	邮编
phone	string	否	联系电话
phoneExtension	string	否	电话分机
email	string	否	邮箱
memo	string	否	备注
mid	string	否	MID 标识，部分国际件场景使用
isResidential	bool	否	是否住宅地址，默认 `false`
verifyStatus	int	否	地址校验状态，一般由响应回填，请求可不传

说明：Gin 绑定仅校验地址对象本身非空；实际调用时 countryCode、addressLine1、postalCode 为业务必填。

包裹对象字段

用于 packages[] 数组元素，至少 1 条。

字段	类型	必填	说明
id	int	否	包裹 ID，内部使用，开放接口可不传
length	float	是	长度，单位由 `options.dimensionUnitCode` 决定
width	float	是	宽度
height	float	是	高度
weight	float	是	重量，单位由 `options.weightUnitCode` 决定
quantity	int	否	数量，默认 `1`
declaredValue	float	否	单包裹申报价值
reference1	string	否	参考号 1
reference2	string	否	参考号 2
reference3	string	否	参考号 3
hazMat	object	否	危险品信息
freightClass	string	否	货运等级，LTL 等场景使用
quantityUnitPcs	int	否	件数单位

危险品对象字段

嵌套在 packages[].hazMat 中，仅危险品包裹需要传。

字段	类型	必填	说明
Reference_number	string	否	参考号
shippingName	string	否	危险品正式运输名称
RegulationSet	string	否	法规集，空运常用 `IATA`
TransportationMode	string	否	运输模式，常用 `CAO`
classDivisionNumber	string	否	危险等级/分类号
quantity	string	否	危险品数量
IDNumber	string	否	UN/ID 编号
UOM	string	否	计量单位
PackagingType	string	否	包装类型，如 `FIBERBOARD BOX`

商品对象字段

用于 products[] 数组元素，国际件建议传。

字段	类型	必填	说明
id	int	否	商品 ID，内部使用，开放接口可不传
description	string	否	商品描述
quantity	int	否	数量
weight	float	否	重量
declaredValue	float	否	申报价值
declaredValueClass	int	否	申报价值等级
hsCode	string	否	HS 编码
originCountry	string	否	原产国代码

附加选项对象字段

用于 options 字段。

字段	类型	必填	说明
deliveryConfirmation	string	否	签收确认类型，如 `signature`、`adultSignature`
shipDate	string	否	发货日期，格式 `YYYY-MM-DD`
packageType	string	否	包装类型，如 `YOUR_PACKAGING`
dimensionUnitCode	string	否	尺寸单位，常用 `IN` 或 `CM`
weightUnitCode	string	否	重量单位，常用 `LBS` 或 `KG`
declaredValueCurrencyCode	string	否	申报价值币种，如 `USD`
isUniqueSellerOrderNumber	bool	否	卖家订单号是否唯一，默认 `false`

用户对象字段

用于 user 字段，本接口当前未消费，仅做字段透传。

字段	类型	必填	说明
userCode	string	否	客户编号
userName	string	否	用户名
labelCustomPrint	int	否	面单自定义打印选项
USPSMailingDays	int	否	USPS 邮寄天数

请求示例

{
  "apiUserCode": "CUST-001",
  "serviceCode": "UPARCEL_GROUND",
  "accountId": 0,
  "orderUserReferenceCode": "REF-001",
  "shipFrom": {
    "name": "Sender Company",
    "attentionName": "Tom",
    "countryCode": "US",
    "stateCode": "CA",
    "city": "Los Angeles",
    "addressLine1": "123 Main St",
    "addressLine2": "",
    "postalCode": "90001",
    "phone": "1234567890",
    "email": "demo@example.com",
    "isResidential": false
  },
  "shipTo": {
    "name": "Receiver Company",
    "attentionName": "Jerry",
    "countryCode": "US",
    "stateCode": "NY",
    "city": "New York",
    "addressLine1": "456 Madison Ave",
    "addressLine2": "",
    "postalCode": "10001",
    "phone": "1234567890",
    "email": "demo@example.com",
    "isResidential": false
  },
  "packages": [
    {
      "length": 10,
      "width": 8,
      "height": 6,
      "weight": 5.5,
      "quantity": 1,
      "declaredValue": 120,
      "reference1": "BOX-001"
    }
  ],
  "products": [
    {
      "description": "T-shirt",
      "quantity": 1,
      "weight": 1.2,
      "declaredValue": 25,
      "hsCode": "610910",
      "originCountry": "US"
    }
  ],
  "options": {
    "deliveryConfirmation": "signature",
    "shipDate": "2026-06-26",
    "packageType": "YOUR_PACKAGING",
    "dimensionUnitCode": "IN",
    "weightUnitCode": "LBS",
    "declaredValueCurrencyCode": "USD",
    "isUniqueSellerOrderNumber": false
  },
  "sellerOrderNumber": "SO-20260626-001"
}

成功响应示例

{
  "code": 200,
  "data": {
    "masterTrackingNumber": "1Z999AA10123456784",
    "shipmentOrderNumber": "S202606260001",
    "carrierCode": "UPARCEL",
    "serviceCode": "GROUND",
    "totalCharge": 15.67,
    "currencyCode": "USD",
    "chargeItems": [
      { "code": "BASE", "value": 12.5, "currencyCode": "USD" },
      { "code": "FUEL", "value": 3.17, "currencyCode": "USD" }
    ],
    "labelUrl": "https://api.example.com/file/label/shipment_xxx",
    "labelFileType": "pdf",
    "trackingNumbers": ["1Z999AA10123456784"],
    "labels": [
      {
        "trackingCode": "1Z999AA10123456784",
        "labelUrl": "https://api.example.com/file/label/shipment_xxx/1Z999AA10123456784",
        "fileType": "pdf"
      }
    ],
    "sellerOrderNumber": "SO-20260626-001",
    "createLabelTime": "2026-06-26 10:00:00"
  },
  "message": "success"
}

返回字段说明

字段	类型	说明
data.masterTrackingNumber	string	主跟踪号
data.shipmentOrderNumber	string	TMS 运单号
data.carrierCode	string	承运商代码
data.serviceCode	string	服务代码（来自选中报价）
data.totalCharge	float	总费用
data.currencyCode	string	币种
data.chargeItems	array	费用明细
data.labelUrl	string	主面单地址，格式为 `https://{host}/file/label/{shipmentId}`
data.labelFileType	string	当前固定 `pdf`
data.trackingNumbers	array[string]	全部跟踪号
data.labels	array	面单简表，元素结构见下方
data.sellerOrderNumber	string	卖家订单号
data.createLabelTime	string	下单时间，格式 `YYYY-MM-DD HH:mm:ss`

面单简表对象字段

用于 data.labels[] 数组元素。

字段	类型	说明
trackingCode	string	该面单对应跟踪号
labelUrl	string	面单下载地址
fileType	string	面单文件类型，如 `pdf`

费用明细对象字段

用于 data.chargeItems[] 数组元素。

字段	类型	说明
code	string	费用项代码
value	float	金额
currencyCode	string	币种

接口说明

serviceCode 必须是用户可用渠道，否则返回 xxx渠道不存在 或 xxx不支持该订单信息
用户余额不足时返回 账号余额不足，请先充值
下单成功后立即扣费
面单地址格式固定为 https://{host}/file/label/{shipmentId}
accountId 当前未消费，仅做字段透传
options.isUniqueSellerOrderNumber 为真时，sellerOrderNumber 在同一用户下不允许重复提交

错误响应示例

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

code	message	场景
401	`请传入API授权信息`	缺少 `Apikey`
401	`请传入apiSign授权签名信息`	缺少 `Apisign`
400	由 Gin 绑定错误文本决定	参数绑定失败
400	`serviceCode is required`	未传 `serviceCode`
400	`xxx apiUserCode不匹配`	`apiUserCode` 与鉴权用户不一致
400	`xxx渠道不存在` / `xxx渠道无效`	渠道不存在
400	`账号余额不足，请先充值`	用户余额不足
400	`xxx不支持该订单信息`	服务不支持该订单

响应码约定：

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

基本信息​

用途​

公共请求头​

请求参数​

地址对象字段​

包裹对象字段​

危险品对象字段​

商品对象字段​

附加选项对象字段​

用户对象字段​

请求示例​

成功响应示例​

返回字段说明​

面单简表对象字段​

费用明细对象字段​

接口说明​

错误响应示例​