Skip to main content

​
Обзор

Реферальная программа позволяет пользователям приглашать новых клиентов и зарабатывать комиссию с их пополнений и покупок. Включает партнёрскую систему для профессиональных рефереров. 
REFERRAL_PROGRAM_ENABLED=true
При отключении:
  • Кнопки “Партнёрка”, “Мои рефералы” скрываются из меню
  • Административные функции остаются доступными

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

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

Каждый пользователь получает уникальный реферальный код формата refAbC12dEf (3 + 8 символов) и ссылку: 
https://t.me/{bot_username}?start=refAbC12dEf

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

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

​
QR-код

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

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

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

При первом пополнении реферала на сумму >= REFERRAL_MINIMUM_TOPUP_KOPEKS:
ПолучательБонус
Реферал (новый пользователь)REFERRAL_FIRST_TOPUP_BONUS_KOPEKS на баланс
Реферер (пригласивший)max(REFERRAL_INVITER_BONUS_KOPEKS, комиссия%)
Если пополнение меньше минимума — реферер получает только комиссию, бонус за первое пополнение откладывается.

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

С каждого пополнения реферала (включая первое и последующие): 
Комиссия = сумма_пополнения × REFERRAL_COMMISSION_PERCENT / 100

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

С каждой покупки подписки: 
Комиссия = сумма_покупки × 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

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

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

Если REFERRAL_WITHDRAWAL_ONLY_REFERRAL_BALANCE=true (по умолчанию):
  • Доступны только реферальные доходы
  • Собственные пополнения не учитываются
Если 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Критический (красный)Рекомендуется отклонить

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

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

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

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

Через Cabinet API пользователь подаёт заявку на партнёрство:
  • Название компании (опционально)
  • URL сайта (опционально)
  • Telegram-канал (опционально)
  • Описание деятельности (опционально)
  • Ожидаемое количество рефералов в месяц (опционально)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

​
Настройка

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

ПеременнаяПо умолчаниюОписание
REFERRAL_PROGRAM_ENABLEDtrueГлобальный переключатель
REFERRAL_COMMISSION_PERCENT25Процент комиссии (по умолчанию)
REFERRAL_MINIMUM_TOPUP_KOPEKS10000Минимум для первого пополнения (100 руб)
REFERRAL_FIRST_TOPUP_BONUS_KOPEKS10000Бонус рефералу (100 руб)
REFERRAL_INVITER_BONUS_KOPEKS10000Мин. бонус рефереру (100 руб)
SKIP_REFERRAL_CODEfalseПропуск ввода реферального кода при регистрации

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

ПеременнаяПо умолчаниюОписание
REFERRAL_WITHDRAWAL_ENABLEDfalseВключить вывод
REFERRAL_WITHDRAWAL_MIN_AMOUNT_KOPEKS50000Минимум вывода (500 руб)
REFERRAL_WITHDRAWAL_COOLDOWN_DAYS30Cooldown между заявками (дни)
REFERRAL_WITHDRAWAL_ONLY_REFERRAL_BALANCEtrueТолько реферальный баланс
REFERRAL_WITHDRAWAL_REQUISITES_TEXT—Подсказка для поля реквизитов
REFERRAL_WITHDRAWAL_NOTIFICATIONS_TOPIC_ID0Топик для уведомлений (0 = основной чат)
REFERRAL_WITHDRAWAL_TEST_MODEfalseТестовый режим (пропуск cooldown, тестовые начисления)

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

ПеременнаяПо умолчаниюОписание
REFERRAL_WITHDRAWAL_SUSPICIOUS_MIN_DEPOSIT_KOPEKS100000Порог суммы от одного реферала (1000 руб)
REFERRAL_WITHDRAWAL_SUSPICIOUS_MAX_DEPOSITS_PER_MONTH10Макс. пополнений от одного реферала в месяц
REFERRAL_WITHDRAWAL_SUSPICIOUS_NO_PURCHASES_RATIO3Соотношение пополнений к тратам

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

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