国际履约概览

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

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

入库预报创建、运输单创建和运输单支付均支持可选 Idempotency-Key 请求头，用于保护重试及并发调用。重复冲突可能通过 error.details.existing_resource 返回已有包裹、运输单或支付信息。

金额单位 {#monetary-unit}

带金额的履约接口标准 JSON 响应会带顶层 monetary_unit: "CNY_minor"。所有 { amount, currency } 的 amount 均为 人民币分（1 元 = 100 分）。见 履约响应模型。

API 可用性 {#availability}

路径状态
/v1/fulfillment/inbounds/create仓库模式 Live（仓库 simple-store）；沙箱 mock
/v1/fulfillment/packages仓库模式 Live（packages/index）；沙箱 mock
/v1/fulfillment/packages/{package_id}仓库模式 Live（packages/detail/{id}）；沙箱 mock
/v1/fulfillment/packages/{package_id}/tracking仓库模式 Live（packages/logs/{id}）；沙箱 mock
/v1/fulfillment/unclaimed-packages仓库模式 Live（列表 + 认领）；沙箱 mock
/v1/fulfillment/returnsMock — 退运创建 / 列表 / 确认 / 取消
/v1/fulfillment/locations仓库模式 Live（warehouse）；沙箱 mock
/v1/fulfillment/value-added-services仓库模式 Live（services）；沙箱 mock
/v1/fulfillment/service-requestsMock — 创建 / 列表 / 详情 / 确认
/v1/fulfillment/shipments/{id}/intercept仓库模式 Live（shipments/set-exceptional）；沙箱 mock
/v1/fulfillment/shipments仓库模式 Live（shipments/index）；沙箱 mock
/v1/fulfillment/shipping/channels仓库模式 Live（渠道目录）；沙箱 mock
/v1/fulfillment/shipping/quotes仓库模式 Live（运费试算）；沙箱 mock
/v1/fulfillment/shipments/*可用（已配置时走仓库 HTTP，否则 mock）
/v1/fulfillment/balance可用
/v1/shipments（旧版）已弃用

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

  1. 创建代购订单 → 卖家发货至仓库
    或 入库预报（你已掌握的包裹）
  2. 包裹详情 / 履约轨迹 → 仓库测量 / 异常 / VAS / 仓内时间线
    或 订单详情 → 代购入库后的 tracking_numbers[]
  3. 运输渠道 查看能力，再 运费试算 → 选择 quotes[].channel.code
  4. 创建发货单 → 获得 id / order_sn（PENDING）
  5. 仓库打包与实测 → boxes[]、最终重量 / 尺寸、最终运费
  6. 发货单进入可支付状态（WAIT_PAYMENT）→ 见详情；过早支付会返回 409 SHIPMENT_NOT_READY_FOR_PAYMENT
  7. 支付发货单 → 扣减钱包
  8. 列表 / 详情 → 轻量行，或分箱 / 打包影像 / timeline / 头尾程单号
    可选：拦截（WAIT_SHIP / SHIPPED）
  9. 国际物流追踪 → 扫描事件

第一次接入仓库履约？ 按 WH-DEV 测试指南完整跑通一次流程，包括仓库打包与结算环节。

开始 WH-DEV 测试 →

端点指南

主题路径文档
入库预报POST .../inbounds/create入库预报
包裹详情 / 轨迹 / 无人认领GET .../packages/* · unclaimed-packages包裹
退运POST/GET .../returns · confirm/cancel退运
仓点GET .../locations仓点
增值服务GET .../value-added-servicesVAS
服务申请POST/GET .../service-requests · confirm服务申请
运输渠道GET .../shipping/channels运输渠道
运费试算POST .../shipping/quotes运费试算
创建 / 支付 / 取消 / 拦截POST .../shipments/create · {id}/pay · {id}/cancel · {id}/intercept发货单
发货单列表GET .../shipments发货单 · 列表
发货单详情GET .../shipments/{id}发货单 · 详情
国际物流轨迹GET .../shipments/{id}/tracking物流追踪
钱包余额GET /v1/fulfillment/balance余额
响应字段—履约响应模型
商品属性GET .../item-attributes运费试算

仓库模式采购

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

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

生命周期状态图 {#lifecycle}

流转图见 包裹、发货单、退运。

错误

FULFILLMENT_MODE_NOT_SUPPORTED、SHIPMENT_CREATE_EXCEPTION、PARCEL_NOT_FOUND、EXTERNAL_ORDER_ID_ALREADY_EXISTS、SHIPMENT_ALREADY_PAID、INSUFFICIENT_BALANCE、NOT_FOUND（SHIPMENT_NOT_EXISTS）、拦截相关码（SHIPMENT_NOT_FOUND、SHIPMENT_NOT_INTERCEPTABLE、SHIPMENT_INTERCEPTION_ALREADY_REQUESTED）— 见 错误码 与 发货单。

获取支持

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

发送邮件