Sandbox environment & fixtures

Audience: integrations that ship against https://api.hiobuy.com (Workers gateway) — same base URL as production.

Plans: Free plans include self-service documentation and Sandbox access. Dedicated integration and fulfillment support are available on paid plans.

Auth: deterministic fixtures apply only to API keys prefixed with hio_test_* (key_type: test). hio_live_* production keys never read this page’s rules — they always hit upstream marketplaces / warehouses normally.

Related docs: Authentication · Response format · Errors · Rate limits · Products · Orders · Fulfillment · Webhooks

Public API coverage (summary)

Design goals

Naming: sb_\{domain\}_\{scenario\}

Characters: [a-z0-9_], length ≤ ~48. Do not prefix real upstream ids with sb_ unless you intend the fixture. Some fulfillment resources also use stable non-sb_ ids (ret_*, ucp_*, svc_*, tkt_*, inv_*).

Two failure layers

Distinguish transport/API errors from HTTP 200 business states:

• API failure → HTTP 4xx/5xx + error.code (e.g. NOT_FOUND, PAYMENT_DECLINED).
• HTTP 200 with state → e.g. variants[].stock = 0, status: wait_payment.

Product fixtures (high level)

POST /v1/products/detail

See Product detail. upstream format is unsupported in sandbox.

Trigger when product_id, parsed url, mi_id, or tao_password resolves to a 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":"en"}'

POST /v1/products/search

channel, keyword, page, page_size, language apply. 1688 filter / sort / price filters are accepted but ignored for mock rows.

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

Order & payment fixtures (magic ids)

POST /v1/orders/detail

POST /v1/orders/pay

Preview / create

Preview returns fixed illustrative totals (sample line ~4500 + freight ~800 in minor units). Create emits dynamic order_id values prefixed sbo_* persisted in sandbox storage — lines referencing offer_id: sb_prod_offline / sb_prod_no_stock return 422 like production semantics.

Cancel / logistics / list / purchase query

Per cancel, trace, detail list: unpaid sb_ord_* and dynamic sbo_* unpaid orders cancel; paid/shipped/etc. fixtures return ORDER_NOT_CANCELLABLE. Logistics returns packages for sb_ord_shipped / completed mocks; unpaid/paid-await-shipment return packages: []. Buyer list respects product_name: sb_ord_list_empty for empty mocks. Purchase query returns upstream envelopes; omit not-found pseudo ids accordingly.

Fulfillment fixtures

Note: The fixtures below are for Sandbox API testing only. They do not represent your application’s WH-DEV warehouse configuration. For WH-DEV testing, use a Production API key (hio_live_*).

All endpoints below require a hio_test_* key. Dynamic ids from create (pkg_*, sbs_*, sbi_*, …) are persisted in sandbox storage for the key.

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 returns dynamic package_id (pkg_*) — there is no separate inbound_id.

Packages · tracking · list

Unclaimed packages

Returns

Service requests

Finance (transactions / invoices)

See Fulfillment finance.

Support ticket fixtures

See Support tickets.

Platform triggers: sandbox_trigger

Allowed only on hio_test_*; production keys ignore the field quietly.

Combine with benign ids so realistic bodies still validate:

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

Special auth fixture sb_auth_channel_required paired with triggers can produce CHANNEL_AUTH_REQUIRED (403) for UI regressions despite the normal “authorized by default” rule.

Implementation status snapshot

Quick copy cheat sheet

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

When you add fixtures internally, mirror this numbering scheme in regression tests — never mutate standard JSON shapes inside mocks.