TMS 运单开放接口-询价

基本信息

• 方法：POST
• 路径：/label/rates

用途

按客户编号、发件地址、收件地址、包裹信息与附加选项，查询该用户当前可用的所有渠道报价列表。报价列表会按用户/承运商的隐藏规则做脱敏。

公共请求头

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

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

请求参数

字段	类型	必填	说明
apiUserCode	string	是	客户编号；必须与鉴权用户或 user.userCode 解析出的用户一致
orderUserReferenceCode	string	否	外部参考号，仅记录用
user	object	否	用户对象；userCode 非空时按该编号解析用户
fromAddressId	int	条件必填	发件地址 ID；用户开启 AddressLimit 时必填
shipFrom	object	是	发件地址；开启 AddressLimit 时由 fromAddressId 自动覆写
shipTo	object	是	收件地址
returnAddress	object	否	退件地址
packages	array	是	包裹列表，至少 1 条
products	array	否	商品列表，国际件建议传
options	object	否	附加选项
serviceCodes	array[string]	否	限定服务代码列表，仅用于过滤
sellerOrderNumber	string	否	卖家订单号
carrierCode	string	否	承运商代码，过滤用
serviceCode	string	否	服务代码，过滤用

地址对象字段

用于 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 字段，GetRate 接口可传，其余接口忽略。

字段	类型	必填	说明
userCode	string	否	客户编号；GetRate 传该字段时会覆盖鉴权用户
userName	string	否	用户名
labelCustomPrint	int	否	面单自定义打印选项
USPSMailingDays	int	否	USPS 邮寄天数

请求示例

{
  "apiUserCode": "CUST-001",
  "orderUserReferenceCode": "REF-001",
  "user": {
    "userCode": "CUST-001"
  },
  "fromAddressId": 0,
  "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
  },
  "serviceCodes": ["UPARCEL_GROUND"]
}

成功响应示例

{
  "code": 200,
  "data": {
    "rates": [
      {
        "rateId": "rate_d4g8m1abc",
        "rate": 12.34,
        "charge": 9.10,
        "chargeItems": [
          { "code": "BASE", "value": 10.0, "currencyCode": "USD" },
          { "code": "FUEL", "value": 2.34, "currencyCode": "USD" }
        ],
        "netChargeItems": [
          { "code": "BASE", "value": 7.5, "currencyCode": "USD" }
        ],
        "currencyCode": "USD",
        "carrierCode": "UPARCEL",
        "carrierName": "UPARCEL",
        "serviceCode": "GROUND",
        "accountId": 0
      }
    ],
    "messages": []
  },
  "message": "success"
}

返回字段说明

字段	类型	说明
data.rates	array	报价列表
data.messages	array[string]	询价过程的附加提示信息；非超管用户且系统开启 HideClientRateError 时会被清空
data.rates[].rateId	string	报价 ID
data.rates[].rate	float	报价金额（已含用户报价方案）
data.rates[].charge	float	成本报价，仅在用户为超管时回填
data.rates[].chargeItems	array	报价明细列表
data.rates[].netChargeItems	array	成本明细列表，仅在用户为超管时回填
data.rates[].currencyCode	string	币种，如 USD
data.rates[].carrierCode	string	承运商代码
data.rates[].carrierName	string	承运商名称
data.rates[].serviceCode	string	服务代码
data.rates[].accountId	int	账号 ID，响应里会被强制清零

接口说明

• 用户开启 AddressLimit 时，fromAddressId 必填，且会覆盖请求中的 shipFrom
• user.userCode 与顶层 apiUserCode 必须一致
• shipTo.phoneExtension 不参与询价
• 包裹的 hazMat、reference3、quantityUnitPcs 字段当前不参与询价

错误响应示例

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

code	message	场景
401	请传入API授权信息	缺少 Apikey
401	请传入apiSign授权签名信息	缺少 Apisign
400	由 Gin 绑定错误文本决定	参数绑定失败
400	xxx apiUserCode不匹配	apiUserCode 与解析用户不一致
400	未查到渠道报价	询价无可用报价

响应码约定：

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