Рефералка и выводы
У каждого пользователя есть уникальный реферальный код и персональная ссылка вида https://t.me/<бот>?start=ref_<код>. Экран «🎁 Рефералка» в боте показывает ссылку (тап — копирование), число приглашённых, кнопку «📤 Поделиться» и — если включены выводы — доступную к выводу сумму с кнопкой «💸 Вывести».
Привязка по диплинку
Реферал привязывается на первом /start нового пользователя: параметр ref_<код> находит владельца кода и создаёт связь. Правила жёсткие:
- один реферер на пользователя — повторные ссылки уже привязанного юзера игнорируются;
- привязать самого себя нельзя;
- у существующего пользователя (не первый
/start) привязка не срабатывает.
Кроме ref_ бот понимает partner_<код> — партнёрскую ссылку: новый юзер привязывается к аккаунту владельца партнёрского кода и дальше работает та же реферальная механика.
Награды
Две независимые награды, обе выдаются автоматически, когда реферал приносит деньги:
| Награда | Когда | Настройка |
|---|---|---|
| Процент с пополнений | с каждого пополнения баланса и оплаты подписки реферала | REFERRAL_PERCENT (по умолчанию 10%) |
| +N дней обоим | один раз — когда реферал впервые приносит деньги | REFERRAL_BONUS_DAYS (по умолчанию 7) |
Процент зачисляется на баланс реферера и пишется в историю как транзакция «Реф. бонус». Если у конкретного пользователя задан индивидуальный процент (поле referral_commission_percent, приезжает, например, при миграции с Bedolaga), он перекрывает общий.
Бонусные дни добавляются к подписке и пригласившему, и другу. Сторона без действующей подписки просто не получает дни — это мягкий отказ, а не ошибка: комиссия и бонус второй стороне всё равно выдаются.
Выплата at-most-once
Каждая выплата привязана к конкретной транзакции пополнения: повторная доставка платёжного вебхука не задваивает комиссию, а разовый бонус дней защищён уникальным маркером в леджере — два воркера одновременно не выдадут его дважды. Каждая выдача фиксируется строкой ReferralEarning в БД.
Вывод заработка
По умолчанию выключен. Включается в настройках кабинета:
| Ключ | По умолчанию | Что делает |
|---|---|---|
REFERRAL_ENABLED | вкл | реферальная программа в целом |
REFERRAL_WITHDRAWAL_ENABLED | выкл | кнопка «Вывести» в рефералке |
REFERRAL_WITHDRAWAL_MIN | 50000 коп. (500 ₽) | минимальная сумма для вывода |
Доступно к выводу — min(баланс, заработано рефералкой − уже выведенное и зарезервированное в заявках): вывести можно только реферальный заработок, а не пополнения.
Флоу в боте:
- «💸 Вывести» — бот проверяет, что вывод включён и сумма не ниже минимума.
- Выбор способа: 💳 Карта, 🪙 USDT (TRC-20) или 💎 TON.
- Реквизиты одним сообщением (минимум 8 символов).
- Заявка создана: выводится вся доступная сумма разом, деньги сразу списываются с баланса в резерв — повторно потратить их нельзя. Админы получают уведомление в топик «payments».
Обработка заявок админом
Заявки живут в кабинете: Платежи → Выводы (вкладка показывает счётчик необработанных). По каждой видно юзера, сумму, способ, реквизиты и статус: pending / paid / rejected.
- Выплачено — вы перевели деньги вручную, статус фиксирует факт выплаты; юзеру в личку уходит «✅ Выплата по заявке #N отправлена».
- Отклонено — сумма автоматически возвращается на баланс; юзер получает уведомление с вашим комментарием (до 256 символов).
Гонки исключены
Двойной клик или два админа на одной заявке — второй запрос получит 409 «already processed»: заявка блокируется на время обработки, и возврат при отклонении не задвоится.