沙箱环境与测试 Fixture

适用范围：接入 https://api.hiobuy.com（Workers 网关）的集成。Base URL 与生产相同。

套餐： 免费套餐包含自助文档与 Sandbox 访问。专属对接与履约支持在付费套餐中提供。

鉴权： 仅前缀为 hio_test_* 的密钥（key_type: test）会套用本文 Fixture 规则。hio_live_* 生产密钥不适用本页的任何说明，一律走真实上游（市场 / 仓配）。

相关：鉴权 · 响应结构 · 错误 · 限流 · 商品 · 订单 · 履约 · Webhook

Public API 覆盖（摘要）

设计目标

命名：sb_{domain}_{scenario}

字符集：[a-z0-9_]，长度 ≤ ~48。非故意触发时勿给真实上游 ID 加 sb_ 前缀。履约另有稳定非 sb_ ID（ret_*、ucp_*、svc_*、tkt_*、inv_*）。

两层失败模型

区分 传输 / API 错误 与 HTTP 200 业务态：

• API 失败 → HTTP 4xx/5xx + error.code（如 NOT_FOUND、PAYMENT_DECLINED）。
• HTTP 200 业务态 → 如 variants[].stock = 0、status: wait_payment。

商品 Fixture（摘要）

POST /v1/products/detail

见 商品详情。沙箱 不支持 upstream 格式。

当 id、product_id、解析出的 url、mi_id 或 tao_password 解析为 sb_* 时触发。

curl https://api.hiobuy.com/v1/products/detail \
  -H "Authorization: Bearer hio_test_..." \
  -H "Content-Type: application/json" \
  -d '{"channel":"1688","product_id":"sb_prod_not_found","language":"zh"}'

POST /v1/products/search

channel、keyword、page、page_size、language 生效。1688 的 filter / sort / 价格筛选 接受但忽略（仍返回 Mock 列表）。

解析 / 上图 / 图搜 / 运费 / 分析

订单与支付 Fixture（Magic ID）

POST /v1/orders/detail

POST /v1/orders/pay

Preview / Create

预览 返回固定示例合计（行约 4500 + 运费约 800 分）。创建 生成动态 sbo_* 订单写入沙箱存储；行级 offer_id: sb_prod_offline / sb_prod_no_stock 返回 422（语义同生产）。

Cancel / 物流 / 列表 / 采购查询

见 取消、轨迹、详情 / 列表：待支付 sb_ord_* 与动态 sbo_* 可取消；已支付 / 已发货等返回 ORDER_NOT_CANCELLABLE。物流对 sb_ord_shipped / completed 有运单；待支付 / 待发货为 packages: []。买家列表可用 product_name: sb_ord_list_empty 得空列表。采购查询 返回上游风格 envelope。

履约 Fixture

说明： 下列 Fixture 仅用于 Sandbox API 测试，不代表您应用的 WH-DEV 仓库配置。WH-DEV 测试请使用 Production API Key（hio_live_*）。

以下端点均需 hio_test_*。创建产生的动态 ID（pkg_*、sbs_*、sbi_*…）会按密钥持久化在沙箱存储中。

余额 · 报价 · 仓点 · VAS 目录

运输单 Shipments

Live 仓库 Public id 为数字主键字符串（如 "115"）；order_sn 为仓库单号。沙箱创单返回 sbs_*；下表 Fixture 使用 sb_shp_*。

列表路径：GET /v1/fulfillment/shipments。轨迹路径：GET /v1/fulfillment/shipments/{id}/tracking（language query）。

入库预报（create / cancel）

创建返回动态 package_id（pkg_*）——没有单独的 inbound_id。

包裹 · 轨迹 · 列表

无人认领包裹

退运 Returns

服务请求 Service requests

财务（流水 / 发票）

见 履约财务。

工单 Fixture

见 支持工单。

平台触发：sandbox_trigger

仅 hio_test_* 生效；生产密钥静默忽略该字段。

可与普通合法 ID 组合，使 body 仍能通过校验：

{
  "channel": "1688",
  "product_id": "123456",
  "language": "zh",
  "sandbox_trigger": "sb_plat_quota_exceeded"
}

特殊鉴权 Fixture sb_auth_channel_required 搭配 trigger 可产生 CHANNEL_AUTH_REQUIRED（403），用于 UI 回归（尽管沙箱默认已授权）。

实现状态快照

快速对照（复制用）

sb_prod_not_found          → 404 商品不存在
sb_prod_offline            → 422 下架
sb_prod_no_stock           → 200 库存为 0

sb_search_empty            → 搜索空结果
sb_ord_list_empty          → 买家订单列表为空
img_sandbox_mock           → upload-image 固定 ID

sb_ord_unpaid              → detail 待支付 · pay 成功 · cancel 可
sb_ord_pay_declined        → pay 402 PAYMENT_DECLINED
sb_ord_paid                → pay 409 ALREADY_PAID · 未发货轨迹可能为空
sb_ord_shipped             → detail 待收货 · 有轨迹
sb_ord_cancelled           → 已取消 · pay 冲突

sb_shp_unpaid / sb_shp_shipped / sb_shp_signed / sb_shp_intercepted → 发货单列表 / 详情 / 拦截
sb_pkg_received / sb_pkg_shipped → 包裹详情 / 履约时间线
sb_inbound_exists          → 入库 create 409 单号已存在
ret_pending_001            → 退运 Confirm 成功路径
ucp_01K2ABCDEF1234567890   → 无人认领可认领
svc_photo_completed        → VAS 请求已完成
tkt_01K2ABCDEF1234567890   → 工单进行中

sb_plat_quota_exceeded     → sandbox_trigger → 429 QUOTA_EXCEEDED

内部新增 Fixture 时请沿用本编号体系做回归 — 切勿在 Mock 中改动 standard JSON 结构。