Sandbox-Umgebung und Fixtures

Zielgruppe: Integrationen gegen https://api.hiobuy.com (Workers-Gateway) — dieselbe Basis-URL wie in Production.

Auth: Deterministische Fixtures gelten nur für API-Schlüssel mit Präfix hio_test_* (key_type: test). hio_live_* Production-Schlüssel beachten nie die Regeln dieser Seite — sie rufen Upstream-Marktplätze / Warehouses stets normal auf.

Verwandte Docs: Authentication · Response format · Errors · Rate limits · Products · Orders · Fulfillment · Webhooks

Public-API-Abdeckung (Überblick)

Designziele

Benennung: sb_{domain}_{scenario}

Zeichen: [a-z0-9_], Länge ≤ ~48. Nicht echte Upstream-IDs mit sb_ präfixen, es sei denn, Sie wollen die Fixture. Einige Fulfillment-Ressourcen nutzen auch stabile Nicht-sb_-IDs (ret_*, ucp_*, svc_*, tkt_*, inv_*).

Zwei Fehlerschichten

Unterscheiden Sie Transport-/API-Fehler von HTTP-200-Geschäftszuständen:

• API-Fehler → HTTP 4xx/5xx + error.code (z. B. NOT_FOUND, PAYMENT_DECLINED).
• HTTP 200 mit Zustand → z. B. variants[].stock = 0, status: wait_payment.

Produkt-Fixtures (Überblick)

POST /v1/products/detail

Siehe Product detail. Format upstream in Sandbox nicht unterstützt.

Auslöser, wenn id, product_id, geparste url, mi_id oder tao_password zu einer sb_*-ID aufgelöst wird.

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 gelten. 1688 filter / sort / Preisfilter akzeptiert, aber für Mock-Zeilen ignoriert.

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

Bestell- und Zahlungs-Fixtures (Magic-IDs)

POST /v1/orders/detail

POST /v1/orders/pay

Preview / create

Preview liefert feste illustrative Summen (Beispielzeile ~4500 + Fracht ~800 in Minor Units). Create erzeugt dynamische order_id-Werte mit Präfix sbo_*, persistiert in Sandbox-Storage — Zeilen mit offer_id: sb_prod_offline / sb_prod_no_stock liefern 422 wie Production-Semantik.

Cancel / logistics / list / purchase query

Laut cancel, trace, detail list: unbezahlte sb_ord_* und dynamische unbezahlte sbo_* stornierbar; Paid/Shipped/etc.-Fixtures liefern ORDER_NOT_CANCELLABLE. Logistics liefert Packages für sb_ord_shipped / completed-Mocks; unpaid/paid-await-shipment liefern packages: []. Käuferliste respektiert product_name: sb_ord_list_empty für leere Mocks. Purchase query liefert Upstream-Envelopes; omitieren Sie entsprechend not-found-Pseudo-IDs.

Fulfillment-Fixtures

Hinweis: Die Fixtures unten gelten nur für Sandbox-API-Tests. Sie repräsentieren nicht die WH-DEV-Lagerkonfiguration Ihrer Anwendung. Für WH-DEV-Tests verwenden Sie einen Production API Key (hio_live_*).

Alle Endpunkte unten erfordern einen hio_test_*-Schlüssel. Dynamische IDs aus Create (pkg_*, sbs_*, sbi_*, …) werden in der Sandbox-Storage für den Schlüssel persistiert.

Balance · Quotes · Locations · VAS-Katalog

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 liefert dynamische package_id (pkg_*) — es gibt keine separate inbound_id.

Packages · Tracking · List

Unclaimed packages

Returns

Service requests

Finance (transactions / invoices)

Siehe Fulfillment finance.

Support-Ticket-Fixtures

Siehe Support tickets.

Plattform-Trigger: sandbox_trigger

Nur auf hio_test_* erlaubt; Production-Schlüssel ignorieren das Feld still.

Mit harmlosen IDs kombinieren, damit realistische Bodies validieren:

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

Spezielle Auth-Fixture sb_auth_channel_required mit Triggern kann CHANNEL_AUTH_REQUIRED (403) für UI-Regressionen erzeugen trotz der Regel „authorized by default“.

Implementierungsstatus (Snapshot)

Kurz-Spickzettel

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

Beim internen Hinzufügen von Fixtures dieses Nummerierungsschema in Regressionstests spiegeln — niemals standard-JSON-Formen in Mocks verändern.