Обзор
Реферальная программа позволяет пользователям приглашать новых клиентов и зарабатывать комиссию с их пополнений и покупок. Включает партнёрскую систему для профессиональных рефереров.
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 |
