サンドボックス環境とフィクスチャ

対象： https://api.hiobuy.com（Workers ゲートウェイ）向け統合 — ベース URL は 本番と同一。

プラン： 無料プランにはセルフサービスのドキュメントと Sandbox アクセスが含まれます。専任のインテグレーションおよびフルフィルメントサポートは有料プランで利用できます。

認証： 決定論フィクスチャは hio_test_* プレフィックスの API キー（key_type: test）に のみ 適用されます。hio_live_* 本番キー はこのページのルールを 一切 使用せず、常に通常どおり upstream マーケットプレイス / 倉庫にアクセスします。

関連ドキュメント：Authentication · Response format · Errors · Rate limits · Products · Orders · Fulfillment · Webhooks

Public API カバレッジ（概要）

設計目標

命名：sb_{domain}_{scenario}

文字：[a-z0-9_]、長さ ≤ ~48。フィクスチャ意図がない限り、実 upstream id に sb_ を 付けない。一部の fulfillment リソースは非 sb_ の安定 id（ret_*、ucp_*、svc_*、tkt_*、inv_*）も使用します。

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 形式 非対応。

id, product_id、解析済み url、mi_id、tao_password が sb_* id に解決されるとトリガー。

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

POST /v1/products/search

channel、keyword、page、page_size、language が適用。1688 の filter / sort / 価格フィルターは 受理されるがモック行では無視。

Parse / upload-image / search-by-image / freight / analytics

注文・決済フィクスチャ（magic id）

POST /v1/orders/detail

POST /v1/orders/pay

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 は適宜省略。

Fulfillment フィクスチャ

注記： 以下のフィクスチャは Sandbox API テスト専用です。アプリの WH-DEV 倉庫設定を表しません。WH-DEV テストには Production API キー（hio_live_*）を使用してください。

下記の全エンドポイントには hio_test_* キーが必要です。create からの動的 id（pkg_*、sbs_*、sbi_*、…）はキー単位でサンドボックス storage に永続化されます。

Balance · quotes · locations · VAS catalog

Shipments

Live warehouse Public id is the numeric PK as a string (e.g. "115"); order_sn is the warehouse order number. Sandbox create returns sbs_*; fixtures below use sb_shp_*.

List path: GET /v1/fulfillment/shipments. Tracking path: GET /v1/fulfillment/shipments/{id}/tracking (language query).

Inbounds（create / cancel）

Create は動的 package_id（pkg_*）を返します — 別途の inbound_id は ありません。

Packages · tracking · list

Unclaimed packages

Returns

Service requests

Finance（transactions / invoices）

Fulfillment finance を参照。

サポートチケットフィクスチャ

Support tickets を参照。

プラットフォームトリガー：sandbox_trigger

hio_test_* に のみ 許可；本番キーはフィールドを静かに無視。

現実的な body が検証を通るよう、無害 id と組み合わせ：

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

トリガーと組み合わせた特殊 auth フィクスチャ sb_auth_channel_required は、通常の「デフォルト認可済み」ルールにもかかわらず UI 回帰用に CHANNEL_AUTH_REQUIRED（403）を返せる。

実装状況スナップショット

クイックコピーチートシート

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_shp_unpaid / sb_shp_shipped / sb_shp_signed / sb_shp_intercepted → shipment list / detail / intercept
sb_pkg_received / sb_pkg_shipped → package detail / fulfillment timeline
sb_inbound_exists          → inbound create 409 tracking exists
ret_pending_001            → return confirm happy path
ucp_01K2ABCDEF1234567890   → unclaimed claimable
svc_photo_completed        → VAS request completed
tkt_01K2ABCDEF1234567890   → support ticket open

sb_plat_quota_exceeded     → sandbox_trigger → 429 QUOTA_EXCEEDED

内部でフィクスチャ追加時は、この番号体系を回帰テストに反映 — モック内の standard JSON 形状は 決して 変更しない。