WH-DEV 履约测试指南

在上线前完整跑通一次 HIOBuy 仓库履约流程。

本页是流程指南，不是接口参考；每一步都会链接到对应的接口文档。

WH-DEV 是受控的集成测试环境

测试期间，部分实物仓库作业（收货、打包、称重、出库、轨迹推进）可能需要 HIOBuy 团队协助模拟。

生产环境中这些作业由正常的 HIOBuy 仓库流程完成，不需要你为每个发货单联系客服。

开始之前

前置条件获取方式
已开通仓库履约的开发者订阅Growth 或 Enterprise 套餐，见 仓库履约授权绑定
WH-DEV 仓库开发者代码审核通过后由 HIOBuy 发放
应用已设置为 HIOBuy 仓库履约门户 → 授权 
生产 API Key（hio_live_*）身份认证
测试钱包余额钱包余额 — 支付发货单前先充值
测试收货地址与可用物流渠道由 HIOBuy 在你的 WH-DEV 仓库上配置

不要用沙箱 Key（hio_test_*）测试 WH-DEV。沙箱返回的是与你所分配仓库无关的固定 fixture。WH-DEV 集成测试使用 hio_live_* + WH-DEV 代码，它仍然是测试仓库配置，并不代表已在做真实履约。见 沙箱环境。

还没有 WH-DEV 代码？请先看 仓库履约授权绑定。

端到端测试流程

#步骤接口文档
1将 WH-DEV 代码绑定到应用—（门户操作）仓库履约授权绑定
2a创建代购订单，由卖家发货到仓库POST /v1/orders/create创建订单
2b或 预报你已掌握的包裹POST /v1/fulfillment/inbounds/create入库预报
3轮询包裹直到 RECEIVEDGET /v1/fulfillment/packages/{package_id}包裹
4询价国际运费POST /v1/fulfillment/shipping/quotes运费报价
5用 tracking_numbers[]、receiver、shipping_channel_code 创建发货单POST /v1/fulfillment/shipments/create发货单 · 创建
6仓库打包与实测期间轮询发货单GET /v1/fulfillment/shipments/{id}发货单 · 详情
7达到可支付状态后支付POST /v1/fulfillment/shipments/{id}/pay发货单 · 支付
8出库后读取扫描轨迹GET /v1/fulfillment/shipments/{id}/tracking国际轨迹

发货单 status 推进：PENDING → WAIT_PAYMENT → WAIT_SHIP → SHIPPED → SIGNED。

开发者动作 vs 仓库动作

阶段你（开发者）HIOBuy WH-DEV
仓库授权配置应用提供 WH-DEV 代码
代购 / 入库预报调用接口—
包裹到仓轮询包裹状态模拟仓库收货
包裹已入库查询包裹详情更新仓库状态
运费报价调用接口—
创建发货单调用接口—
从库位取货—仓库模拟
合箱 / 打包—仓库模拟
实测重量与尺寸轮询发货单详情仓库模拟
结算调用支付接口—
出库轮询发货单详情仓库模拟
轨迹推进调用轨迹接口模拟扫描事件

出库打包与支付

为什么创建发货单后不能立刻支付？

新建的发货单通常处于 PENDING：

{
  "id": "115",
  "status": "PENDING",
  "payment_status": "UNPAID",
  "boxes": [],
  "times": {
    "packed_at": null
  }
}

这是正常状态。仓库还需要完成：

  1. 从库位取出包裹
  2. 合并所选包裹
  3. 打包出库箱
  4. 实测最终重量
  5. 实测最终尺寸
  6. 计算最终运费

完成后发货单才会进入可支付状态（WAIT_PAYMENT）。

如果过早调用支付：

POST /v1/fulfillment/shipments/115/pay
Authorization: Bearer hio_live_...

可能返回：

HTTPerror.code
409SHIPMENT_NOT_READY_FOR_PAYMENT

这不是接口报错，而是表示仓库打包与实测尚未完成。

请轮询发货单详情，确认可支付后再调用支付。可用于判断的字段：

字段可支付时的取值
statusWAIT_PAYMENT
payment_statusUNPAID 且 total.outstanding > 0
times.packed_at非 null
boxes[]非空，且带最终 weight / dimensions

其他支付错误：404 NOT_FOUND（发货单不存在）、409 SHIPMENT_ALREADY_PAID、402 INSUFFICIENT_BALANCE（请通过钱包余额充值）。完整列表见 发货单 · 支付 与 错误码。

WH-DEV 仓库模拟

WH-DEV 不是持续运行的生产仓库。测试期间以下事件可能需要 HIOBuy 协助模拟：

  • 包裹收货
  • 包裹质检
  • 包裹上架存储
  • 出库打包
  • 实测重量
  • 实测尺寸
  • 发货单出库
  • 轨迹推进
  • 签收完成

如果测试正在等待上述事件，可发邮件至 support@hiobuy.com，或提交工单。

协助请求模板

Subject: WH-DEV Fulfillment Test Assistance

Application:
WH-DEV Code:

Package ID:
Shipment ID:
Order SN:

Current Status:

Expected Next Test Step:

Request ID:

每个接口响应都会返回 request_id，附带它能帮助开发者支持团队更快定位你的请求。

生产环境有什么不同？

WH-DEV 中部分实物事件需要按需模拟；生产环境中真实包裹按正常仓库流程流转：

这些都属于常规仓库作业，不需要你为每个发货单联系 HIOBuy 客服。应用只需要：

  • 监听发货单状态
  • 查询发货单详情
  • 等待进入可支付状态
  • 完成结算
  • 跟踪国际轨迹

Webhooks

除了轮询，你也可以在门户 订阅履约事件。与本流程相关的现有事件：

事件类型触发时机
package.received国内包裹在仓库收货
package.exception入库包裹异常
consolidation.completed包裹已合箱待出库
shipment.created国际发货单已创建
shipment.dispatched发货单已交承运商
shipment.delivered已送达收件人
shipment.exception出库异常
balance.low钱包余额低于阈值

目前没有「可支付」事件。是否可支付请按上文从发货单详情判断。

推荐模式：

HIOBuy 仓库
        ↓
Webhook（package.received / shipment.dispatched / …）
        ↓
你的系统
        ↓
查询发货单详情
        ↓
业务逻辑 → 支付 / 通知客户

沙箱资源不会自动推送 webhook，请使用门户的 Send test。完整事件目录、签名校验与重试见 Webhooks。

测试物流渠道

WH-DEV 返回的物流渠道主要用于集成测试：

  • 运费报价对接
  • 渠道选择
  • 创建发货单
  • 结算流程测试
  • 轨迹流程测试

不要把 WH-DEV 的物流渠道数据当作生产物流规格。测试仓库中的渠道名称、价格、时效、清关模式、税费模式与尾程服务都不构成商业承诺。生产渠道在价格、服务范围、清关模式、税则、限制与投递要求上可能不同。

物流渠道规则 — 即将上线

Coming soon

HIOBuy 计划开放更完整的渠道规则，便于应用自动选线：服务范围、目的地覆盖、投递方式、尾程派送、计费规则、预计时效、清关模式、税费模式（DDP / DAP / DDU）、是否含税含关、商品限制、重量与尺寸限制。

这些字段与接口尚未上线，当前请按运费报价已文档化的响应结构开发。

相关文档

获取支持

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

发送邮件