サンドボックス環境とフィクスチャ
対象：
https://api.hiobuy.com（Workers ゲートウェイ）向け統合 — ベース URL は 本番と同一。
認証： 決定論フィクスチャは hio_test_* プレフィックスの API キー（key_type: test）に のみ 適用されます。hio_live_* 本番キー はこのページのルールを 一切 使用せず、常に通常どおり upstream マーケットプレイスにアクセスします。
関連ドキュメント：Authentication · Response format · Errors · Rate limits · Products · Orders · Webhooks
Public API カバレッジ（概要）
| 領域 | サンドボックス |
|---|---|
| グローバル | response_format: upstream 拒否（standard のみ）。currency ボディフィールドは prod と同様 拒否。sandbox_trigger は test キーで 許可（プラットフォームフィクスチャ）。Channel OAuth は hio_test_* で 認可済みとして扱う。クォータと rate limits は test キーでスキップ。 |
/v1/products/* | Search、detail、parse、upload-image、search-by-image、freight estimate、batch-check、1688 analytics エンドポイントは下記どおり モック。本サイト handoff セット外の OpenAPI-only 拡張は モックなし。 |
/v1/orders/* | Preview、create、detail、pay、cancel、logistics trace、list、purchase query を magic / dynamic id で モック。 |
/v1/fulfillment/* | ゲートウェイでは現時点 モックなし — サンドボックスでは利用不可として扱う。 |
| Webhooks | サンドボックス注文は webhooks を 送信しない。 |
設計目標
| 目標 | 意味 |
|---|---|
| 再現性 | 同一リクエスト → 同一レスポンス（結果にランダム性なし）。 |
| 文書化 | 各シナリオに、このページで grep できる安定 id または keyword。 |
| 契約整合 | JSON は本番 standard スキーマフィールドに一致；値は異なる。 |
| デフォルト happy path | 未知 id は汎用成功モックにフォールバック。 |
| 明示的失敗 | sb_* id または 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。フィクスチャ意図がない限り、実 upstream id に sb_ を 付けない。
2 層の失敗
トランスポート/API エラー と HTTP 200 ビジネス状態 を区別：
- API 失敗 → HTTP 4xx/5xx +
error.code（例：NOT_FOUND、PAYMENT_DECLINED）。 - HTTP 200 と状態 → 例：
variants[].stock = 0、status: wait_payment。
商品フィクスチャ（概要）
POST /v1/products/detail
Product detail を参照。サンドボックスでは upstream 形式 非対応。
product_id、解析済み url、mi_id、tao_password が sb_* id に解決されるとトリガー。
| Fixture id | 結果 | HTTP |
|---|---|---|
（非 sb_ の任意 id） | 標準モック商品 | 200 |
sb_prod_not_found | NOT_FOUND | 404 |
sb_prod_offline | PRODUCT_UNAVAILABLE | 422 |
sb_prod_no_stock | Detail ok、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 / 価格フィルターは 受理されるがモック行では無視。
keyword（完全一致） | 結果 |
|---|---|
| 通常テキスト | ヒット付きモックリスト |
sb_search_empty | items: []、total: 0 |
sb_search_not_found | 空のエイリアス |
Parse / upload-image / search-by-image / freight / analytics
| Endpoint | サンドボックス注記 |
|---|---|
| Parse URL | sb_* を含む URL query/path は detail 動作を再現。 |
| Upload image | 検証通過後、常に { "image_id": "img_sandbox_mock" }。 |
| Image search | 任意 keyword: sb_search_empty で空リスト；フローテストは upload-image と組み合わせ。 |
| Advanced — freight estimate | デフォルト国内送料モック 800 minor units、preview と整合。 |
| Advanced — batch-check | mock mpProducts 付き upstream 形式 envelope；除外リストには mi_id/item_id に sb_prod_not_found。 |
| Advanced — top keywords/list / daily-sales-trend | 文書化箇所で category_id / rank_id に sb_search_empty で空リストまたは 404 detail。 |
注文・決済フィクスチャ（magic id）
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 in progress） | — |
sb_ord_not_found | — | 404 |
POST /v1/orders/pay
order_id | 結果 | HTTP |
|---|---|---|
sb_ord_unpaid | 決済成功 → 論理的 paid 状態 | 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 は固定の illustrative 合計（サンプル行 ~4500 + 送料 ~800 minor units）。Create は sbo_* プレフィックスの動的 order_id をサンドボックス storage に永続化 — offer_id: sb_prod_offline / sb_prod_no_stock の行は本番セマンティクスどおり 422。
Cancel / logistics / list / purchase query
cancel、trace、detail list に従い：未払い sb_ord_* と動的未払い sbo_* はキャンセル可；paid/shipped 等フィクスチャは ORDER_NOT_CANCELLABLE。Logistics は sb_ord_shipped / completed モックで packages；unpaid/paid-await-shipment は packages: []。購入者リストは空モックで product_name: sb_ord_list_empty を尊重。Purchase query は upstream envelope を返す；not-found 用 pseudo id は適宜省略。
プラットフォームトリガー：sandbox_trigger
hio_test_* に のみ 許可；本番キーはフィールドを静かに無視。
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 |
現実的な body が検証を通るよう、無害 id と組み合わせ：
{
"channel": "1688",
"product_id": "123456",
"language": "en",
"sandbox_trigger": "sb_plat_quota_exceeded"
}トリガーと組み合わせた特殊 auth フィクスチャ sb_auth_channel_required は、通常の「デフォルト認可済み」ルールにもかかわらず UI 回帰用に CHANNEL_AUTH_REQUIRED（403）を返せる。
実装状況スナップショット
| フェーズ | カバレッジ | 備考 |
|---|---|---|
| Shipped | 上記 Product + procurement API | 本サイト公開 Public API 部分集合を反映。 |
| Not yet | 完全 /v1/fulfillment/*、webhooks、未公開 OpenAPI-only ルート | 告知までサンドボックス CI では依存しない。 |
クイックコピーチートシート
sb_prod_not_found → 404 product missing
sb_prod_offline → 422 unavailable
sb_prod_no_stock → 200 detail with zero stock
sb_search_empty → empty search/items
sb_ord_list_empty → empty buyer order list filter
img_sandbox_mock → stable upload-image id
sb_ord_unpaid → detail wait_payment • pay succeeds • cancel ok
sb_ord_pay_declined → pay 402 PAYMENT_DECLINED
sb_ord_paid → pay 409 ALREADY_PAID • trace maybe empty until shipped fixtures
sb_ord_shipped → detail wait_receive • trace populated
sb_ord_cancelled → cancelled state • pay conflicts
sb_plat_quota_exceeded → sandbox_trigger → 429 QUOTA_EXCEEDED内部でフィクスチャ追加時は、この番号体系を回帰テストに反映 — モック内の standard JSON 形状は 決して 変更しない。