Coupons Stack (Стеки купонов)

Назначение Coupons Stack

Coupons Stack (Стеки купонов) — это механизм управления массивами промокодов для автоматической выдачи уникальных кодов клиентам.

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

Создание идентификаторов стеков купонов
Загрузка купонов из файла
Просмотр остатка доступных купонов
Привязка стеков к наградам (Rewards) для автоматической выдачи
Пополнение существующих стеков новыми купонами

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

Создание стека - администратор создает стек с уникальным coupons_id
Загрузка купонов - загружается файл с промокодами
Привязка к награде - в сущности Reward указывается coupons_id стека
Автоматическая выдача - при выдаче награды клиенту система:
- Берет один купон из стека
- Сохраняет его в награде клиента
- Помечает купон как использованный
- Уменьшает счетчик доступных купонов

Связь с Rewards

Стеки купонов тесно интегрированы с сущностью Rewards:

В Reward:

{
  "id": "promo_discount",
  "type": "promocode",
  "activation_type": "promocode",
  "coupons_id": "stack_december_2025"
}

В Coupons Stack:

{
  "coupons_id": "stack_december_2025",
  "reward_id": "promo_discount",
  "title": "Промокоды декабря"
}

При выдаче награды promo_discount система автоматически возьмет купон из стека stack_december_2025.

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

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

Параметр	Тип данных	Описание
environment_id	Varchar(50)	ID окружения, к которому относится стек купонов
coupons_id	Varchar(50)	Уникальный идентификатор стека купонов
reward_id	Varchar(50)	ID награды с типом promocode, к которой привязан стек

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

Параметр	Тип данных	Описание
title	Varchar(50)	Название стека купонов
description	Varchar(250)	Описание назначения купонов

Связи и метаданные

Параметр	Тип данных	Описание
partner_id	Varchar(50)	ID партнера (если купоны от партнера)
creator	Varchar(250)	Создатель стека (имя пользователя)

Загрузка купонов

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

Формат файла: CSV или TXT (один купон на строку)

Формат имени файла:

{{coupon_id}}#Описание.csv

Где:

{{coupon_id}} - ID стеку купонов (например, litres)
Описание - произвольное текстовое описание

Пример: litres#Награды_декабря.csv

Пример содержимого:

SUMMER2025-ABC123
SUMMER2025-XYZ789
SUMMER2025-QWE456
SUMMER2025-RTY789

Требования к купонам:

Каждый купон должен быть уникальным
Формат купона определяется бизнес-логикой
Рекомендуется использовать легко читаемые коды

Мониторинг остатка

Администратор может просматривать остаток доступных купонов в стеке:

Информация о стеке:

Общее количество загруженных купонов
Количество использованных купонов
Количество доступных купонов
История использования

Пример:

Стек: stack_december_2025
Всего загружено: 10,000
Использовано: 3,245
Доступно: 6,755

Важно: Если доступные купоны заканчиваются, рекомендуется пополнить стек новыми купонами до того, как система начнет возвращать ошибки при выдаче наград.

Пополнение стека

Существующий стек можно пополнить новыми купонами:

Подготовьте файл с новыми уникальными промокодами
Загрузите файл в существующий стек
Система добавит новые купоны к существующим
Счетчик доступных купонов увеличится

Важные моменты:

Новые купоны не должны дублировать существующие, если это не предусмотрено
Дубликаты будут прогружены
Пустые строки будут прогружены

Обработка ошибок

Распространенные ошибки (Тут требуется обновление, прописаны ошибки, которые хочется реализовать в системе):

Стек пуст - все купоны использованы
```
\{
  "error": "No available coupons in stack",
  "coupons_id": "stack_december_2025"
\}
```
Решение: Пополните стек новыми купонами
Стек не найден - указан несуществующий coupons_id
```
\{
  "error": "Coupons stack not found",
  "coupons_id": "invalid_stack"
\}
```
Решение: Проверьте правильность coupons_id

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

Пример 1: Промокоды для новых клиентов

Стек: welcome_promo_2025
Награда: welcome_bonus
Купоны: WELCOME2025-XXXXX (5000 штук)
Использование: При регистрации новый клиент получает уникальный промокод

Пример 2: Сезонная акция

Стек: black_friday_2025
Награда: bf_discount_50
Купоны: BF50-XXXXX (50000 штук)
Использование: За покупку клиент получает промокод на скидку 50%

Пример 3: Партнерские промокоды

Стек: partner_retail_q4
Награда: partner_gift

Partner: Торговая сеть "Пятерочка"
Купоны: P5-XXXXX (20000 штук)
Использование: Клиент получает промокод для использования у партнера

Coupons Stack (Стеки купонов)