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 upstream normalement.
Docs associées : Authentication · Response format · Errors · Rate limits · Products · Orders · Webhooks
Couverture Public API (résumé)
| Domaine | Sandbox |
|---|---|
| Global | response_format: upstream rejeté (standard uniquement). Champ currency dans le corps rejeté comme en prod. sandbox_trigger autorisé pour les clés test (fixtures plateforme). OAuth canal traité comme autorisé pour hio_test_*. Quotas et rate limits ignorés pour les clés test. |
/v1/products/* | Search, detail, parse, upload-image, search-by-image, freight estimate, batch-check, analytics 1688 mockés comme documenté ci-dessous. Extensions OpenAPI-only hors du jeu handoff de ce site non mockées. |
/v1/orders/* | Preview, create, detail, pay, cancel, logistics trace, list, purchase query mockés avec magic / dynamic ids. |
/v1/fulfillment/* | Non mockés dans la passerelle aujourd’hui — considérez comme indisponible en sandbox. |
| Webhooks | Les commandes sandbox n’émettent pas de webhooks. |
Objectifs de conception
| Objectif | Signification |
|---|---|
| Reproductible | Même requête → même réponse (aucune aléatoire dans les résultats). |
| Documenté | Chaque scénario a un id ou keyword stable à rechercher sur cette page. |
| Aligné sur le contrat | JSON conforme aux champs du schéma standard de production ; valeurs différentes. |
| Happy path par défaut | Les ids inconnus retombent sur des mocks de succès génériques. |
| Échec explicite | Utilisez les ids sb_* ou sandbox_trigger pour forcer erreurs / états limites. |
Nommage : sb_{domain}_{scenario}
| Segment | Règle | Exemples |
|---|---|---|
| Préfixe | Toujours sb_ | sb_prod_not_found |
domain | Nom en minuscules (prod, search, ord, plat, auth, …) | — |
scenario | snake_case | not_found, pay_declined |
Caractères : [a-z0-9_], longueur ≤ ~48. Ne préfixez pas les vrais ids upstream avec sb_ sauf si vous voulez la fixture.
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 product_id, url parsée, mi_id ou tao_password se résout en id sb_*.
| Fixture id | Résultat | HTTP |
|---|---|---|
(tout id non-sb_) | Produit mock standard | 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 s’appliquent. Filtres 1688 filter / sort / prix acceptés mais ignorés pour les lignes mock.
keyword (exact) | Résultat |
|---|---|
| texte ordinaire | Liste mock avec résultats |
sb_search_empty | items: [], total: 0 |
sb_search_not_found | Alias du vide |
Parse / upload-image / search-by-image / freight / analytics
| Endpoint | Note sandbox |
|---|---|
| Parse URL | Query/path URL contenant sb_* reproduit le comportement detail. |
| Upload image | Toujours { "image_id": "img_sandbox_mock" } après validations réussies. |
| Image search | keyword: sb_search_empty optionnel donne une liste vide ; associez à upload-image pour les tests de flux. |
| Advanced — freight estimate | Mock fret domestique par défaut 800 minor units aligné avec preview. |
| Advanced — batch-check | Retourne une enveloppe style upstream avec mock mpProducts ; utilisez sb_prod_not_found dans mi_id/item_id pour les listes d’exclusion. |
| Advanced — top keywords/list / daily-sales-trend | Utilisez sb_search_empty sur category_id / rank_id où documenté pour listes vides ou cas 404 detail. |
Fixtures commandes et paiement (magic ids)
POST /v1/orders/detail
order_id | status typique | Notes |
|---|---|---|
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 | Résultat | HTTP |
|---|---|---|
sb_ord_unpaid | Paiement réussi → état logique 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 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.
Déclencheurs plateforme : sandbox_trigger
Autorisé uniquement sur hio_test_* ; les clés production ignorent le champ silencieusement.
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 |
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
| Phase | Couverture | Notes |
|---|---|---|
| Shipped | Product + procurement APIs ci-dessus | Reflète le sous-ensemble Public API publié sur ce site. |
| Not yet | /v1/fulfillment/* complet, webhooks, routes OpenAPI-only non publiées | Ne vous y fiez pas en CI sandbox tant que non annoncé. |
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_plat_quota_exceeded → sandbox_trigger → 429 QUOTA_EXCEEDEDLorsque 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.