Управление товарами

Товары (Items) - это предметы, доступные для покупки в магазинах вашей игры или приложения.

Создание товара

POST /api/v1/items

Создает новый товар в каталоге магазина.

Требуется авторизация: x-account-key

Запрос

POST /api/v1/items HTTP/1.1
Host: API_HOST
x-account-key: YOUR_ACCOUNT_KEY
Content-Type: application/json

{
  "store_id": "store_xyz789",
  "name": "gems_100",
  "display_name": "100 Gems Pack",
  "description": "Набор из 100 кристаллов",
  "price": "499",
  "type": "consumable",
  "meta": {
    "gems_amount": 100,
    "bonus_gems": 10,
    "category": "currency"
  }
}

Параметры запроса

Параметр	Тип	Обязательный	Описание
`store_id`	string	Да	ID магазина
`name`	string	Да	Уникальное имя товара (SKU)
`display_name`	string	Да	Отображаемое название товара
`description`	string	Нет	Описание товара
`price`	string	Да	Цена в минимальных единицах валюты (копейки/центы)
`type`	string	Да	Тип товара
`meta`	object	Нет	Дополнительные метаданные

Успешный ответ (200 OK)

{
  "id": "item_abc123",
  "name": "gems_100",
  "display_name": "100 Gems Pack",
  "description": "Набор из 100 кристаллов"
}

Параметры ответа

Параметр	Тип	Описание
`id`	string	Уникальный идентификатор товара
`name`	string	Имя товара (SKU)
`display_name`	string	Отображаемое название
`description`	string	Описание товара

Возможные ошибки

400 Bad Request - неверные параметры запроса
401 Unauthorized - неверный или отсутствующий x-account-key
500 Internal Server Error - внутренняя ошибка сервера

Получение списка товаров

GET /api/v1/items

Получает все товары магазина.

Требуется авторизация: Bearer токен

Запрос

GET /api/v1/items?store_id=store_xyz789 HTTP/1.1
Host: API_HOST
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Параметры запроса

Параметр	Тип	Обязательный	Описание
`store_id`	string	Да	ID магазина

Успешный ответ (200 OK)

{
  "items": [
    {
      "id": "item_abc123",
      "name": "gems_100",
      "display_name": "100 Gems Pack",
      "description": "Набор из 100 кристаллов",
      "price": 499,
      "type": "consumable",
      "store_id": "store_xyz789",
      "metadata": {
        "gems_amount": 100,
        "bonus_gems": 10
      }
    },
    {
      "id": "item_def456",
      "name": "gems_500",
      "display_name": "500 Gems Pack",
      "description": "Большой набор кристаллов",
      "price": 1999,
      "type": "consumable",
      "store_id": "store_xyz789",
      "metadata": {
        "gems_amount": 500,
        "bonus_gems": 100
      }
    }
  ]
}

Параметры ответа

Параметр	Тип	Описание
`items`	array	Массив товаров

ItemDto

Параметр	Тип	Описание
`id`	string	Уникальный идентификатор товара
`name`	string	Имя товара (SKU)
`display_name`	string	Отображаемое название
`description`	string	Описание товара
`price`	integer	Цена в минимальных единицах валюты
`type`	string	Тип товара
`store_id`	string	ID магазина
`metadata`	object	Дополнительные метаданные

Возможные ошибки

400 Bad Request - неверные параметры запроса
401 Unauthorized - неверный или отсутствующий токен
500 Internal Server Error - внутренняя ошибка сервера

Получение товара по ID

`GET /api/v1/items/{item_id}`

Получает детальную информацию о конкретном товаре.

Требуется авторизация: Bearer токен

Запрос

GET /api/v1/items/item_abc123 HTTP/1.1
Host: API_HOST
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Параметры пути

Параметр	Тип	Описание
`item_id`	string	ID товара

Успешный ответ (200 OK)

{
  "id": "item_abc123",
  "name": "gems_100",
  "display_name": "100 Gems Pack",
  "description": "Набор из 100 кристаллов",
  "price": 499,
  "type": "consumable",
  "store_id": "store_xyz789",
  "metadata": {
    "gems_amount": 100,
    "bonus_gems": 10,
    "category": "currency"
  }
}

Возможные ошибки

400 Bad Request - неверные параметры запроса
401 Unauthorized - неверный или отсутствующий токен
404 Not Found - товар не найден

Типы товаров

Тип	Описание
`consumable`	Расходуемый товар (валюта, зелья)
`non_consumable`	Постоянный товар (скин, разблокировка)
`subscription`	Подписка

Цена товара

Цена указывается в минимальных единицах валюты:

Валюта	Пример	Значение
USD	$4.99	`"499"`
EUR	4.99	`"499"`
RUB	499	`"49900"`

{
  "price": "499"  // $4.99 или 4.99
}

Имя товара (name/SKU)

Поле name используется как уникальный идентификатор товара в вашей системе (SKU).

Примеры хороших имен

// Валюта
'gems_100'      // 100 кристаллов
'gems_500'      // 500 кристаллов
'coins_1000'    // 1000 монет

// Подписки
'sub_monthly'   // Месячная подписка
'sub_yearly'    // Годовая подписка

// Предметы
'sword_legendary'     // Легендарный меч
'armor_epic_chest'    // Эпическая броня

// Наборы
'starter_pack'        // Стартовый набор
'battle_pass_s1'      // Боевой пропуск сезон 1

Правила для имен

Используйте только латинские буквы, цифры и подчеркивания
Делайте их понятными и описательными
Используйте единый стиль именования
Имя должно быть уникальным в рамках магазина
Избегайте специальных символов и пробелов

Метаданные (meta)

Поле meta позволяет хранить любую дополнительную информацию о товаре:

Примеры использования

// Валюта
{
  "meta": {
    "gems_amount": 100,
    "bonus_gems": 10,
    "category": "currency",
    "popular": true
  }
}

// Предмет
{
  "meta": {
    "item_type": "weapon",
    "rarity": "legendary",
    "level_required": 50,
    "stats": {
      "damage": 150,
      "critical_chance": 0.25
    }
  }
}

// Подписка
{
  "meta": {
    "duration_days": 30,
    "benefits": [
      "no_ads",
      "daily_bonus",
      "exclusive_items"
    ]
  }
}

Массовый импорт покупок

Если вам нужно загрузить большое количество покупок сразу, используйте эндпоинт импорта. Запрос принимает CSV файл и идентификатор магазина через multipart/form-data.

Требуется авторизация: Bearer токен

curl --location 'https://API_HOST/api/v1/purchases/import' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ••••••' \
  --form 'file=@"/path/to/file"' \
  --form 'store_id="your_store_id"'

Параметры запроса (form-data)

Параметр	Тип	Обязательный	Описание
`file`	file	Да	Файл с данными покупок
`store_id`	string	Да	ID магазина

Успешный ответ (200 OK)

{
  "ok": true
}

Связанные разделы

Магазины - создание магазинов
Покупки - обработка покупок товаров

Создание товара​

POST /api/v1/items​

Запрос​

Параметры запроса​

Успешный ответ (200 OK)​

Параметры ответа​

Возможные ошибки​

Получение списка товаров​

GET /api/v1/items​

Запрос​

Параметры запроса​

Успешный ответ (200 OK)​

Параметры ответа​

ItemDto​

Возможные ошибки​

Получение товара по ID​

GET /api/v1/items/{item_id}​

Запрос​

Параметры пути​

Успешный ответ (200 OK)​

Возможные ошибки​

Типы товаров​

Цена товара​

Имя товара (name/SKU)​

Примеры хороших имен​

Правила для имен​

Метаданные (meta)​

Примеры использования​

Массовый импорт покупок​

Параметры запроса (form-data)​

Успешный ответ (200 OK)​

Связанные разделы​

Создание товара

POST /api/v1/items

Запрос

Параметры запроса

Успешный ответ (200 OK)

Параметры ответа

Возможные ошибки

Получение списка товаров

GET /api/v1/items

Запрос

Параметры запроса

Успешный ответ (200 OK)

Параметры ответа

ItemDto

Возможные ошибки

Получение товара по ID

`GET /api/v1/items/{item_id}`

Запрос

Параметры пути

Успешный ответ (200 OK)

Возможные ошибки

Типы товаров

Цена товара

Имя товара (name/SKU)

Примеры хороших имен

Правила для имен

Метаданные (meta)

Примеры использования

Массовый импорт покупок

Параметры запроса (form-data)

Успешный ответ (200 OK)

Связанные разделы