Действие «Реферальная система»

«Реферальная система в Telegram/MAX» — действие в сценарии действий, которое реализует полноценную партнёрскую программу: реферальные ссылки, начисление баллов, многоуровневая структура (реферал, реферер реферера, и т.д.), выплаты.

Поддерживает классическую схему «привёл друга → получил награду» и сложные MLM-структуры с 2-10 уровнями.

Когда использовать

• Реферальная программа: «Приведи друга — получи 100 ₽».
• Партнёрская сеть: проценты от заказов рефералов.
• Геймификация: накопление баллов за приглашения, обмен на бонусы.
• MLM: многоуровневые выплаты за глубину сети.

Термины

Термин	Что означает
Реферер	Тот, кто пригласил (вышестоящий)
Реферал	Тот, кого пригласили (нижестоящий)
Уровень	Глубина в сети. 1 — прямые рефералы; 2 — рефералы рефералов
Баланс рефералов	Сумма, начисленная нижестоящим
Баланс рефереров	Сумма, начисленная вышестоящим

---

Часть 1. Структура действия

В сценарии действий → «Добавить действие» → «Реферальная система в Telegram/MAX».

Внутри действия — несколько операций (как в «Операциях с данными»). Доступно 13 операций:

Операция	Назначение
Получить реферальную ссылку	Уникальная ссылка для подписчика
Добавить/Отнять баллы	Изменить баланс одного клиента
Добавить/Отнять баллы по уровням	Начислить рефералам на N уровнях вверх
Произвести выплату	Зафиксировать выплату одному клиенту
Произвести выплаты по уровням	Выплаты по структуре
Получить количество рефералов	Сколько пригласил клиент
Получить общий баланс рефералов	Сумма баллов всех рефералов
Получить общий баланс рефереров	Сумма баллов цепочки вверх
Получить общие выплаты рефералам	Сколько уже выплачено
Получить общие выплаты реферерам	Аналогично вверх
Получить данные рефералов	Массивы по подписчикам-рефералам
Получить данные рефереров	Массивы по рефереров
Получить число уровней реферальной системы	Глубина настроенной системы

Скриншот 1. Список операций.

---

Часть 2. Реферальная ссылка

Операция «Получить реферальную ссылку»

Возвращает уникальный URL вида https://link.quescha.com/invite/:code. По нему перешедший попадает в бот и автоматически прикрепляется как реферал.

Где использовать:

• В блоке «Пригласи друга» — кнопка-ссылка с URL = переменная ссылки;
• В сообщении: Ваша реф-ссылка: #{ref_link};
• В QR-кодах для оффлайн-распространения.

Сохраните в переменную (например, ref_link).

---

Часть 3. Начисление баллов

Операция «Добавить/Отнять баллы»

Меняет баланс одного подписчика. Подставьте сумму:

• 100 — добавить 100;
• -50 — отнять 50;
• #{order_sum} * 0.1 — 10% от заказа (через выражение {{ #{order_sum} * 0.1 }}).

Целевой клиент — текущий подписчик. Если нужно начислить рефереру клиента — см. следующую операцию.

Операция «Добавить/Отнять баллы по уровням»

Многоуровневое начисление. Заполните:

• Сумма на каждом уровне;
• От уровня — с какого уровня начинать (обычно 1);
• До уровня — до какого уровня закончить (1 = только прямой реферер, 3 = три уровня вверх).

Кейс: 10% прямому рефереру (уровень 1), 5% его рефереру (уровень 2):

• Уровень 1: {{ #{order_sum} * 0.1 }};
• Уровень 2: {{ #{order_sum} * 0.05 }}.

Скриншот 2. Начисление по уровням.

Галочка «Рефералам подписчика» — начисление идёт вниз (тем, кого подписчик пригласил), а не вверх.

---

Часть 4. Выплаты

Операция «Произвести выплату»

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

Используется когда:

• клиент запросил вывод бонусов;
• автоматически выплачены проценты через CRM/банк.

Операция «Произвести выплаты по уровням»

Аналогично начислению по уровням — массовая выплата по структуре.

Это учёт, не реальные деньги

Действие меняет внутренние балансы Квесчи. Реальный перевод денег делается через HTTP-запрос в платёжный шлюз или действие «Платежи» отдельно.

---

Часть 5. Чтение данных

Простые счётчики

Операция	Что вернёт
Получить количество рефералов	Число прямых рефералов подписчика
Получить общий баланс рефералов	Сумма всех баллов рефералов
Получить общий баланс рефереров	Сумма всех баллов вверх по цепочке
Получить общие выплаты рефералам	Сколько выплачено вниз
Получить общие выплаты реферерам	Сколько выплачено вверх
Получить число уровней	Глубина настроенной системы

Используйте в сообщении: Вы пригласили #{ref_count} человек. Заработали #{ref_balance} ₽.

Массивы данных рефералов

«Получить данные рефералов» возвращает сразу несколько массивов:

Массив	Содержит
ClientID рефералов	Массив ID
Messenger рефералов	telegram, max, ...
BotID рефералов	ID бота
Балансы рефералов	Баланс каждого
Выплаты рефералов	Выплаты каждого
Уровни рефералов	На каком уровне (1/2/3)
ClientLink рефералов	Ссылка на профиль
FullName рефералов	Полное имя
Name рефералов	Имя

Можно ограничить «От уровня» / «До уровня» для выборки одного среза.

После — перебор массива в «Операциях с данными» для формирования строки списка.

Скриншот 3. Параметры операции «Получить данные рефералов».

---

Часть 6. Типовой сценарий

Минимальная программа «Приведи друга»

Блок 1. «Пригласи друга»
  Сценарий действий «До»:
    - Реферальная система → «Получить реф-ссылку» → ref_link
  Сообщение: «🎁 Приглашай друзей и получай 100 ₽ за каждого.
              Твоя ссылка: #{ref_link}»

Триггер «При подписке нового реферала»:
  (срабатывает автоматически в системе Квесчи, если есть реферер)
  Сценарий действий «До»:
    - Реферальная система → «Добавить баллы по уровням»: 
        уровень 1 — сумма 100
  Сообщение рефереру: «🎉 У вас новый реферал! +100 баллов»

Блок «Мой баланс»:
  Сценарий действий «До»:
    - Реферальная система → «Получить количество рефералов» → ref_count
    - Реферальная система → «Получить общий баланс рефералов» → ref_total
  Сообщение: «Друзей: #{ref_count}
              Баланс: #{ref_total} ₽»

Блок «Вывести»:
  Сценарий действий «До»:
    - Реферальная система → «Произвести выплату» на сумму #{ref_total}
    - HTTP-запрос в банк/шлюз — реальное списание
  Сообщение: «Заявка на вывод #{ref_total} ₽ принята.»

---

Часть 7. Продвинутые сценарии

Сценарий 1. Процент с заказа другу

После оплаты заказа клиентом:

1. В цепочке приёма платежа → действие реферальной системы → «Добавить баллы по уровням», сумма = {{ #{paid_sum} * 0.1 }}, уровень 1.
2. Прямой реферер получит 10% от заказа автоматически.

Сценарий 2. Геймификация — топ-5 рефералов

1. В блоке «Рейтинг» → «Получить данные рефералов» → массивы Name, ref_count.
2. Через JS код отсортируйте по количеству.
3. Покажите топ-5 в сообщении.

Сценарий 3. Бонус за рефералов второго уровня

Структура: вы → ваш реферал → его реферал.

При действиях клиента второго уровня:

• Прямому рефереру — 50 ₽ (уровень 1);
• «Дедушке» — 20 ₽ (уровень 2).

Настройка: «Добавить баллы по уровням» с разными суммами на каждом уровне.

Сценарий 4. Бан реферала за нарушения

Если клиент-реферал «накручен» (фейк, спам):

1. Действие «Добавить/Отнять баллы по уровням» с отрицательной суммой.
2. Это снимет баллы с реферера.

Сценарий 5. «Лидерборд» по выплатам

1. «Получить данные рефералов» → массивы ClientID, Balance, Paid.
2. Сохранение в список «Аналитика рефералов» с датой.
3. Через неделю — сравнение для отчёта.

---

Часть 8. Архитектура

Принцип 1. Реферальная ссылка — в первом контакте

Кнопка «Пригласить друга» — в приветственном сценарии. Чем раньше клиент увидит — тем выше вовлечённость.

Принцип 2. Уведомляйте реферера сразу

Когда подписался новый реферал — отправьте уведомление вверх через триггер «при подписке» с проверкой наличия реферера.

Принцип 3. Выплаты по уровням редко больше 3

Многоуровневые структуры свыше 3 уровней — это уже MLM, под которые нужны юристы и согласование. 1-2 уровня для большинства задач достаточно.

Принцип 4. Учёт в Квесче, расчёт в CRM/банке

Реферальная система Квесчи считает баланс, но не отправляет деньги. Для реальных выплат подключайте платёжные шлюзы через HTTP или CRM.

Принцип 5. Защита от накруток

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

Принцип 6. Логируйте операции

Каждое начисление/выплату дублируйте в список «Реф-операции» с датой, ClientID, суммой. Это нужно для разрешения споров.

---

Часть 9. Частые ошибки

• Ссылка возвращается, но реферал не привязывается — клиент уже был в боте раньше. Реферер фиксируется только при первой подписке.
• Уровень начисления неверный — проверьте в optionsReferal, что «От уровня» меньше или равен «До уровня».
• Баланс отрицательный — операция «Произвести выплату» списывает, даже если баланса нет. Добавляйте проверку #{balance} >= #{withdrawal} до выплаты.
• Реферер не получил уведомление — нет цепочки с триггером «при добавлении тега новый-реферал».
• Массивы рефералов пустые — у клиента нет рефералов, или вы фильтруете по уровню, на котором никого нет.

---

Что дальше

• Платежи — реальные выплаты через шлюз.
• HTTP-запросы — для внешних расчётов.
• Списки — учёт операций.
• Цепочки — уведомления при новых рефералах.
• Шаблоны замен — [ClientLink], [FullName], [Name] для оформления.