📦 接口文档

🌐 English Version

对外 API 接口说明：

1：使用 vendor-token 请求头鉴权，请联系业务经理。

2：使用 域名，请联系业务经理。

POST rate 询价

地址：/api/order/rate　·　说明：为客户查询可选渠道的运费报价，不落库、不扣费。

参数说明

关键规则： ① shipping_code 与 shipping_service 可传可不传 —— 不传时返回客户全部可用渠道的报价列表（多渠道并行询价，单渠道失败不影响其他渠道）；传了则只返回该渠道报价。 ② 传了渠道时必须同时传 shipping_code 和 shipping_service 两个参数，缺一不可。
参数 必填 类型 说明
shipping_code 选填 string 渠道编码（如 iusps / fdx / ups / dhl / arm）；不传=全渠道询价
shipping_service 选填 string 渠道服务编码（如 zdgj / fdxp / iups）；与 shipping_code 成对传递
reference 选填 string 订单参考号（询价阶段仅记录，不校验唯一性）
is_signature 选填 int 签名服务 0/1，默认 0
is_insurances 选填 int 保险 0/1，默认 0
unit 选填 int 单位制：默认 1（公制）
currency 选填 string 货币：默认 1（USD 美元）
发货地址（可直接传字段，或仅传 vendor_address_id 由系统带出发货地址）
shipper_name … shipper_zipcode 选填 string 发货人信息，字段见 公共参数表
vendor_address_id 选填 int 客户已保存的发货地址 ID，传了则优先使用
vendor_address_label 选填 string 用户地址编号（客户已保存地址的地址编码 label）；与 vendor_address_id 均为选填，可单独以指定已保存地址，优先级 id > label
收货地址（以下 4 项必填）
recipient_name 是 string 收件人姓名
recipient_street1 是 string 收件地址-街道1
recipient_city 是 string 收件城市
recipient_country 是 string 收件国家（如 US）
其他 recipient_* 选填 string 见 公共参数表
包裹信息（packages 数组格式）
packages 是* array 多包裹数组，元素字段见 包裹参数表；
length/width/height/weight 是* number 传四个尺寸重量字段
weight_unit 是* string 重量单位：lb / g / kg / oz（非法值报错）
length_unit 是* string 长度单位：in / cm / m（非法值报错）
必填约束：至少传递一个包裹（length/width/height/weight 四要素齐全）；收货地址 4 项必填。

请求示例

# 全渠道询价（不传渠道参数）
POST /api/order/rate
Header: vendor-token: xxxxx
Content-Type: application/json
{
    "shipper_name": "John",
    "shipper_street1": "123 Main St",
    "shipper_city": "Los Angeles",
    "shipper_state": "CA",
    "shipper_country": "US",
    "shipper_zipcode": "90001",
    "recipient_name": "Jane",
    "recipient_street1": "456 Oak Ave",
    "recipient_city": "New York",
    "recipient_state": "NY",
    "recipient_country": "US",
    "recipient_zipcode": "10001",
    "packages": [
        {
            "name": "dress",
            "length": 12,
            "width": 10,
            "height": 5,
            "weight": 3.3,
            "weight_unit": "lb",
            "length_unit": "in"
        }
    ]
}

返回示例（data 为渠道报价数组）

{
    "success": true,
    "message": "获取价格成功！",
    "code": 200,
    "data": [
        {
            "success": true,
            "message": "success",
            "fee": 15.05,          // 运费
            "zone": "zone8",           // 区域
            "billing_weight": 3.3069,   // 计费重量(lb)
            "currency_id": 1,            // 货币：1-美元
            "shipping_service": "zdgj", // 渠道服务编码
            "shipping_code": "iusps",   // 渠道编码
            "carrier_name": "USPS",     // 承运商名称
            "carrier_code": "usps",     // 承运商编码
            "carrier_logo": "https://.../usps.png", // 承运商logo
            "content": null
        }, // ... 其余渠道
        {
            "success": false,       // 单个渠道失败不影响整体
            "message": "该渠道暂不支持寄往该收件区域，请更换渠道",
            "shipping_service": "fdx",
            "shipping_code": "iexp2",
            "carrier_name": "FedEx",
            "carrier_code": "fedex",
            "carrier_logo": "https://.../fedex.png",
            "content": null
        }
    ]
}
data[] 字段 类型 说明
success bool 该渠道是否报价成功；false 时 message 为失败原因，其余承运商字段仍返回
message string 成功 success / 失败原因
fee number 最终运费（已含加价/附加费）
zone string 分区（如 zone8）
billing_weight number 计费重量（lb）
currency_id int 货币 ID，默认 1（美元）
shipping_service / shipping_code string 渠道服务编码 / 渠道编码
carrier_name / carrier_code / carrier_logo string 承运商名称 / 编码 / logo
content null 下单内容占位（部分接口下单与询价一体时使用），当前为 null