> For the complete documentation index, see [llms.txt](https://docs.graspil.com/ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graspil.com/ru/app/referral-system.md). # Реферальная система ### 1. Что это и зачем Реферальная система позволяет вашему боту отслеживать, кто кого привёл, и автоматически начислять вознаграждения тем пользователям, которые приводят новых участников. {% hint style="info" %} Реферальную систему от graspil можно подключить даже если у вас уже реализованна ваша собственная реф. система {% endhint %} **Что можно сделать с её помощью:** * **Отслеживать источники** — видеть, по каким ссылкам или меткам приходят новые пользователи. * **Вести учёт рефереров и рефералов** — знать, кто кого пригласил. * **Начислять вознаграждения** — автоматически, когда реферал совершает нужное действие (оплата, регистрация, любое другое событие вашего бота). * **Выплачивать вознаграждения** — вручную, по вебхуку или автоматически по расписанию. * **Смотреть статистику** — воронку, топ рефереров, динамику начислений, использовать реф. данные в конструкторе отчетов > **Реферер** — тот, кто приглашает (зарабатывает).\ > **Реферал** — тот, кого пригласили. *** ### 2. Режимы работы: Наблюдение и Управление При настройке реферальной системы нужно выбрать один из двух режимов. #### Наблюдение (Observe) Вы просто следите за тем, какие метки (коды) приходят в параметр `?start=` ваших ссылок. Система фиксирует переходы и связывает их с пользователями, но сама коды не генерирует и не управляет ими — это делает ваш бот самостоятельно. **Когда выбирать:** если у вас уже есть своя логика выдачи реферальных ссылок, и вы хотите просто получить аналитику и учёт переходов без смены инфраструктуры. > **Важно:** для работы начислений система должна знать, кому принадлежит код (то есть `referrer_id` реферера). В режиме «Управление» это происходит автоматически. В режиме «Наблюдение» — только если вы передаёте Telegram-id реферера напрямую (опция «Параметр = Telegram ID») или привязываете владельца кода через API (`set-code-owner`). #### Управление (Manage) Платформа берёт на себя генерацию уникальных реферальных кодов и ссылок для каждого пользователя. Вы можете настраивать правила вознаграждений, видеть балансы рефереров и делать выплаты — всё через интерфейс или API. **Когда выбирать:** если вы строите реферальную программу с нуля или хотите переложить управление кодами и выплатами на платформу. Режим управления открывает весь функционал: правила начислений, балансы, выплаты. *** ### 3. Параметр ссылки и режим передачи user\_id #### Имя параметра В настройках вы задаёте, в каком параметре ссылки передаётся реферальный код. По умолчанию это `ref`, то есть ссылка выглядит так: {% code overflow="wrap" %} ``` https://t.me/your_bot?start=ref-<код> ``` {% endcode %} Имя параметра можно изменить на любое латинское слово (только буквы и цифры). Важно, чтобы оно совпадало с тем, что передаёт ваш бот. {% hint style="info" %} Если у вас включен [упрощенный режим обработки UTM меток](/ru/app/start-utm/configuring-start.md#uproshennyi-rezhim) то все что после `start=...` будет использованно как код реферера, чтобы избежать этого выключите упрощенный режим обработки меток и используйте параметры. {% endhint %} #### Режим «Параметр = Telegram ID реферера» По умолчанию в ссылке передаётся непрозрачный код, и система сама выясняет, кому он принадлежит. Но есть альтернативный режим: ваш бот кладёт в параметр `?start=` **прямой Telegram-id** реферера (числовое значение). Включите опцию **«Параметр = Telegram ID реферера»**, если: * Ваш бот сам формирует ссылки вида `?start=`. * Вы хотите избежать отдельного слоя маппинга «код → пользователь». При включённом режиме, если в параметр пришло число, система сразу записывает реферера с известным Telegram-id — никаких промежуточных шагов. > Нечисловые значения при этом режиме обрабатываются как обычные наблюдаемые коды. #### Привязка владельца кода через API Используйте метод `POST v1/referral/set-code-owners`, чтобы сообщить системе, кому принадлежит один или несколько кодов. Метод принимает массив объектов `[{code, user_id}, ...]` и работает в двух сценариях: * **Заранее (pre-assign):** код ещё никем не использовался, вы регистрируете его с уже известным владельцем. Все будущие переходы по коду сразу привяжутся к рефереру — без дополнительных шагов. * **Постфактум (backfill):** кто-то уже перешёл по коду, но владелец не был известен. Система задним числом проставляет реферера для всех прошлых переходов. Передавать коды можно одним запросом пачкой, что удобно при инициализации реферальной программы. *(Документацию по методам API см. в разделе API.)*
*** ### 4. Активация и создание реферальных кодов #### Активация Реферальная система по умолчанию отключена. Чтобы включить её: 1. Перейдите в раздел **Реферальная система → Настройки → Основные**. 2. Выберите режим (Наблюдение или Управление). 3. Укажите имя параметра (или оставьте `ref`). 4. Нажмите **Активировать**. После активации раздел открывается полностью. #### Создание реферальных кодов (режим «Управление») В режиме «Управление» каждый реферер получает уникальную ссылку. Есть несколько способов её получить: 1. **Через интерфейс.** Откройте карточку реферера (раздел «Рефереры» → нужный пользователь). Там отображается его персональная реферальная ссылка и кнопка «Копировать». 2. **Через API.** Метод `GET referral/default/referrer-code?key=&user_id=` возвращает ссылку для конкретного пользователя. Если кода ещё нет — он создаётся автоматически. Удобно вызывать прямо из вашего бота, чтобы выдавать ссылку пользователю по команде «Моя реферальная ссылка». 3. Через Автоматизацию. Вы можете создать автоматизацию которая будет отправлять его код реферера напрямую в телеграм бот. *** ### 5. Разделы системы После активации в меню появляется раздел «Реферальная система» с подразделами:
РазделЧто здесь
ОбзорСводная панель: ключевые цифры, воронка, топ рефереров, мини-графики
НастройкиРежим, параметр ссылки, правила начислений, настройки выплат
РеферерыСписок всех, кто приводит пользователей, с балансами и статистикой
РефералыСписок приведённых пользователей с указанием реферера
НачисленияПолная история начислений (леджер) со статусами
ВыплатыИстория выплат, ручные операции, статусы
СтатистикаГрафики и таблицы: динамика, воронка, топы
*** ### 6. Правила начислений Правила — это сердце реферальной программы. Каждое правило описывает: **за какое событие**, **сколько** начислять рефереру, и **что ещё сделать** (опционально). #### Как создать правило Перейдите в **Настройки → Правила вознаграждений** и нажмите «Добавить правило». #### Что настраивается в правиле **Название** — произвольное, для вашего удобства. **Статус** — правило можно включить или выключить, не удаляя. **Триггер-событие** — какое событие реферала запускает начисление. Это любое событие вашего бота: оплата, подписка, прохождение шага в боте и т.д. Выбирается из списка типов событий, которые платформа уже знает для вашего бота. {% hint style="info" %} Вы можете создать/инициировать событие любым удобным способом, через: API, правила обработки сообщений бота {% endhint %} **Условия по значению события** — дополнительный фильтр: например, «событие оплаты, но только если сумма ≥ 1000». Поля: минимальное значение, максимальное значение, точное значение. Все необязательные. **Тип вознаграждения:** * **Фиксированное** — реферер получает конкретную сумму в выбранной вами валюте (например, 100 монет за каждую оплату реферала). * **Процент** — реферер получает процент от суммы события (например, 10% от оплаты реферала). Валюта берётся из самого события. * **Внешнее** — платформа не считает сумму сама, а просто уведомляет ваш сервер через вебхук. Удобно, если логика начисления (например, продление доступа) реализована на вашей стороне. **Период выдержки (hold\_days)** — сколько дней начисление находится в статусе «на выдержке» прежде, чем стать доступным к выплате. Полезно, если у вас есть возвраты: начисление не уйдёт в выплату раньше, чем истечёт срок возврата. {% hint style="info" %} Установите **hold\_days = 0 если не требуется выдержка** {% endhint %} **Побочные эффекты** — дополнительные действия при каждом начислении: * **Вебхук** — платформа отправляет POST-запрос на указанный URL с данными о начислении. Вы задаёте шаблон тела запроса с подстановкой переменных (`{{referrer_id}}`, `{{amount}}`, `{{event_value}}` и др.). * **Кастомное поле** — увеличить (`inc`) или установить (`set`) значение [кастомного поля ](/ru/app/custom-fields.md)пользователя-реферера в вашем боте. Например, можно хранить накопленный баланс прямо в профиле пользователя. #### Приоритет правил Если для одного события могут сработать несколько правил — порядок применения определяется приоритетом. Правила с меньшим числом проверяются первыми. *** ### 7. Выплаты Когда у реферера накопился одобренный баланс, его можно выплатить. #### Способы выплат Настраиваются в **Настройки → Выплаты**. **Ручной (Manual)** — вы сами переводите деньги пользователю любым удобным способом, после чего отмечаете выплату в системе как «Оплачена» или «Неуспешная» (с комментарием). Платформа просто ведёт учёт. **Вебхук (Webhook)** — при инициировании выплаты платформа автоматически отправляет POST-запрос на ваш URL с данными «зачисли X в валюте Y пользователю Z». Ваш сервер зачисляет средства и возвращает ответ; платформа помечает выплату как выполненную или неуспешную. Этот способ подходит, если у вас есть внутренний кошелёк или платёжная система. **Криптовалюта и другие способы** — в разработке, скоро. {% hint style="info" %} Напишите нам с какой платформой вам требуется интеграция, добавим в оперативном порядке :) {% endhint %} #### Как инициировать выплату * **Из карточки реферера** — выберите валюту и способ, нажмите «Выплатить». Платформа возьмёт весь доступный баланс по выбранной валюте. * **Из раздела «Выплаты»** — кнопка «Создать выплату», выбор реферера, валюты и способа. * **Через публичный API** (`POST v1/referral/payout`) — ваш бот может дать пользователю кнопку «Вывести», при нажатии которой сам инициирует выплату. #### Автоматические выплаты Включите в **Настройки → Выплаты → Авто-выплаты**: * **Расписание** — ежемесячно или каждые N дней. * **Способ** — manual или webhook (применяется для всех авто-выплат). * **Минимальный порог по валюте** — выплата создаётся только если доступный баланс в данной валюте достиг нужной суммы. Настраивается отдельно для каждой валюты. Авто-выплаты работают независимо от ручных: ручные и через API всегда доступны, даже без включённого расписания. #### Жизненный цикл выплаты {% code overflow="wrap" %} ``` Запрошена → В обработке → Выполнена ↘ Неуспешная (возвращается в баланс) ``` {% endcode %} *** ### 8. Баланс и статусы начислений Баланс реферера ведётся отдельно по каждой валюте (без автоматической конвертации). #### Статусы начислений
СтатусЧто значит
На выдержкеНачислено, но ещё не прошёл период удержания (hold_days). Пока нельзя выплатить
ПодтвержденоГотово к выплате (доступный баланс)
В выплатеЗарезервировано под текущую выплату
ВыплаченоУшло в выплату
ВозвращеноКомпенсирующее начисление (возврат)
ОтмененоАннулировано
#### Из чего складывается баланс реферера * **Доступно** — сумма подтверждённых начислений, не привязанных к выплате. Это то, что можно выплатить прямо сейчас. * **Зарезервировано** — подтверждённые начисления, уже включённые в текущую выплату (в процессе). * **На выдержке** — ещё не прошёл период удержания. * **Выплачено** — итоговая сумма всех успешных выплат. *** ### Частые вопросы **Могу ли я работать в режиме «Наблюдение» и потом переключиться на «Управление»?**\ Да, режим можно изменить в любой момент в настройках. Накопленная история переходов сохраняется. **Могу ли я начислять в нескольких валютах?**\ Да. Для каждого правила задаётся своя валюта. Баланс реферера ведётся по каждой валюте отдельно, без конвертации. **Одно правило или несколько для одного события?**\ Можно создать несколько правил для одного типа события — например, разные ставки в зависимости от суммы (используйте условия `value_min`/`value_max`). Приоритет определяет порядок проверки. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.graspil.com/ru/app/referral-system.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.