Environnement sandbox et fixtures

Public : intégrations déployées contre https://api.hiobuy.com (passerelle Workers) — même URL de base qu’en production.

Auth : les fixtures déterministes s’appliquent uniquement aux clés API préfixées par hio_test_* (key_type: test). Les clés production hio_live_* n’utilisent jamais les règles de cette page — elles accèdent toujours aux marketplaces / entrepôts upstream normalement.

Docs associées : Authentication · Response format · Errors · Rate limits · Products · Orders · Fulfillment · Webhooks

Couverture Public API (résumé)

Objectifs de conception

Nommage : sb_{domain}_{scenario}

Caractères : [a-z0-9_], longueur ≤ ~48. Ne préfixez pas les vrais ids upstream avec sb_ sauf si vous voulez la fixture. Certaines ressources fulfillment utilisent aussi des ids stables hors sb_ (ret_*, ucp_*, svc_*, tkt_*, inv_*).

Deux niveaux d’échec

Distinguez erreurs transport/API et états métier en HTTP 200 :

• Échec API → HTTP 4xx/5xx + error.code (ex. NOT_FOUND, PAYMENT_DECLINED).
• HTTP 200 avec état → ex. variants[].stock = 0, status: wait_payment.

Fixtures produits (vue d’ensemble)

POST /v1/products/detail

Voir Product detail. Le format upstream est non pris en charge en sandbox.

Déclenché quand id, product_id, url parsée, mi_id ou tao_password se résout en id sb_*.

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 s’appliquent. Filtres 1688 filter / sort / prix acceptés mais ignorés pour les lignes mock.

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

Fixtures commandes et paiement (magic ids)

POST /v1/orders/detail

POST /v1/orders/pay

Preview / create

Preview retourne des totaux illustratifs fixes (ligne exemple ~4500 + fret ~800 en minor units). Create émet des order_id dynamiques préfixés sbo_* persistés en sandbox storage — les lignes référençant offer_id: sb_prod_offline / sb_prod_no_stock retournent 422 comme en production.

Cancel / logistics / list / purchase query

Selon cancel, trace, detail list : sb_ord_* impayés et sbo_* dynamiques impayés s’annulent ; fixtures paid/shipped/etc. retournent ORDER_NOT_CANCELLABLE. Logistics retourne packages pour mocks sb_ord_shipped / completed ; unpaid/paid-await-shipment retournent packages: []. La liste acheteur respecte product_name: sb_ord_list_empty pour mocks vides. Purchase query retourne des enveloppes upstream ; omettez les pseudo-ids not-found en conséquence.

Fixtures fulfillment

Note : les fixtures ci-dessous servent uniquement aux tests Sandbox API. Elles ne représentent pas la configuration WH-DEV de votre application. Pour les tests WH-DEV, utilisez une Production API key (hio_live_*).

Tous les endpoints ci-dessous exigent une clé hio_test_*. Les ids dynamiques issus de create (pkg_*, sbs_*, sbi_*, …) sont persistés en sandbox storage pour la clé.

Balance · quotes · locations · catalogue VAS

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 retourne un package_id dynamique (pkg_*) — il n’y a pas d’inbound_id séparée.

Packages · tracking · list

Unclaimed packages

Returns

Service requests

Finance (transactions / invoices)

Voir Fulfillment finance.

Fixtures tickets support

Voir Support tickets.

Déclencheurs plateforme : sandbox_trigger

Autorisé uniquement sur hio_test_* ; les clés production ignorent le champ silencieusement.

Combinez avec des ids bénins pour que les corps réalistes passent la validation :

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

La fixture auth spéciale sb_auth_channel_required associée aux triggers peut produire CHANNEL_AUTH_REQUIRED (403) pour les régressions UI malgré la règle « authorized by default ».

Instantané du statut d’implémentation

Aide-mémoire rapide

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

Lorsque vous ajoutez des fixtures en interne, reproduisez ce schéma de numérotation dans les tests de régression — ne modifiez jamais les formes JSON standard dans les mocks.