Entorno sandbox y fixtures

Audiencia: integraciones desplegadas contra https://api.hiobuy.com (gateway Workers) — misma URL base que en producción.

Auth: las fixtures deterministas aplican solo a claves API con prefijo hio_test_* (key_type: test). Las claves de producción hio_live_* nunca usan las reglas de esta página — siempre acceden a los marketplaces / almacenes upstream con normalidad.

Documentación relacionada: Authentication · Response format · Errors · Rate limits · Products · Orders · Fulfillment · Webhooks

Cobertura Public API (resumen)

Objetivos de diseño

Nomenclatura: sb_{domain}_{scenario}

Caracteres: [a-z0-9_], longitud ≤ ~48. No prefije ids upstream reales con sb_ salvo que quiera la fixture. Algunos recursos de fulfillment también usan ids estables no-sb_ (ret_*, ucp_*, svc_*, tkt_*, inv_*).

Dos capas de fallo

Distinga errores de transporte/API de estados de negocio con HTTP 200:

• Fallo API → HTTP 4xx/5xx + error.code (p. ej. NOT_FOUND, PAYMENT_DECLINED).
• HTTP 200 con estado → p. ej. variants[].stock = 0, status: wait_payment.

Fixtures de productos (resumen)

POST /v1/products/detail

Vea Product detail. El formato upstream no está soportado en sandbox.

Se activa cuando id, product_id, url parseada, mi_id o tao_password se resuelve en un 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

Aplican channel, keyword, page, page_size, language. Filtros 1688 filter / sort / precio aceptados pero ignorados para filas mock.

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

Fixtures de pedidos y pago (magic ids)

POST /v1/orders/detail

POST /v1/orders/pay

Preview / create

Preview devuelve totales ilustrativos fijos (línea ejemplo ~4500 + flete ~800 en minor units). Create emite order_id dinámicos con prefijo sbo_* persistidos en sandbox storage — líneas con offer_id: sb_prod_offline / sb_prod_no_stock devuelven 422 como en producción.

Cancel / logistics / list / purchase query

Según cancel, trace, detail list: sb_ord_* impagados y sbo_* dinámicos impagados se cancelan; fixtures paid/shipped/etc. devuelven ORDER_NOT_CANCELLABLE. Logistics devuelve packages para mocks sb_ord_shipped / completed; unpaid/paid-await-shipment devuelven packages: []. La lista del comprador respeta product_name: sb_ord_list_empty para mocks vacíos. Purchase query devuelve sobres upstream; omita los pseudo ids not-found según corresponda.

Fixtures de fulfillment

Nota: las fixtures siguientes son solo para pruebas Sandbox API. No representan la configuración WH-DEV de su aplicación. Para pruebas WH-DEV, use una Production API key (hio_live_*).

Todos los endpoints siguientes requieren una clave hio_test_*. Los ids dinámicos de create (pkg_*, sbs_*, sbi_*, …) se persisten en sandbox storage para la clave.

Balance · quotes · locations · catálogo 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 devuelve un package_id dinámico (pkg_*) — no hay un inbound_id separado.

Packages · tracking · list

Unclaimed packages

Returns

Service requests

Finance (transactions / invoices)

Vea Fulfillment finance.

Fixtures de tickets de soporte

Vea Support tickets.

Triggers de plataforma: sandbox_trigger

Permitido solo en hio_test_*; las claves de producción ignoran el campo silenciosamente.

Combine con ids benignos para que cuerpos realistas pasen validación:

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

La fixture auth especial sb_auth_channel_required combinada con triggers puede producir CHANNEL_AUTH_REQUIRED (403) para regresiones UI pese a la regla «authorized by default».

Instantánea del estado de implementación

Hoja de referencia rápida

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

Al añadir fixtures internamente, refleje este esquema de numeración en pruebas de regresión — nunca mute las formas JSON standard dentro de los mocks.