Песочница и фикстуры

Аудитория: интеграции, работающие с https://api.hiobuy.com (шлюз Workers) — тот же базовый URL, что и в production.

Тарифы: В бесплатных тарифах доступны документация для самостоятельной работы и Sandbox. Выделенная поддержка по интеграции и фулфилменту доступна на платных тарифах.

Аутентификация: детерминированные фикстуры применяются только к API-ключам с префиксом hio_test_* (key_type: test). Production-ключи hio_live_* никогда не используют правила этой страницы — они всегда обращаются к upstream-маркетплейсам / складам в обычном режиме.

Связанные документы: Authentication · Response format · Errors · Rate limits · Products · Orders · Fulfillment · Webhooks

Покрытие Public API (кратко)

Цели проектирования

Именование: sb_{domain}_{scenario}

Символы: [a-z0-9_], длина ≤ ~48. Не добавляйте префикс sb_ к реальным upstream id, если не хотите сработать фикстуру. Некоторые ресурсы fulfillment также используют стабильные id без sb_ (ret_*, ucp_*, svc_*, tkt_*, inv_*).

Два уровня сбоев

Различайте транспортные/API-ошибки и бизнес-состояния при HTTP 200:

• Сбой API → HTTP 4xx/5xx + error.code (напр. NOT_FOUND, PAYMENT_DECLINED).
• HTTP 200 со состоянием → напр. variants[].stock = 0, status: wait_payment.

Фикстуры товаров (кратко)

POST /v1/products/detail

См. Product detail. Формат upstream в песочнице не поддерживается.

Срабатывает, когда id, product_id, разобранный url, mi_id или tao_password разрешается в 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. Фильтры 1688 filter / sort / price принимаются, но игнорируются для mock-строк.

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

Фикстуры заказов и оплаты (magic id)

POST /v1/orders/detail

POST /v1/orders/pay

Preview / create

Preview возвращает фиксированные иллюстративные итоги (пример строки ~4500 + freight ~800 в minor units). Create выдаёт динамические order_id с префиксом sbo_*, сохраняемые в sandbox storage — строки с offer_id: sb_prod_offline / sb_prod_no_stock возвращают 422, как в production.

Cancel / logistics / list / purchase query

По cancel, trace, detail list: неоплаченные sb_ord_* и динамические неоплаченные sbo_* отменяются; фикстуры paid/shipped и т.д. возвращают ORDER_NOT_CANCELLABLE. Logistics возвращает packages для mock sb_ord_shipped / completed; unpaid/paid-await-shipment возвращают packages: []. Список покупателя учитывает product_name: sb_ord_list_empty для пустых mock. Purchase query возвращает upstream envelopes; соответственно не используйте pseudo id для not-found.

Фикстуры fulfillment

Примечание: фикстуры ниже предназначены только для Sandbox API testing. Они не отражают WH-DEV warehouse configuration вашего приложения. Для WH-DEV testing используйте Production API key (hio_live_*).

Все эндпоинты ниже требуют ключ hio_test_*. Динамические id из create (pkg_*, sbs_*, sbi_*, …) сохраняются в sandbox storage для ключа.

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 возвращает динамический package_id (pkg_*) — отдельного inbound_id нет.

Packages · tracking · list

Unclaimed packages

Returns

Service requests

Finance (transactions / invoices)

См. Fulfillment finance.

Фикстуры support tickets

См. Support tickets.

Триггеры платформы: sandbox_trigger

Разрешён только на hio_test_*; production-ключи тихо игнорируют поле.

Комбинируйте с безопасными id, чтобы реалистичные тела проходили валидацию:

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

Специальная auth-фикстура sb_auth_channel_required, сочетаемая с триггерами, может давать CHANNEL_AUTH_REQUIRED (403) для UI-регрессий, несмотря на правило «authorized by default».

Снимок статуса реализации

Краткая шпаргалка

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

При добавлении фикстур внутри команды отражайте эту схему нумерации в регрессионных тестах — никогда не меняйте формы JSON standard внутри mock.