国际履约概览

/v1/fulfillment/* 涵盖货物进入 HIOBuy 仓库后的国际物流。国内采购见 代购订单。

需要应用开启仓库履约（门户授权）。自履约应用会收到 403 FULFILLMENT_MODE_NOT_SUPPORTED。

API 可用性 {#availability}

路径	状态
/v1/fulfillment/shipments/*	规划中 — 规范已稳定；Gateway 正在逐步上线
/v1/fulfillment/balance	规划中
/v1/shipments（旧版）	已弃用

端到端流程 {#end-to-end-flow}

1. 创建代购订单 → 卖家发货至仓库
2. 订单详情 → 入库后获得 parcel_nos[]
3. 运费估算 → 选择 shipping_channel_code
4. 发货预览 → 精确价格
5. 创建发货单 → 获得 shipment_id
6. 支付发货单 → 扣减钱包
7. 国际物流追踪

端点指南

主题	路径	文档
快速运费报价	POST .../freight/estimate	运费估算
仓库精确报价	POST .../preview	发货预览
创建 / 支付 / 取消 / 详情	POST .../shipments/*	发货单
国际物流轨迹	POST .../logistics/trace	物流追踪
钱包余额	GET /v1/fulfillment/balance	余额
响应字段	—	履约响应模型
商品属性	GET .../item-attributes	运费估算

仓库模式采购

/v1/orders/* 路径不变；Gateway 转发至 HIOBuy。商品 API 仍直接调用各 marketplace。

国内物流轨迹：订单物流追踪（仓库模式下由 Gateway 代理）。

错误

FULFILLMENT_MODE_NOT_SUPPORTED、PARCEL_NOT_FOUND、INVALID_SHIPPING_CHANNEL、INSUFFICIENT_BALANCE — 见 错误码。