Реферальная программа

Обзор

Реферальная программа позволяет пользователям приглашать новых клиентов и зарабатывать комиссию с их пополнений и покупок. Включает партнёрскую систему для профессиональных рефереров.

REFERRAL_PROGRAM_ENABLED=true

При отключении:

Кнопки “Партнёрка”, “Мои рефералы” скрываются из меню
Административные функции остаются доступными

Механика работы

Реферальная ссылка

Каждый пользователь получает уникальный реферальный код формата refAbC12dEf (3 + 8 символов) и ссылку:

https://t.me/{bot_username}?start=refAbC12dEf

Процесс приглашения

Реферер делится ссылкой или QR-кодом
Новый пользователь переходит по ссылке и регистрируется
Создаётся запись referral_registration_pending
При первом пополнении (>= REFERRAL_MINIMUM_TOPUP_KOPEKS) обоим начисляются бонусы
С каждого последующего пополнения и покупки реферала начисляется комиссия

QR-код

Генерируется через библиотеку qrcode
Содержит полную реферальную ссылку
Кэшируется в data/referral_qr/{user_id}.png
Доступен через кнопку “Показать QR-код”

Система комиссий

Бонус за первое пополнение

При первом пополнении реферала на сумму >= REFERRAL_MINIMUM_TOPUP_KOPEKS:

Получатель	Бонус
Реферал (новый пользователь)	`REFERRAL_FIRST_TOPUP_BONUS_KOPEKS` на баланс
Реферер (пригласивший)	`max(REFERRAL_INVITER_BONUS_KOPEKS, комиссия%)`

Если пополнение меньше минимума — реферер получает только комиссию, бонус за первое пополнение откладывается.

Если REFERRAL_FIRST_TOPUP_BONUS_KOPEKS = 0, информация о бонусе для реферала скрывается из уведомлений и личного кабинета. Аналогично, если REFERRAL_INVITER_BONUS_KOPEKS = 0, карточка бонуса реферера не отображается в интерфейсе.

Комиссия с пополнений

С каждого пополнения реферала (включая первое и последующие):

Комиссия = сумма_пополнения × REFERRAL_COMMISSION_PERCENT / 100

Если REFERRAL_MAX_COMMISSION_PAYMENTS > 0, комиссия начисляется только с первых N пополнений каждого реферала. После достижения лимита комиссия с пополнений этого реферала больше не начисляется. По умолчанию значение 0 — комиссия начисляется с каждого пополнения без ограничений.

Комиссия с покупок

С каждой покупки подписки:

Комиссия = сумма_покупки × REFERRAL_COMMISSION_PERCENT / 100

Индивидуальная комиссия

Администратор может установить персональный процент комиссии для конкретного пользователя (User.referral_commission_percent). Это переопределяет глобальный REFERRAL_COMMISSION_PERCENT.

Интерфейс пользователя

Меню “Партнёрка”

Кнопка	Описание
Создать приглашение	Сформировать текст для пересылки с кнопкой “Поделиться”
QR-код	Показать QR с реферальной ссылкой
Список рефералов	Пагинированный список (10 на страницу) с деталями
Аналитика	Доходы по периодам и топ рефералов
Запросить вывод	Заявка на вывод средств (если включено)

Список рефералов

Для каждого реферала показывается:

Статус (активный/неактивный)
Первое пополнение (да/нет)
Количество пополнений
Заработано с реферала
Дата регистрации
Последняя активность

Аналитика

Доходы по периодам: сегодня, неделя, месяц, квартал
Топ-5 самых прибыльных рефералов

Вывод средств

Включение

REFERRAL_WITHDRAWAL_ENABLED=true
REFERRAL_WITHDRAWAL_MIN_AMOUNT_KOPEKS=50000    # 500 руб
REFERRAL_WITHDRAWAL_COOLDOWN_DAYS=30

Пользовательский flow

Проверка доступности: включён ли вывод, достаточно ли средств, прошёл ли cooldown
Ввод суммы (ручной или “Вывести всё”)
Ввод реквизитов (номер СБП и банк, мин. 10 символов)
Подтверждение заявки
Система создаёт заявку с анализом рисков и уведомляет администраторов

Расчёт доступного баланса

Если REFERRAL_WITHDRAWAL_ONLY_REFERRAL_BALANCE=true (по умолчанию):

Доступны только реферальные доходы
Формула: min(баланс, заработано - выведено - в ожидании)
Собственные пополнения не учитываются

Если false:

Доступен весь оставшийся баланс пользователя

Статусы заявки

Статус	Описание
`pending`	Ожидает проверки администратором
`approved`	Одобрена, баланс списан
`rejected`	Отклонена
`completed`	Деньги переведены
`cancelled`	Отменена пользователем

Анализ подозрительной активности

Каждая заявка автоматически проверяется на признаки фрода (risk score 0-100):

Проверка	Баллы	Описание
Пополнения без покупок	+40	Средства не тратились на подписки
Пополнения >> траты	+25	Соотношение пополнений к тратам > порога
Нет рефералов, но есть доход	+50	Реферальный доход без фактических рефералов
Много пополнений от одного реферала	+15	Превышение порога за месяц
Крупные пополнения от одного реферала	+10	Превышение минимальной суммы
Весь доход от одного реферала	+20	Только один платящий реферал (>500 руб)
Много начислений за неделю	+15	>20 начислений за последнюю неделю

Уровни риска:

Диапазон	Уровень	Рекомендация
0-29	Низкий (зелёный)	Можно одобрить
30-49	Средний (жёлтый)	Рекомендуется проверка
50-69	Высокий (оранжевый)	Требует проверки
70-100	Критический (красный)	Рекомендуется отклонить

Администрирование заявок

Список ожидающих заявок с цветовым кодированием риска
Одобрить → баланс списывается, создаётся транзакция withdrawal, пользователь уведомлён
Отклонить → пользователь уведомлён
Отметить “Переведено” → статус completed, пользователь уведомлён

Партнёрская система

Подача заявки

Через Cabinet API пользователь подаёт заявку на партнёрство:

Название компании (опционально)
URL сайта (опционально)
Telegram-канал (опционально)
Описание деятельности (опционально)
Ожидаемое количество рефералов в месяц (опционально)
Желаемый процент комиссии 1-100% (опционально) — отображается администратору при рассмотрении заявки

Статусы партнёра

Статус	Описание
`none`	Не подавал заявку
`pending`	Заявка на рассмотрении
`approved`	Одобрен
`rejected`	Отклонён

Одобрение партнёра

При одобрении администратор устанавливает:

Персональный процент комиссии (переопределяет глобальный)
Генерируется реферальный код (если отсутствует)
Пользователь уведомляется

Возможности партнёра

Персональный процент комиссии
Привязка рекламных кампаний — переходы по кампании автоматически делают партнёра реферером
Детальная статистика: рефералы, конверсии, доходы по периодам
Аналитика трендов (сравнение текущего и предыдущего периодов)

Управление партнёрами (админ)

Действие	Описание
Одобрить заявку	С установкой комиссии
Отклонить	С комментарием
Отозвать статус	Удаление партнёрства, очистка комиссии, отвязка кампаний
Изменить комиссию	Обновление процента
Привязать/отвязать кампанию	Управление связью партнёр-кампания

Уведомления

Событие	Получатель	Описание
Регистрация по ссылке	Реферал	Welcome + бонусы
Регистрация по ссылке	Реферер	”Новый реферал” + комиссия
Бонус за первое пополнение	Реферал	”Бонус получен!”
Награда за первое пополнение	Реферер	”Награда!” + сумма + комиссия
Комиссия с пополнения	Реферер	”Реферальная комиссия!” + сумма
Комиссия с покупки	Реферер	”Комиссия с покупки!” + сумма
Заявка на вывод	Администраторы	Детали + анализ рисков
Вывод одобрен/отклонён/переведён	Пользователь	Статус заявки

REFERRAL_NOTIFICATIONS_ENABLED=true
REFERRAL_NOTIFICATION_RETRY_ATTEMPTS=3

Реферальные конкурсы

Подробнее в разделе Конкурсы и игры.

Диагностика (админ)

Анализ логов для поиска “потерянных” рефералов (кликнул ссылку, но реферер не записался)
Аудит БД на пропущенные бонусы
Предпросмотр и применение исправлений
Синхронизация с реферальными конкурсами

Настройка

Основные параметры

Переменная	По умолчанию	Описание
`REFERRAL_PROGRAM_ENABLED`	`true`	Глобальный переключатель
`REFERRAL_COMMISSION_PERCENT`	`25`	Процент комиссии (по умолчанию)
`REFERRAL_MINIMUM_TOPUP_KOPEKS`	`10000`	Минимум для первого пополнения (100 руб)
`REFERRAL_FIRST_TOPUP_BONUS_KOPEKS`	`10000`	Бонус рефералу (100 руб)
`REFERRAL_INVITER_BONUS_KOPEKS`	`10000`	Мин. бонус рефереру (100 руб)
`REFERRAL_MAX_COMMISSION_PAYMENTS`	`0`	Максимальное количество пополнений реферала, с которых начисляется комиссия. 0 = без лимита
`SKIP_REFERRAL_CODE`	`false`	Пропуск ввода реферального кода при регистрации

Вывод средств

Переменная	По умолчанию	Описание
`REFERRAL_WITHDRAWAL_ENABLED`	`false`	Включить вывод
`REFERRAL_WITHDRAWAL_MIN_AMOUNT_KOPEKS`	`50000`	Минимум вывода (500 руб)
`REFERRAL_WITHDRAWAL_COOLDOWN_DAYS`	`30`	Cooldown между заявками (дни)
`REFERRAL_WITHDRAWAL_ONLY_REFERRAL_BALANCE`	`true`	Только реферальный баланс
`REFERRAL_WITHDRAWAL_REQUISITES_TEXT`	—	Подсказка для поля реквизитов
`REFERRAL_WITHDRAWAL_NOTIFICATIONS_TOPIC_ID`	`0`	Топик для уведомлений (0 = основной чат)
`REFERRAL_WITHDRAWAL_TEST_MODE`	`false`	Тестовый режим (пропуск cooldown, тестовые начисления)

Пороги подозрительной активности

Переменная	По умолчанию	Описание
`REFERRAL_WITHDRAWAL_SUSPICIOUS_MIN_DEPOSIT_KOPEKS`	`100000`	Порог суммы от одного реферала (1000 руб)
`REFERRAL_WITHDRAWAL_SUSPICIOUS_MAX_DEPOSITS_PER_MONTH`	`10`	Макс. пополнений от одного реферала в месяц
`REFERRAL_WITHDRAWAL_SUSPICIOUS_NO_PURCHASES_RATIO`	`3`	Соотношение пополнений к тратам

Партнёрская секция

Переменная	По умолчанию	Описание
`REFERRAL_PARTNER_SECTION_VISIBLE`	`true`	Показывать раздел партнёрства в Cabinet

​Обзор

​Механика работы

​Реферальная ссылка

​Процесс приглашения

​QR-код

​Система комиссий

​Бонус за первое пополнение

​Комиссия с пополнений

​Комиссия с покупок

​Индивидуальная комиссия

​Интерфейс пользователя

​Меню “Партнёрка”

​Список рефералов

​Аналитика

​Вывод средств

​Включение

​Пользовательский flow

​Расчёт доступного баланса

​Статусы заявки

​Анализ подозрительной активности

​Администрирование заявок

​Партнёрская система

​Подача заявки

​Статусы партнёра

​Одобрение партнёра

​Возможности партнёра

​Управление партнёрами (админ)

​Уведомления

​Реферальные конкурсы

​Диагностика (админ)

​Настройка

​Основные параметры

​Вывод средств

​Пороги подозрительной активности

​Партнёрская секция

Обзор

Механика работы

Реферальная ссылка

Процесс приглашения

QR-код

Система комиссий

Бонус за первое пополнение

Комиссия с пополнений

Комиссия с покупок

Индивидуальная комиссия

Интерфейс пользователя

Меню “Партнёрка”

Список рефералов

Аналитика

Вывод средств

Включение

Пользовательский flow

Расчёт доступного баланса

Статусы заявки

Анализ подозрительной активности

Администрирование заявок

Партнёрская система

Подача заявки

Статусы партнёра

Одобрение партнёра

Возможности партнёра

Управление партнёрами (админ)

Уведомления

Реферальные конкурсы

Диагностика (админ)

Настройка

Основные параметры

Вывод средств

Пороги подозрительной активности

Партнёрская секция