Items

Items

Назначение Items

Items (Предметы) — это объекты лояльности, которые клиенты могут приобрести за валюту из кошелька (Wallet) или получить бесплатно.

Основные возможности:

• Создание виртуальных товаров для продажи или выдачи
• Покупка за валюту лояльности (баллы, бонусы и т.д.)
• Бесплатная выдача (при price = 0)
• Три типа предметов: reward, treasure, item
• Контроль доступности и количества покупок
• Персонализация для каждого клиента

Типы Items

Система поддерживает три типа предметов:

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

Пример 1: Покупка конкретной награды (reward)

{
  "id": "premium_bonus_pack",
  "item_type": "reward",
  "title": "Премиум набор бонусов",
  "description": "1000 бонусных баллов",
  "reward_id": "bonus_1000",
  "price": 500,
  "currency": "bonusPlus"
}

Сценарий: Клиент платит 500 баллов из кошелька bonusPlus и получает награду bonus_1000 в раздел "Мои призы".

Пример 2: Покупка сундука (treasure)

{
  "id": "lucky_chest",
  "item_type": "treasure",
  "title": "Счастливый сундук",
  "description": "Откройте и получите случайный приз",
  "treasure_id": "daily_chest",
  "price": 100,
  "currency": "bonusPlus"
}

Сценарий: Клиент платит 100 баллов, сундук daily_chest автоматически открывается, система выдает случайный приз согласно настроенным вероятностям.

Пример 3: Покупка игрового предмета (item)

{
  "id": "super_premium_skin",
  "item_type": "item",
  "title": "Супер-премиум скин",
  "description": "Эксклюзивный скин для вашего персонажа",
  "price": 2000,
  "currency": "bonusPlus"
}

Сценарий: Клиент платит 2000 баллов и получает предмет в свой инвентарь. Этот предмет может использоваться в игре, мобильном приложении и т.д.

Пример 4: Бесплатная выдача

{
  "id": "welcome_gift",
  "item_type": "item",
  "title": "Супер-премиум скин",
  "description": "Эксклюзивный скин для вашего персонажа",
  "price": 0,
  "currency": "bonusPlus"
}

Сценарий: При price = 0 предмет выдается бесплатно. Подходит для приветственных подарков, акций, промо-механик.

Покупки и ограничения

Множественные покупки

Система контролирует, можно ли купить предмет несколько раз:

• is_multiple_purchases = true - предмет можно купить несколько раз
• is_multiple_purchases = false - предмет можно купить только один раз
• multiple_purchases_count - указывает максимальное количество покупок

Пример: Cундук может быть куплен не более 3 раз (is_multiple_purchases = true, multiple_purchases_count = 3).

Уникальность (is_unique)

• is_unique = true - каждая покупка создает уникальную запись с новым ID
• is_unique = false - все покупки используют один ID

Применение: Для коллекционных предметов или предметов с историей используйте is_unique = true.

Блокировка (is_locked)

• is_locked = true - предмет заблокирован и недоступен для покупки
• is_locked = false - предмет доступен для покупки

Применение: Используйте для создания предметов, которые открываются при выполнении условий (достижение уровня, выполнение задания).

Состояние покупки (is_purchased)

• is_purchased = true - предмет уже куплен клиентом
• is_purchased = false - предмет еще не куплен

Это поле обновляется автоматически после покупки.

Валюта и цена

Каждый item имеет цену и валюту:

• price - стоимость предмета
• currency - ID валюты из Wallet (например, bonusPlus, miles, cashback)

Бесплатная выдача:

{
  "price": 0,
  "currency": "bonusPlus"
}

При покупке система:

1. Проверяет баланс клиента в указанной валюте
2. Списывает сумму price из кошелька
3. Выдает предмет/награду/открывает сундук

Срок действия

Items могут иметь ограниченный период доступности:

• valid_from - дата начала действия (формат: YYYY-MM-DD)
• expired_at - дата окончания действия (формат: YYYY-MM-DD)

Пример: Новогодний сундук доступен только с 25 декабря по 10 января.

Аварийная награда (emergency_reward_id)

Если при открытии сундука или выдаче награды происходит ошибка, система выдаст аварийную награду:

{
  "item_type": "treasure",
  "treasure_id": "premium_chest",
  "reward_id": "bonus_100",
  "emergency_reward_id": "emergency_bonus_50"
}

Если сундук premium_chest не может быть открыт (например, закончились призы), клиент получит emergency_bonus_50.

Описание полей

Обязательные поля

Поля с описанием

Медиа

Связи с другими сущностями

Флаги и ограничения

Срок действия

Дополнительные параметры

Примеры заполнения Items

Пример 1: Платный сундук с множественной покупкой

{
  "environment_id": "accelera",
  "id": "daily_lucky_chest",
  "item_type": "treasure",
  "title": "Ежедневный счастливый сундук",
  "short_description": "Откройте и получите случайный приз!",
  "full_description": "Сундук содержит случайные награды от 50 до 1000 баллов",
  "treasure_id": "daily_chest",
  "emergency_reward_id": "emergency_bonus_50",
  "price": 100,
  "currency": "bonusPlus",
  "is_multiple_purchases": true,
  "multiple_purchases_count": "3",
  "is_unique": true,
  "is_locked": false,
  "is_default": true,
  "valid_from": "2025-01-01",
  "expired_at": "2025-12-31"
}

Пример 2: Бесплатный приветственный подарок

{
  "environment_id": "accelera",
  "id": "welcome_reward",
  "item_type": "reward",
  "title": "Приветственный подарок",
  "short_description": "Получите 500 баллов в подарок!",
  "reward_id": "welcome_bonus_500",
  "price": 0,
  "currency": "bonusPlus",
  "is_multiple_purchases": false,
  "is_unique": false,
  "is_locked": false,
  "is_default": true
}

Пример 3: Платный эксклюзивный предмет

{
  "environment_id": "accelera",
  "id": "vip_skin_gold",
  "item_type": "item",
  "title": "Золотой VIP скин",
  "short_description": "Эксклюзивный золотой скин для VIP-клиентов",
  "full_description": "Уникальный скин доступен только для VIP уровня",
  "price": 5000,
  "currency": "bonusPlus",
  "is_multiple_purchases": false,
  "is_unique": false,
  "is_locked": true,
  "is_default": false,
  "image_url": "https://cdn.example.com/skins/gold.png",
  "additional": {
    "rarity": "legendary",
    "unlock_level": 10
  }
}

Примеры API-запросов

Создание нового item в системе

curl --request POST \
     --url /v1/management/items \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "environment_id": "accelera",
  "id": "daily_chest_item",
  "item_type": "treasure",
  "title": "Ежедневный сундук",
  "treasure_id": "daily_chest",
  "price": 100,
  "currency": "bonusPlus",
  "is_multiple_purchases": true,
  "multiple_purchases_count": "3"
}
'

Покупка item клиентом

curl --request POST \
     --url /v1/internal/wallet/purchase \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "client_id": "12345",
  "environment_id": "accelera",
  "id": "daily_chest_item"
}
'

Что происходит при покупке:

1. Система проверяет баланс клиента в валюте currency
2. Проверяет доступность item (is_locked, valid_from, expired_at)
3. Проверяет лимит покупок (is_multiple_purchases, multiple_purchases_count)
4. Списывает price из кошелька клиента
5. Выполняет действие согласно item_type:
   • reward - создает награду
   • treasure - открывает сундук и выдает приз
   • item - добавляет предмет в инвентарь

Получение items по клиенту

curl --request GET \
     --url /v1/internal/items/clients/{{client_id}}/{{environment_id}} \
     --header 'accept: application/json'

Интеграция с другими сущностями

Items тесно интегрируется с другими механиками системы:

1. Wallet - списание валюты при покупке
2. Rewards - выдача наград при item_type = reward
3. Treasures - открытие сундуков при item_type = treasure
4. Tasks - items могут быть наградой за выполнение заданий
5. Level - разблокировка items при достижении уровня
6. Achievements - items как награда за достижения

Сценарии использования

Сценарий 1: Магазин виртуальных товаров

Создайте каталог items типа item с различными ценами. Клиенты могут просматривать магазин и покупать предметы за баллы.

Скин "Классический" - 500 баллов
Скин "Премиум" - 2000 баллов
Скин "Легендарный" - 10000 баллов (заблокирован до уровня 10)

Сценарий 2: Акционные предложения

Создайте ограниченные по времени items:

Новогодний сундук
valid_from: 2025-12-25

expired_at: 2026-01-10

price: 100 (вместо обычных 200)

Работа с Items

Для работы с предметами используйте методы API, описанные выше. Items могут создаваться и управляться через интерфейс ЛК менеджера или программно через API.