Аутентификация

Все запросы Public API требуют Bearer token. Учетные данные каналов и складские коды управляются в портале разработчика — никогда не встраивайте их в клиентские приложения.

API-ключи {#api-keys}

Создавайте ключи в Developer Portal → API Keys после одобрения приложения.

Пункт	Описание
Формат	`Authorization: Bearer hio_live_…` (production) или тестовые ключи, выданные порталом
Область	Один ключ на приложение. Квоты и доступ к каналам следуют subscription plan приложения.
Ротация	Немедленно отзывайте скомпрометированные ключи; перед отзывом в production создайте замену.
Хранение	Только на стороне сервера. Не раскрывайте ключи в мобильных приложениях, browser JS или публичных репозиториях.

Пример запроса

curl https://api.hiobuy.com/v1/products/detail \
  -H "Authorization: Bearer hio_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "1688",
    "product_id": "554456348334",
    "language": "en"
  }'

Авторизация канала (предварительное требование) {#channel-authorization}

Одного API-ключа недостаточно. Каждое приложение должно выполнить авторизацию канала перед вызовом product или order APIs для этого маркетплейса.

Режим	Что вы настраиваете	Что использует Gateway
Self fulfillment	OAuth для каждого канала или token JSON в портале	Сохраненные токены для приложения + канала
Склад HIOBuy	Один складской код разработчика	Код + управляемые токены на сервере; закупка/фулфилмент пересылаются в HIOBuy

См. авторизацию в портале. Если канал не авторизован, вызовы возвращают 401 CHANNEL_NOT_AUTHORIZED (ошибки).

Что вы никогда не отправляете {#what-not-to-send}

Access tokens или refresh tokens Taobao / 1688 / Weidian
Складской код разработчика (Gateway прикрепляет его для fulfillment routes)
Portal session JWT в вызовах Public API

Трассировка запросов {#tracing}

Каждый ответ включает:

заголовок x-request-id — сопоставляйте с request_id в JSON body
опциональные quota headers на billable routes — см. лимиты запросов

Указывайте x-request-id при обращении в поддержку HIOBuy.

Распространенные ошибки auth {#auth-errors}

HTTP	Код	Значение
401	`INVALID_API_KEY`	Bearer token отсутствует, отозван или имеет неверный формат
401	`CHANNEL_NOT_AUTHORIZED`	Приложение не авторизовало запрошенный канал в портале
403	`INSUFFICIENT_SCOPE`	У ключа или приложения нет разрешения на операцию
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	Fulfillment API вызван, когда приложение находится в self-fulfillment mode