运输渠道 API

GET /v1/fulfillment/shipping/channels 返回当前应用所绑定仓库中已启用且拥有有效价格配置的国际运输渠道。

用此接口做渠道选择器或查看能力。地址级可用性与金额必须通过运费试算确认。这里的价卡只解释计价方式，不锁价。

GEThttps://api.hiobuy.com/v1/fulfillment/shipping/channels

需要仓库履约。沙箱 hio_test_* 密钥返回确定性 mock 数据。

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

金额与单位 {#units}

所有金额 amount 均为人民币整数分。1000 表示 ¥10.00。
响应顶层 monetary_unit 固定为 CNY_minor。
金额对象格式：

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

KG = 千克，CM = 厘米，M3 = 立方米，KG_PER_M3 = 千克/立方米。
渠道、分区、服务请使用稳定 code，不要依赖 name。
不公开仓库数据库 ID、Developer Code、内部鉴权或供应商接口地址。

请求 {#request}

GET /v1/fulfillment/shipping/channels?country_code=US&include=regions,services,rate_cards,rules&page=1&page_size=20
Authorization: Bearer hio_live_xxx
Language: zh-CN

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

Query 参数

参数	必填	默认值	说明
`channel_code`	否	—	稳定渠道代码精确筛选（最长 64）
`country_code`	否	—	ISO 3166-1 alpha-2 目的国家代码；传入后不会返回其他国家的渠道。
`include`	否	—	逗号分隔展开：`regions`、`services`、`rate_cards`、`rules`
`page`	否	`1`	页码，从 1 开始
`page_size`	否	`20`	每页条数，最大 50

`include` 展开

不传 include 时只返回轻量渠道摘要。

`include` 值	返回字段	用途
`regions`	`regions`	配送分区与参考时效
`services`	`value_added_services`	渠道增值服务，供试算使用
`rate_cards`	`rate_cards`	参考价格表，只解释计价方式
`rules`	`channel_rules`	渠道可能存在的收费与限制规则

可组合，例如 include=regions,services,rate_cards,rules。未知值返回 400 VALIDATION_ERROR。

rate_cards 带 reference_only，不能代替 POST /v1/fulfillment/shipping/quotes。只有 include=rate_cards 才会向仓库拉取价格表。

只有已启用并且拥有有效价格配置的渠道才会返回。items 为空表示当前筛选条件下没有匹配渠道。

响应 {#response}

响应示例与英文档同一结构。关键顶层字段：items、pagination、monetary_unit（CNY_minor）、generated_at、request_id。

{
  "items": [
    {
      "code": "US-SEA",
      "name": "美线海运",
      "description": "普货线路",
      "status": "ACTIVE",
      "tags": [
        "GREAT_VALUE"
      ],
      "warehouse": {
        "code": "SZ",
        "name": "深圳仓"
      },
      "capabilities": {
        "delivery_methods": [
          "DOOR_DELIVERY"
        ],
        "multi_package_supported": true,
        "tracking_supported": true,
        "shipping_label_supported": false
      },
      "requirements": {
        "weight": "REQUIRED",
        "dimensions": "CONDITIONAL",
        "postal_code": "OPTIONAL",
        "declared_value": "OPTIONAL",
        "customs_code": "OPTIONAL",
        "personal_customs_code": "OPTIONAL",
        "recipient_identity": "OPTIONAL"
      },
      "attribute_matching": {
        "mode": "ANY_OF",
        "accepted_attributes": [
          {
            "code": "GENERAL",
            "name": "普货"
          }
        ],
        "unsupported_attributes": [
          {
            "code": "SENSITIVE",
            "name": "敏感货"
          }
        ]
      },
      "billing": {
        "basis": "WEIGHT",
        "calculation_model": "FIRST_NEXT_WEIGHT",
        "quantity_unit": "KG",
        "supported_range": {
          "minimum": {
            "value": 0.5,
            "unit": "KG"
          },
          "maximum": {
            "value": 30,
            "unit": "KG"
          },
          "out_of_range_behavior": "UNAVAILABLE"
        },
        "minimum": {
          "value": 0.5,
          "unit": "KG",
          "ceil_to_minimum": true
        },
        "rounding": {
          "single_package_step": {
            "value": 0.5,
            "unit": "KG"
          },
          "multi_package_step": {
            "value": 0.5,
            "unit": "KG"
          },
          "ignore_below": {
            "value": 0.05,
            "unit": "KG"
          }
        },
        "volumetric_weight": {
          "enabled": true,
          "divisor": 6000,
          "average_with_actual": false,
          "exemption": null
        },
        "overweight_warning": {
          "enabled": false,
          "threshold": {
            "value": 0,
            "unit": "KG"
          },
          "notice": null
        }
      },
      "rule_summary": {
        "aggregation": "SUM_ALL",
        "cap": null,
        "has_surcharges": true,
        "has_order_restrictions": false,
        "has_dispatch_restrictions": true,
        "evaluated_by_quote": true
      },
      "service_policy": {
        "warehouse_may_add_services": true,
        "warehouse_may_remove_services": true,
        "prices_may_change_after_inspection": true
      },
      "final_quote_required": true,
      "config_updated_at": "2026-09-07T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "has_more": false
  },
  "monetary_unit": "CNY_minor",
  "generated_at": "2026-09-07T09:00:00Z",
  "request_id": "req_xxx"
}

regions、value_added_services、rate_cards、channel_rules 仅在对应 include 后出现。完整展开示例见英文文档或下方字段表。

响应字段 {#fields}

字段	说明
`items[]`	匹配渠道。无匹配时为空数组。
`items[].code`	稳定渠道代码。试算 `channel_codes` 与创建发货单使用此值。
`items[].name`	展示名称（`Language` Header）。
`items[].description`	展示描述。
`items[].status`	目录状态。返回的渠道为 `ACTIVE`。
`items[].tags`	稳定标签。
`items[].warehouse`	绑定仓库 `{ code, name }`，不是数据库 ID。
`items[].capabilities`	配送方式、多箱、轨迹、面单能力。
`items[].requirements`	输入完整度：`REQUIRED` · `OPTIONAL` · `CONDITIONAL` · `NOT_SUPPORTED`。
`items[].attribute_matching`	`ANY_OF` 或 `ALL_REQUIRED`，以及互斥的 `accepted_attributes[]` 与可选的 `unsupported_attributes[]` 属性目录。
`items[].billing`	计价方式，见下表。
`items[].rule_summary`	是否存在附加费或限制；规则由试算评估。
`items[].regions`	`include=regions` 时返回。
`items[].value_added_services`	`include=services` 时返回。
`items[].rate_cards`	`include=rate_cards` 时返回，且 `reference_only=true`。
`items[].channel_rules`	`include=rules` 时返回结构化收费和限制规则。
`items[].service_policy`	仓库处理后可能增删服务或改价。
`items[].final_quote_required`	`true` 表示仍需票级试算。
`items[].config_updated_at`	该渠道配置更新时间。
`pagination`	`page` / `page_size` / `total` / `has_more`。
`monetary_unit`	固定 `CNY_minor`。
`generated_at`	响应时间。
`request_id`	与 `x-request-id` 对应。

billing {#billing}

字段	含义
`basis`	`WEIGHT`、`VOLUME` 或 `DENSITY`
`calculation_model`	渠道采用的计价模型
`quantity_unit`	`KG`、`M3` 或 `KG_PER_M3`
`supported_range`	支持的计价范围
`out_of_range_behavior=UNAVAILABLE`	超出范围后渠道不可用，不能用最后一档外推
`minimum`	最低计费量，以及是否向上取整
`rounding`	单箱和多箱取整规则
`volumetric_weight`	体积重规则与换算系数
`multi_package`	多箱分别计费还是合并计费
`overweight_warning`	超重提醒

regions {#regions}

字段	含义
`code` / `name`	稳定分区代码与名称
`match_type`	`COUNTRY_REGION` 或 `POSTAL_CODE`
`countries`	覆盖的国家代码
`postal_code_required`	为 `true` 时试算需传邮编
`reference_transit_time`	参考时效
`areas`	更细分区；目录不暴露完整邮编规则库

value_added_services {#value-added-services}

code 是调用 shipping/quotes 时使用的稳定服务代码。

request_mode：MANDATORY 强制，OPTIONAL 可选（即是否 required）。
pricing_type：固定价格或动态计算。
pricing_scope：服务适用范围。
仓库可能在实际处理时增加、删除或调整服务。

region_prices[] 按 region_code 匹配分区。PERCENT 使用百分点（10 表示 10%）；MINOR_UNIT 使用人民币分（5 表示 ¥0.05）。必须结合 pricing_basis 解释 value：它可能乘以基础运费、申报价值、票数、总箱数、计费或实际重量、总箱数 - 1、原始包裹数或实际体积，之后再加上 fixed_charge。

BASE_FREIGHT_PERCENT：基础运费 × 比例 + fixed_charge。
DECLARED_VALUE_PERCENT：申报价值 × 比例 + fixed_charge。
PER_SHIPMENT：按票 value + fixed_charge。
当 value=0 且 fixed_charge.amount=0 时，该分区未配置服务费，不能视为本次已产生 ¥0.00 费用。
final_quote_required=true 表示目录公式仅用于解释，实际收费以运费试算为准。

channel_rules {#channel-rules}

include=rules 返回配置态规则。aggregation=SUM_ALL 表示累计所有命中费用；HIGHEST_ONLY 表示按金额倒序只取最高的一条，同价规则视为等价。cap 是聚合后的封顶金额，null 表示不封顶。

每条 items[] 使用稳定的 code，并通过 regions[]、condition_match、conditions[]、rule_type、charge_mode、charge_value、min_charge、max_charge 和 formula 解释适用区域、触发条件和收费方式。conditions[].parameter/operator/threshold_value/unit 是配置阈值，不是某票货物的实际值。

目录规则只表示渠道可能存在的配置，不代表本次一定收费。实际命中情况见试算的 matched_conditions[]；实际金额只认 amount 且 included_in_total=true。不要解析名称或 reason 推断业务逻辑。

rate_cards {#rate-cards}

包含 region_code、billing_basis、calculation_model、quantity_unit、price_rows。reference_only=true 表示仅供参考。

缓存 {#caching}

config_updated_at 变化时重新拉取展开数据。创建发货前始终调用运费试算。当前没有锁价版本。

错误 {#errors}

某个筛选条件下没有渠道不是 HTTP 错误，而是 items: []。

HTTP	`error.code`	说明
400	`VALIDATION_ERROR`	分页、国家代码语法或 `include` 无效
401	`INVALID_API_KEY`	缺少或无效的 Bearer
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	应用不是仓库履约模式
403	`WAREHOUSE_AUTH_INVALID`	仓库授权缺失、无效或过期
422	`INVALID_COUNTRY_CODE`	国家代码无效或不支持
502	`WAREHOUSE_UPSTREAM_ERROR`	仓库服务异常，请退避重试

公开接口没有单独的 AUTHENTICATION_ERROR、WAREHOUSE_AUTH_REQUIRED、WAREHOUSE_SERVICE_UNAVAILABLE。鉴权失败用 401 INVALID_API_KEY，未绑定仓库用 403 WAREHOUSE_AUTH_INVALID，仓库不可用用 502 WAREHOUSE_UPSTREAM_ERROR。

下一步：按目的地做运费试算。

获取支持

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

发送邮件