运费试算 API

POST /v1/fulfillment/shipping/quotes 根据目的地、重量、尺寸、商品属性和服务选择，返回当前可见运输渠道的预算结果。

不知道仓库最终如何分箱时，使用单箱简写。已经知道箱数和每箱数据时，使用 packages[]。

术语与运输渠道一致。

POSThttps://api.hiobuy.com/v1/fulfillment/shipping/quotes

运价是预算，不锁价。仓库称重、体积测量、重新包装和服务审核都可能改变最终费用。即使 quote_status=COMPLETE 也不锁价。

兼容别名：POST /v1/fulfillment/shipments/freight/estimate。新集成请使用 /v1/fulfillment/shipping/quotes。

金额与单位 {#units}

金额全部使用人民币最小单位「分」。5000 表示 ¥50.00。
响应顶层 monetary_unit 为 CNY_minor。
金额对象：{ "amount": 5000, "currency": "CNY" }。
重量单位固定 KG，尺寸单位固定 CM。
渠道和服务使用稳定 code。

请求头 {#request}

POST /v1/fulfillment/shipping/quotes
Authorization: Bearer hio_live_xxx
Content-Type: application/json
Language: zh-CN

展示语言只通过 Language Header 传递。支持：en（默认）、en-US、zh、zh-CN、zh-TW、cn、hk。不要把 language 写在 JSON Body 或 Query 中。

两种请求格式 {#request-formats}

顶层单箱简写字段 weight_kg、length_cm、width_cm、height_cm 不能和 packages[] 同时传递。混用会返回 400 VALIDATION_ERROR。

格式 A：单箱简写 {#format-a}

最小请求：

{
  "destination": {
    "country_code": "KR"
  },
  "weight_kg": 2.05
}

带尺寸的单箱请求：

{
  "destination": {
    "country_code": "KR",
    "postal_code": "04524"
  },
  "weight_kg": 2.05,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 10,
  "attributes": []
}

weight_kg 是预计整票总重量，单位固定为 KG。
length_cm / width_cm / height_cm 单位固定为 CM，必须同时提供或全部省略。
不知道仓库最终如何分箱时，推荐使用此格式。

格式 B：已知包裹 {#format-b}

单箱也可以使用 packages[]：

{
  "destination": {
    "country_code": "KR"
  },
  "packages": [
    {
      "reference": "box-1",
      "weight": {
        "value": 2.05,
        "unit": "KG"
      },
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10,
        "unit": "CM"
      }
    }
  ]
}

多箱示例：

{
  "destination": {
    "country_code": "KR",
    "postal_code": "04524"
  },
  "packages": [
    {
      "reference": "box-1",
      "weight": {
        "value": 1.25,
        "unit": "KG"
      },
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10,
        "unit": "CM"
      }
    },
    {
      "reference": "box-2",
      "weight": {
        "value": 0.8,
        "unit": "KG"
      },
      "dimensions": {
        "length": 20,
        "width": 15,
        "height": 8,
        "unit": "CM"
      }
    }
  ]
}

packages[] 规则：

支持 1–200 个包裹。
只有一个元素代表明确声明单箱；多个元素代表明确声明多箱。
reference 选填，同一请求内不能重复。
packages[].weight 必填，unit 只能是 KG。
packages[].dimensions 选填；提供时 length、width、height、unit 必须完整，unit 只能是 CM。

公共字段 {#shared-fields}

destination

字段	必填	说明
`country_code`	是	两位 ISO 国家代码
`subdivision_code`	否	如 `US-CA`，国家前缀必须与 `country_code` 一致
`region`	否	省州展示名称
`postal_code`	否	必须作为字符串，保留前导零

declared_value

{
  "amount": 5000,
  "currency": "CNY"
}

整票申报价值，amount 为人民币整数分。未知时省略，不要用 0 表示未知。

attributes

商品属性稳定代码数组，来自 GET /v1/fulfillment/shipments/item-attributes。

试算首先只保留适用于 destination.country_code 的渠道，不会混入其他国家的渠道。每个候选渠道再分别判断本次申报属性；命中不支持属性时，该渠道返回 UNAVAILABLE 和 ATTRIBUTE_NOT_SUPPORTED，其他适用渠道仍可正常返回报价。

services

{
  "services": {
    "channel": [
      {
        "code": "LINE_INSURANCE",
        "quantity": 1
      }
    ],
    "outbound": [
      {
        "code": "VACUUM_PACKING",
        "quantity": 1
      }
    ],
    "inbound": [
      {
        "code": "PHOTO",
        "quantity": 3
      }
    ]
  }
}

channel：运输渠道自身增值服务，代码来自渠道目录 value_added_services[].code。
outbound：出库处理服务。
inbound：入库处理服务。
code 使用稳定业务代码。
quantity 为整数，范围 1–999（以 OpenAPI 为准）。
同一分组内 code 不能重复。

channel_codes

用稳定渠道代码限定参与试算的渠道。省略表示试算全部候选。不能传空数组。指定不存在或不可访问的渠道时返回 INVALID_SHIPPING_CHANNEL。

响应 {#response}

{
  "success": true,
  "estimate_type": "DECLARED",
  "completeness": {
    "level": "HIGH",
    "destination": "COMPLETE",
    "package_dimensions": "COMPLETE",
    "package_split": "DECLARED",
    "declared_value": "PROVIDED",
    "attributes": "DECLARED",
    "services": "REQUESTED_ONLY"
  },
  "warnings": [
    {
      "code": "WAREHOUSE_REVIEW_REQUIRED",
      "message": "最终费用需经仓库测量、打包和服务审核。",
      "affects": [
        "FINAL_CHARGES"
      ]
    }
  ],
  "quotes": [
    {
      "channel": {
        "code": "US-SEA",
        "name": "美线海运",
        "description": "普货线路",
        "tags": [
          "GREAT_VALUE"
        ],
        "capabilities": {
          "delivery_methods": [
            "DOOR_DELIVERY",
            "PICKUP"
          ]
        }
      },
      "available": true,
      "quote_status": "COMPLETE",
      "unavailable_reason": null,
      "attribute_evaluation": {
        "status": "SUPPORTED",
        "declared_attributes": [
          {
            "code": "GENERAL",
            "name": "普货"
          }
        ],
        "accepted_attributes": [
          {
            "code": "GENERAL",
            "name": "普货"
          }
        ],
        "unsupported_attributes": []
      },
      "matched_region": {
        "code": "US-WEST",
        "name": "美西",
        "match_type": "COUNTRY_REGION"
      },
      "packages": [
        {
          "reference": "box-1",
          "weight": {
            "value": 2.05,
            "unit": "KG"
          },
          "dimensions": {
            "length": 30,
            "width": 20,
            "height": 10,
            "unit": "CM"
          },
          "weights": {
            "actual": {
              "value": 2.05,
              "unit": "KG"
            },
            "volumetric": {
              "value": 1,
              "unit": "KG"
            },
            "chargeable": {
              "value": 2.5,
              "unit": "KG"
            }
          }
        }
      ],
      "weights": {
        "actual": {
          "value": 2.05,
          "unit": "KG"
        },
        "volumetric": {
          "value": 1,
          "unit": "KG"
        },
        "chargeable": {
          "value": 2.5,
          "unit": "KG"
        }
      },
      "billing_quantity": {
        "value": 2.5,
        "unit": "KG"
      },
      "pricing_selector": {
        "type": "WEIGHT",
        "value": 2.5,
        "unit": "KG",
        "scope": "SHIPMENT"
      },
      "transit_time": {
        "text": "15-18 个工作日",
        "min_business_days": 15,
        "max_business_days": 18
      },
      "charges": {
        "base_freight": {
          "amount": 10000,
          "currency": "CNY"
        },
        "channel_services": {
          "amount": 550,
          "currency": "CNY",
          "known_amount": 550,
          "calculation_status": "CALCULATED",
          "items": []
        },
        "channel_rules": {
          "amount": 0,
          "currency": "CNY",
          "known_amount": 0,
          "calculation_status": "CALCULATED",
          "items": [],
          "aggregation": "SUM_ALL",
          "cap": null
        },
        "outbound_services": {
          "amount": 800,
          "currency": "CNY",
          "known_amount": 800,
          "calculation_status": "CALCULATED",
          "items": []
        },
        "inbound_services": {
          "amount": 300,
          "currency": "CNY",
          "known_amount": 300,
          "calculation_status": "CALCULATED",
          "items": []
        },
        "adjustments": {
          "amount": 0,
          "currency": "CNY",
          "known_amount": 0,
          "calculation_status": "CALCULATED",
          "items": []
        }
      },
      "display_charges": {
        "addition": {
          "amount": 0,
          "currency": "CNY",
          "included_in_total": false
        },
        "floor": {
          "amount": 0,
          "currency": "CNY",
          "included_in_total": false
        }
      },
      "total": {
        "amount": 11650,
        "currency": "CNY"
      },
      "known_total": {
        "amount": 11650,
        "currency": "CNY"
      },
      "warnings": [],
      "service_adjustment_possible": true
    }
  ],
  "monetary_unit": "CNY_minor",
  "generated_at": "2026-09-07T08:00:00Z",
  "request_id": "req_xxx",
  "disclaimer": "基于申报数据的预估费用。"
}

顶层字段：success、estimate_type、completeness、warnings、quotes、monetary_unit（CNY_minor）、generated_at、request_id、disclaimer。

success=true 表示试算请求成功，即使部分渠道 quote_status=UNAVAILABLE。estimate_type 为 DECLARED，表示基于申报数据而非仓库实测。

completeness

说明输入资料完整度，不是可达性保证。

字段	含义
`level`	整体完整度，例如 `HIGH`
`destination`	目的地是否齐全
`package_dimensions`	是否提供尺寸
`package_split`	是否明确声明分箱（`packages[]` 为 `DECLARED`）
`declared_value`	是否提供申报价值
`attributes`	是否声明商品属性
`services`	是否仅包含调用方选择的服务（`REQUESTED_ONLY`）

quote_status {#quote-status}

调用方不能只判断 available，还要判断 quote_status。

`quote_status`	`available`	`total`	含义
`COMPLETE`	`true`	金额对象	完整预算，可以展示，但仍不锁价
`PARTIAL`	`true`	通常为 `null`	缺少部分信息
`REVIEW_REQUIRED`	`true`	通常为 `null`	需要仓库测量或人工审核
`UNAVAILABLE`	`false`	`null`	该渠道不可用，不一定是整个 HTTP 请求失败

total 是完整预算总额。
known_total 是当前能算出的已知费用。
total=null 时，known_total 不能当作完整报价。
unavailable_reason.code 用于程序判断；message 只用于展示。

quotes[] 字段 {#quotes}

字段	说明
`channel`	`{ code, name, description, tags, capabilities }`，与渠道目录同一身份
`channel.capabilities.delivery_methods`	向后兼容的可选增量数组：`DOOR_DELIVERY`（送货上门）、`PICKUP`（网点/自提点自提）、`POST_OFFICE_PICKUP`（邮局自提）。所有报价状态均可返回；旧客户端可以忽略。
`available`	该渠道是否产生可用预算，必须同时看 `quote_status`
`quote_status`	`COMPLETE` · `PARTIAL` · `REVIEW_REQUIRED` · `UNAVAILABLE`
`unavailable_reason`	`{ code, message }` 或 `null`
`attribute_evaluation`	可选的渠道级属性判定：`SUPPORTED`、`UNSUPPORTED` 或 `NOT_DECLARED`，并列出申报、接受和不支持的属性。
`matched_region`	`{ code, name, match_type }` 或 `null`
`packages`	申报或映射后的包裹及逐箱重量
`weights`	整票 `actual` / `volumetric` / `chargeable`，单位 `KG`
`billing_quantity`	该渠道实际收费数量，单位 `KG`、`M3` 或 `KG_PER_M3`
`pricing_selector`	该数量如何命中价格档位（`type`、`value`、`unit`、`scope`）
`transit_time`	参考时效
`charges`	费用分组，见下表
`display_charges`	可能仅用于前端。`included_in_total=false` 时不要再加进 `total`
`total` / `known_total`	完整预算 vs 当前已知费用
`warnings`	渠道级警告
`service_adjustment_possible`	`true` 表示仓库处理后服务和费用仍可能调整

重量：

actual：申报或实测重量
volumetric：体积重
chargeable：最终用于计算运费的重量
billing_quantity：该渠道实际收费使用的数量和单位
pricing_selector：该数量如何命中价格档位
多箱渠道可能按每箱分别取整后再合计

费用分组 {#charges}

分组	含义
`base_freight`	基础国际运费
`channel_services`	渠道强制或调用方选择的增值服务
`channel_rules`	超尺寸、超重、申报价值等线路规则
`outbound_services`	运输单备货 / 出库处理阶段执行的增值服务
`inbound_services`	仓库收货 / 入库处理阶段执行的增值服务
`adjustments`	调整项

入库与出库服务

inbound_services 与 outbound_services 是仓库增值服务的两个不同执行阶段。入库服务发生在仓库收货 / 入库处理时，例如包裹照片、视频录制、验货及客户要求的其它收货服务；出库服务发生在运输单备货 / 出库处理时，例如包裹加固、真空包装、木架 / 木箱包装及其它打包或出库操作。

同一包裹或运输单可能在两个阶段执行不同服务，因此两组费用可以同时出现并同时产生实际收费。Shipping Quote 中的金额仅是适用服务的估算；查询报价本身不会创建或结算一笔额外服务费。最终费用以实际执行的服务及包裹 / 运输单最终服务定价与结算为准。

开发者应在估算履约总成本时使用这两组金额，并将每项估算服务与对应的最终实际费用对账；不得把同一项服务的报价估算再次叠加到该服务的最终收费之上。

示例（金额均为 CNY 分）：

阶段	服务示例	估算金额
入库	包裹照片	`50` 分（¥0.50）
入库	验货	`100` 分（¥1.00）
出库	真空包装	`150` 分（¥1.50）
出库	包裹加固	`200` 分（¥2.00）

以上四项可以同时存在，因为它们是在不同履约阶段执行的不同服务。

每组通常包含：

字段	含义
`amount`	分组合计（分），未知时为 `null`
`currency`	`CNY`
`known_amount`	当前能算出的明细合计
`calculation_status`	例如 `CALCULATED`
`items`	费用明细

channel_rules.aggregation=SUM_ALL 时累计所有命中规则；HIGHEST_ONLY 时按金额倒序只取最高的一条，同价规则等价。channel_rules.cap 是聚合后的封顶金额，null 表示不封顶。调用方必须使用仓库返回的分组 amount，不能自行累加规则明细。

明细 items：

字段	含义
`code`	稳定费用或服务代码
`name`	本地化展示名称
`category`	费用类别
`source`	`MANDATORY` · `DEVELOPER_SELECTED` · `RULE_ENGINE`
`pricing_basis`	计价依据
`quantity`	该行计费数量
`unit_price`	已知时的单价（分）
`amount`	行合计。`null` 表示未知，不是 0
`estimated`	该行是否仍为估算
`calculation_status`	计算状态
`affected_by_packages`	箱数/尺寸是否会影响该行
`included_in_total`	`false` 时不要重复加入 `total`
`reason`	面向用户的补充解释；不得用于程序判断
`condition_match`	`ALL` 表示全部条件满足，`ANY` 表示任一条件满足
`matched_conditions`	规则条件及本次 `actual_value`、配置 `threshold_value`
`rule_type`	按票、按箱、按计费重、禁止下单/出库等规则类型
`charge_mode` / `charge_value`	固定金额、比例或公式及其配置收费标准
`outcome`	规则结果，例如 `CHARGE`
`missing_fields`	当前无法评估时缺少的输入字段

display_charges 可能仅用于前端展示。
included_in_total=false 时不要重复加入 total。
PENDING_INPUT、REVIEW_REQUIRED 或其他未计算规则不适用于本次已知总额；amount=null 不能按零处理，也不能把配置态 charge_value 当作实际收费。
service_adjustment_possible=true 表示仓库处理后服务和费用仍可能调整。

渠道目录的 rule_summary.aggregation、rule_summary.cap 分别对应本接口的 charges.channel_rules.aggregation、charges.channel_rules.cap，两端使用相同语义。

商品属性 {#item-attributes}

GET /v1/fulfillment/shipments/item-attributes 返回可用于 attributes[] 的稳定代码。

错误 {#errors}

HTTP	`error.code`	说明
400	`VALIDATION_ERROR`	结构无效、混用两种请求格式、单位错误或重复代码
400	`INVALID_SHIPPING_CHANNEL`	指定渠道不存在或当前应用不可访问
401	`INVALID_API_KEY`	缺少或无效的 Bearer
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	应用不是仓库履约模式
403	`WAREHOUSE_AUTH_INVALID`	仓库授权缺失、无效或过期
422	`INVALID_COUNTRY_CODE`	国家代码无效
422	`INVALID_ITEM_ATTRIBUTE`	商品属性代码无效
502	`WAREHOUSE_UPSTREAM_ERROR`	仓库服务异常

公开接口没有单独的 AUTHENTICATION_ERROR、WAREHOUSE_AUTH_REQUIRED、WAREHOUSE_SERVICE_UNAVAILABLE。单个渠道的 UNAVAILABLE 不是 HTTP 错误。

获取支持

需要集成帮助？请联系开发者支持 support@hiobuy.com · 预计 1–2 个工作日内回复

发送邮件