运单服务-询价

基本信息

• 方法：POST
• 路径：/label/carrier/rate
• Handler：carrierApi.GetRate
• Service：CarrierOpenAPIService.GetRate

用途

根据承运商、服务代码、账号别名、发件地址、收件地址和包裹信息查询可用报价。

公共请求头

所有承运商开放接口（询价 / 下单 / 取消 / 轨迹 / 地址校验）都需要传以下请求头：

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

鉴权规则：

• Apikey 不能为空
• Apisign 不能为空
• Timestamp 参与签名校验
• 鉴权成功后，系统会把当前 OpenAPI 用户写入上下文中的 userId

请求参数

字段	类型	必填	说明
externalRequestId	string	是	外部请求号
carrierCode	string	是	承运商代码
serviceCode	string	否	服务代码
accountAlias	string	否	账号别名，多账号场景建议传
accountId	int	否	预留字段，当前未使用
senderAddress	object	是	发件地址，结构见下方地址对象字段
recipientAddress	object	是	收件地址，结构见下方地址对象字段
packages	array	是	包裹列表，至少 1 条，元素结构见下方包裹对象字段
products	array	否	商品列表，国际件建议传，元素结构见下方商品对象字段
options	object	否	附加选项，结构见下方附加选项对象字段

地址对象字段

用于 senderAddress、recipientAddress、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 中，仅危险品包裹需要传。

字段	类型	必填	说明
ReferenceNumber	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、adult_signature
shipDate	string	否	发货日期，格式 YYYY-MM-DD
packageType	string	否	包装类型，如 YOUR_PACKAGING
dimensionUnitCode	string	否	尺寸单位，常用 IN 或 CM
weightUnitCode	string	否	重量单位，常用 LBS 或 KG
declaredValueCurrencyCode	string	否	申报价值币种，如 USD
isUniqueSellerOrderNumber	bool	否	卖家订单号是否唯一，默认 false

请求示例

{
  "externalRequestId": "REQ-20260611-RATE-001",
  "carrierCode": "UPARCEL",
  "serviceCode": "GROUND",
  "accountAlias": "UPARCEL_MAIN",
  "accountId": 0,
  "senderAddress": {
    "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
  },
  "recipientAddress": {
    "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",
      "reference2": "",
      "reference3": ""
    }
  ],
  "products": [
    {
      "description": "T-shirt",
      "quantity": 1,
      "weight": 1.2,
      "declaredValue": 25,
      "hsCode": "610910",
      "originCountry": "US"
    }
  ],
  "options": {
    "deliveryConfirmation": "signature",
    "shipDate": "2026-06-11",
    "packageType": "YOUR_PACKAGING",
    "dimensionUnitCode": "IN",
    "weightUnitCode": "LBS",
    "declaredValueCurrencyCode": "USD",
    "isUniqueSellerOrderNumber": false
  }
}

成功响应示例

{
  "code": 200,
  "data": {
    "rates": [
      {
        "rateId": "rate_d4g8m1abc",
        "carrierCode": "UPARCEL",
        "serviceCode": "GROUND",
        "estDays": 3,
        "costEstimate": {
          "amount": 12.34,
          "currencyCode": "USD",
          "source": "carrier_cost"
        }
      }
    ]
  },
  "message": "success"
}

返回字段说明

字段	类型	说明
data.rates	array	报价列表
data.messages	array	附加提示信息，通常为空
data.rates[].rateId	string	报价 ID
data.rates[].carrierCode	string	承运商代码
data.rates[].carrierName	string	承运商名称
data.rates[].serviceCode	string	服务代码
data.rates[].estDays	int	预计妥投天数
data.rates[].costEstimate	object	成本摘要，无成本时可能为空
data.rates[].costEstimate.amount	float	预估成本金额
data.rates[].costEstimate.currencyCode	string	币种，如 USD
data.rates[].costEstimate.source	string	成本来源，当前固定为 carrier_cost

接口说明

• 该接口内部会把请求转换为标准 shipment.Shipment 后调用渠道适配器 GetRate()
• serviceCode 不传时，会按账号可用服务解析
• 如果账号解析失败，会直接返回错误

错误响应示例

{
  "code": 400,
  "data": null,
  "message": "未找到可用的账号服务"
}

code	message	场景
401	请传入API授权信息	缺少 Apikey
401	请传入apiSign授权签名信息	缺少 Apisign
400	由 Gin 绑定错误文本决定	参数绑定失败
400	未找到可用的账号服务	找不到可用账号
400	存在多个可用账号，请提供 accountAlias 进行消歧	多账号未消歧
400	unsupported carrier	不支持的承运商

响应码约定：

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