沙箱环境与测试 Fixture

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

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

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

Public API 覆盖（摘要）

域	沙箱行为
全局	`response_format: upstream` 拒绝（仅 `standard`）。`currency` 与生产一致会拒绝。`sandbox_trigger` 仅在 test key 下生效。test key 下层级 OAuth 默认视为已授权。配额 / 每分钟限流对 test key 跳过。
*`/v1/products/`**	搜索、详情、解析、上图、图搜、国内运费、`batch-check`、1688 分析类下文所述端点有 Mock。未在本站正文覆盖的 OpenAPI 扩展路由暂不 Mock。
*`/v1/orders/`**	Preview、Create、Detail、Pay、Cancel、物流、列表、`purchase/query` 有 Mock（含 Magic `sb_ord_` 与动态 `sbo_`）。
*`/v1/fulfillment/`**	网关当前不做 Mock，请视为沙箱不可用。
Webhooks	沙箱产生的订单不发 Webhook。

设计目标

目标	含义
可重复	固定输入 ⇒ 固定输出（结果无随机漂移）。
可检索	每个场景有可稳定拷贝的 ID / keyword。
契约对齐	字段层级与生产 `standard` 一致；值不同。
默认走 happy path	未匹配的普通 ID 仍可得到通用 Mock 成功体。
显式失败	`sb_*` 或 `sandbox_trigger` 专门诱导错误态。

命名：`sb_{domain}_{scenario}`

段	规则	例
前缀	固定 `sb_`	`sb_prod_not_found`
`domain`	小写英文名（资源域）	`prod`、`search`、`ord`、`plat`、`auth`
`scenario`	`snake_case`	`not_found`、`pay_declined`

字符 [a-z0-9_]，长度建议 ≤ 48。勿在非测试场景冒充 sb_*，以免误触发。

两类失败形态

需区分：

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

商品域 Fixture（摘要）

`POST /v1/products/detail`

见商品详情。沙箱 不支持 response_format: upstream。

当 product_id、可从 url 解析的 ID、mi_id、tao_password 命中 sb_* 时触发下表：

Fixture id	结果	HTTP
(任意不含 `sb_` 的普通 id)	标准 Mock 商品	200
`sb_prod_not_found`	`NOT_FOUND`	404
`sb_prod_offline`	`PRODUCT_UNAVAILABLE`	422
`sb_prod_no_stock`	详情成功，`stock: 0`	200

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":"en"}'

`POST /v1/products/search`

channel、keyword、page、page_size、language 生效。1688 filter、sort、price_* 接受但不改变 Mock 行集。

`keyword`（完全匹配）	行为
普通检索词	有数据的 Mock 列表
`sb_search_empty`	`items: []`，`total: 0`
`sb_search_not_found`	与上一行别名，便于语义化用例

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

端点	沙箱摘要
链接解析	URL 中带 `sb_` 时对齐 detail* 的 404/422/库存语义。
上传商品图	校验通过后恒返回 `{ "image_id": "img_sandbox_mock" }`。
以图搜	可传 `keyword: sb_search_empty`；推荐 `prepare-upload → search-by-image` 串起来测。
高级——国内运费估算	默认运价 Mock 800 分，与 Preview 对齐。
高级——batch-check	上游信封；在 `mi_id`/`item_id` 中用 `sb_prod_not_found` 进入未映射列表。
高级——热词 / 榜单 / 日销趋势	依文档在 `category_id` / `rank_id` / `product_id` 上可用 `sb_search_empty`、`sb_prod_not_found` 快速拿空列表 / 404。

订单与支付：`sb_ord_*` 魔法单号

`POST /v1/orders/detail`

`order_id`	典型 `status`	备注
`sb_ord_unpaid`	`wait_payment`	—
`sb_ord_paid`	`wait_shipment`	—
`sb_ord_shipped`	`wait_receive`	—
`sb_ord_completed`	`completed`	—
`sb_ord_cancelled`	`cancelled`	—
`sb_ord_refunding`	`wait_shipment`（`refund_status` 退款中）	—
`sb_ord_not_found`	—	404

`POST /v1/orders/pay`

`order_id`	结果	HTTP
`sb_ord_unpaid`	支付逻辑成功 ⇒ 视作已支付	200
`sb_ord_pay_declined`	`PAYMENT_DECLINED`	402
`sb_ord_pay_insufficient`	`PAYMENT_INSUFFICIENT_FUNDS`	402
`sb_ord_paid`	`ORDER_ALREADY_PAID`	409
`sb_ord_cancelled`	`ORDER_CANCELLED`	409
`sb_ord_upstream_timeout`	`CHANNEL_UPSTREAM_ERROR`	502

Preview / Create

Preview 给出稳定示例计价（SKU 示范价约 4500 分，国内快递 800 分，单位与下文「分」对齐）。Create 返回动态 order_id，前缀常为 sbo_*（沙箱会话内落库）；offer_id: sb_prod_offline / sb_prod_no_stock 仍可触发 422 与上游语义一致的商品拒绝。

取消 / 国内物流 / 列表 / Purchase query

对齐取消、国内物流、详情与列表：未支付 sb_ord_* 与本 App 的动态 sbo_* 可撤销；已支付等在途 Fixture 会得到 ORDER_NOT_CANCELLABLE。sb_ord_shipped / sb_ord_completed 在物流字段里含 Mock 路由；未到发货态常为 packages: []。买家列表可把 product_name: sb_ord_list_empty。purchase/query 仍为上 upstream 信封（非 standard）。

`sandbox_trigger`（平台维度）

仅在 hio_test_*；生产 key 忽略字段。

`sandbox_trigger`	HTTP	`error.code`
`sb_plat_quota_exceeded`	429	`QUOTA_EXCEEDED`
`sb_plat_rate_limited`	429	`RATE_LIMIT_EXCEEDED`
`sb_plat_upstream_error`	502	`CHANNEL_UPSTREAM_ERROR`

常与「看起来正常」的请求体拼装在一起：

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

若需校验 403 CHANNEL_AUTH_REQUIRED 的 UX，可走专用 Fixture sb_auth_channel_required 与上文触发组合——尽管常规沙箱为方便测商品链路 默认已授权。

实现快照

Phase	范围	备注
已就绪	本文列出的商品 + 代购子集	与官网 Public 文档对齐。
未就绪	全部 `/v1/fulfillment/*`、Webhook、未收录的私有扩展路由	勿在未公告前在生产/沙箱 QA 流水线强依赖它们。

速查（复制）

sb_prod_not_found          → 404 不存在
sb_prod_offline            → 422 下架不可用
sb_prod_no_stock           → 200 stock=0

sb_search_empty / sb_search_not_found → 搜索空列表
img_sandbox_mock               → upload-image 固定 ID

sb_ord_unpaid              → unpaid · pay OK · cancel OK
sb_ord_pay_declined        → pay 402
sb_ord_paid / shipped …    → pay / logistics 分支态
sb_ord_not_found           → 404 detail

sb_plat_quota_exceeded     → sandbox_trigger 429

若你在内部新增 Fixture：不要改写 standard 外层的字段树；新增的 error.code 也请同步本站 Errors 与消费者 SDK。