Rewards

Rewards

Назначение Rewards

Rewards (Награды) — это сущность для управления призами и вознаграждениями в программе лояльности.

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

• Создание различных типов наград (бонусы, скидки, подарки, промокоды)
• Настройка условий выдачи и ограничений
• Интеграция со стеками купонов для автоматической выдачи промокодов
• Управление видимостью и приоритетом наград
• Модерация выдачи наград
• Гибкая настройка активации через внешние системы

Типы наград

Rewards поддерживает различные типы наград:

1. Обычные призы - награды с описанием, логотипом, ссылками
2. Промокоды - награды с интеграцией стеков купонов
3. Подписки - призы, которые можно активировать после подтверждения через СМС-код

Промокоды и стеки купонов

При создании награды типа "промокод" используется механика стеков купонов. Стек купонов — это массив промокодов, из которого система автоматически берет уникальный код при выдаче награды клиенту.

Как это работает:

1. В Reward указывается coupons_id - идентификатор стека купонов
2. При выдаче награды система берет один купон из стека
3. Купон сохраняется в награде клиента
4. Купон помечается как использованный

Ограничения выдачи

Система поддерживает гибкие ограничения на выдачу наград:

Пример: Если issue_type = "once a period" и issue_period = 7, то клиент может получать награду не чаще раза в неделю.

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

Поле is_unique определяет, как создаются записи выданных наград:

is_unique = true (Уникальные награды):

• При каждой выдаче формируется уникальный ID награды
• Каждая выдача создает отдельную запись в базе данных
• Каждая запись получает свой промокод из стека (если используются купоны)

Пример: Клиент получил награду дважды:

Запись 1: id = "promo_discount_abc123", промокод = "SALE10-X7Y9"
Запись 2: id = "promo_discount_def456", промокод = "SALE10-K2M5"

is_unique = false (Обычные награды):

• Используется один и тот же ID награды
• При повторной выдаче существующая запись перезаписывается
• Промокод заменяется на новый (если используются купоны)

Важно: Для наград с промокодами рекомендуется использовать is_unique = true, чтобы сохранялась история всех выданных промокодов.

Моментальная выдача и модерация

Моментальная выдача (is_instant)

• is_instant = true - награда выдается автоматически сразу после триггера
• is_instant = false - награду должен выдать сценарий в Flow

Если награда не моментальная, можно настроить специальные тексты:

• instant_title - заголовок для показа клиенту
• instant_description - описание процесса выдачи

Пример: "Ваша награда обрабатывается, ожидайте уведомления в течение 24 часов"

Модерация (is_moderated)

• is_moderated = true - выдача награды требует ручного подтверждения администратором
• is_moderated = false - выдача полностью автоматическая

Для модерируемых наград настраиваются тексты:

• moderated_title - заголовок для показа во время модерации
• moderated_description - описание процесса модерации

Пример: "Ваша заявка на получение приза проверяется модератором"

Процесс модерации

Обычно модерация настраивается через файлообмен или прямой доступ к базе данных:

1. Клиент получает награду со статусом "на модерации"
2. Модератор получает доступ к базе выданных наград (таблица {{environment_id}}.rewards)
3. Модератор проверяет клиента и формирует файл с решениями
4. Файл содержит списки подтвержденных и заблокированных наград
5. Подтвержденные награды:
   • Выдаются клиенту окончательно
   • Если используются купоны - берется купон из стека
6. Заблокированные награды:
   • Удаляются из базы
   • Купоны не используются

Статусы наград и жизненный цикл

Возможные статусы:

Автоматические изменения статуса:

• При достижении даты active_to награда автоматически переходит в статус expired
• При достижении даты archieve_from награда уходит в архив, но не удаляется из системы
• Архивные награды сохраняются для истории, но не доступны для выдачи

Видимость и приоритет

is_visible (Флаг видимости)

• is_visible = true - награда отображается в интерфейсе
• is_visible = false - награда скрыта для пользователя

Применение: Флаг используется на уровне фронтенда или промежуточного бэкенда для фильтрации состава ответа. Это позволяет создавать награды, которые существуют в системе, но временно скрыты от пользователей.

is_priority (Флаг приоритета)

• is_priority = true - награда помечена как приоритетная
• is_priority = false - обычная награда

Применение (в разработке): Приоритетные награды могут выдаваться из сундуков (Treasures), игнорируя стандартные вероятности. Это позволяет гарантировать выдачу определенных наград.

Пример использования: Акционная награда с ограниченным сроком может быть помечена как приоритетная, чтобы гарантировать ее получение определенными сегментами пользователей.

position (Позиция при сортировке)

Поле position определяет порядок отображения наград в интерфейсе. Работает независимо от is_priority.

Тип награды (type)

Поле type является свободным текстовым полем без жестких ограничений.

Применение:

• Группировка наград на фронтенде
• Фильтрация при выборе награды для выдачи
• Категоризация в аналитике

Примеры типов:

• bonus_points - бонусные баллы
• promocode - промокод
• physical_gift - физический подарок
• discount - скидка
• cashback - кэшбэк
• subscription - подписка

Вы можете создавать собственные типы в зависимости от бизнес-логики.

Партнеры (partner_id)

Поле partner_id используется как простой флаг для обозначения партнерских наград.

Применение:

• Идентификация наград от партнеров
• Группировка партнерских предложений
• Фильтрация в отчетах

Примечание: На текущем этапе partner_id не влияет на логику работы системы и используется только для маркировки и аналитики.

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

Поле additional представляет собой JSON-объект для хранения любых кастомных параметров.

Особенности:

• Полностью гибкое - можно использовать любую структуру данных
• Нет стандартных полей или ограничений
• Параметры определяются бизнес-логикой конкретного проекта

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

{
  "additional": {
    "button_text": "Активировать",
    "button_url": "https://example.com/activate",
    "icon_url": "https://cdn.example.com/icons/gift.png",
    "background_color": "#FF6B6B",
    "tags": ["новинка", "акция"],
    "metadata": {
      "campaign_id": "summer_2025",
      "source": "email"
    }
  }
}

Процесс выдачи наград

Награды могут выдаваться двумя способами:

1. Через модуль Flow

Сценарий:

1. Внешняя система отправляет во Flow событие о необходимости выдачи награды
2. Flow отлавливает это событие
3. Сценарий вызывает API-метод выдачи награды по клиенту
4. Награда создается в таблице {{environment_id}}.rewards

Пример события:

{
  "event_type": "give_reward",
  "client_id": "12345",
  "reward_id": "bonus_500",
  "environment_id": "accelera"
}

2. Через внешнюю систему (Backend)

Сценарий:

1. Внешняя система, использующая платформу лояльности, напрямую инициирует выдачу
2. Backend вызывает API-метод создания награды по клиенту
3. Flow не участвует в процессе
4. Награда сразу создается в базе данных

Это позволяет интегрировать лояльность в существующие системы без необходимости настройки сценариев во Flow.

Клиентские награды

При выдаче награды клиенту создается запись в таблице **{{environment_id}}.rewards**, где {{environment_id}} — это идентификатор окружения.

Структура хранения:

• Каждое окружение имеет свою схему в базе данных
• Название схемы совпадает с environment_id
• Внутри схемы создается таблица rewards с записями выданных наград

Пример: Для окружения accelera выданные награды хранятся в accelera.rewards

API "Мои награды"

Клиент может получить список своих наград через API:

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

Ответ содержит:

• Все выданные клиенту награды
• Информацию о статусе каждой награды
• Промокоды (если применимо)
• Даты получения и активации
• Дополнительные параметры из поля additional

Удаление выданных наград

Уже выданную клиенту награду можно удалить через API:

curl --request DELETE \
     --url /v1/internal/rewards/clients/{{client_id}}/{{environment_id}}/{{reward_id}} \
     --header 'accept: application/json'

Применение:

• Отзыв ошибочно выданных наград
• Удаление истекших наград
• Урегулирование спорных ситуаций

Важно: При удалении награды с промокодом купон остается использованным.

Типы активации

Поле activation_type определяет способ активации награды:

Поле external_id используется для связи с внешними системами активации.

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

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

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

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

Флаги

Ограничения выдачи

Активация и промокоды

Партнеры и даты

Сортировка и дополнительно

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

Пример 1: Обычная награда с баллами

{
  "environment_id": "accelera",
  "id": "bonus_500",
  "type": "bonus_points",
  "status": "active",
  "title": "500 бонусных баллов",
  "description": "Получите 500 баллов на счет",
  "category": "bonuses",
  "issue_type": "once",
  "active_from": "2025-01-01",
  "active_to": "2025-12-31",
  "is_instant": true,
  "is_moderated": false,
  "is_visible": true,
  "is_priority": false,
  "position": 1
}

Пример 2: Промокод из стека купонов

{
  "environment_id": "accelera",
  "id": "promo_discount",
  "type": "promocode",
  "status": "active",
  "title": "Скидка 15%",
  "description": "Промокод на скидку 15% в партнерских магазинах",
  "details": "Действует 30 дней с момента получения",
  "activation_type": "promocode",
  "coupons_id": "stack_december_2025",
  "issue_type": "once a period",
  "issue_period": 30,
  "active_from": "2025-12-01",
  "active_to": "2025-12-31",
  "is_instant": true,
  "is_moderated": false,
  "is_visible": true,
  "position": 2
}

Пример 3: Награда с модерацией

{
  "environment_id": "accelera",
  "id": "premium_gift",
  "type": "physical_gift",
  "status": "active",
  "title": "Премиум подарок",
  "description": "Эксклюзивный подарок для VIP-клиентов",
  "issue_type": "once",
  "active_from": "2025-01-01",
  "active_to": "2025-12-31",
  "is_instant": false,
  "instant_title": "Обработка заявки",
  "instant_description": "Ваша заявка на получение подарка обрабатывается",
  "is_moderated": true,
  "moderated_title": "Проверка модератором",
  "moderated_description": "Подарок будет выдан после проверки модератором в течение 48 часов",
  "is_visible": true,
  "position": 3
}

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

Выдача новой награды клиенту

curl --request POST \
     --url /v1/internal/rewards \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "client_id": "client1"
  "environment_id": "accelera",
  "id": "bonus_500"
}
'

Получение наград клиента

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

Удаление выданной награды

curl --request DELETE \
     --url /v1/internal/rewards/clients/{{client_id}}/{{environment_id}}/{{reward_id}} \
     --header 'accept: application/json'

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

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

1. Tasks - награды выдаются автоматически при выполнении заданий через Flow
2. Treasures - награды используются как призы в сундуках
3. Coupons Stack - при типе promocode награды берут купоны из загруженных стеков
4. Wallet - награды типа "бонусные баллы" начисляют валюту на кошелек
5. Flow - сценарии управляют выдачей наград при выполнении условий

Работа с Rewards

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