Как работает реферальная программа

Реферальная программа — вид сотрудничества между клиентом и провайдером, при котором клиент получает реферальную ссылку или промокод. Такой клиент считается партнёром или реферером, а новые клиенты, которые зарегистрировались по этой ссылке (промокоду), — рефералами. Партнёр получает процент от расходов своих рефералов.

По промокоду можно привязать только нового клиента, у которого нет услуг.

Результаты реферальной программы:

партнёр получает прибыль за счёт привлечённых клиентов;
провайдер получает новых клиентов и рекламу силами партнёра.

О том, как создать реферальную программу см. в статье Реферальная программа. Общая информация.

Информация в данной статье актуальна для версии BILLmanager выше 6.135. Информация о том, как работает реферальная программа в версиях ниже, см. в статье Как работает реферальная программа (для версий 6.134 и ниже)

Настройка интеграции с сайтом

Чтобы настроить интеграцию реферальной программы с сайтом, при создании реферальной программы укажите URL сайта в настройках:

если URL сайта — это адрес BILLmanager, дополнительных действий не требуется. Платформа будет автоматически извлекать значение параметра из запроса и регистрировать переход по реферальной ссылке;
если URL — сторонний сайт, со стороны сайта выполните запрос к платформе следующего вида:

https://bill_address?func=referralprogram.registerclick&p=https%3A%2F%2Fsite.com%2F%3Ffrom%3D2&r=https%3A%2F%2Freferrer.com%2Fpage&out=xjson

Где:

- bill_address — доменное имя сервера с платформой;
- func=referralprogram.registerclick — функция, регистрирующая переход по реферальной ссылке;
- &p=адрес_сайта — URL-кодированная ссылка, по которой перешёл клиент. Специальные символы должны быть заменены на коды в соответствии с процентным кодированием. Процентное кодирование (или URL-кодирование) — способ безопасно передавать специальные символы в ссылках (URL). Например, для URL https://site.com/?from=2 укажите &p=https%3A%2F%2Fsite.com%2F%3Ffrom%3D2. Этот адрес указан в личном кабинете реферера и предоставляется им потенциальным рефералам;
  
  Значение параметра p должно точно соответствовать ссылке, указанной в настройках реферальной программы — поле URL сайта, иначе переход не будет зарегистрирован. Например, если программа настроена на корень домена https://example.ru/, а в параметре передаётся адрес с путём .../catalog/.
  Для универсальной настройки рекомендуется нормализовать адрес: оставьте только протокол и домен, удаляя путь и параметры.
- &r=referrer_url — URL-кодированная ссылка на страницу, с которой клиент перешёл на текущую (значение `HTTP_REFERER`). Параметр передаётся для отслеживания источника перехода. Для получения значения используйте свойство `document.referrer` в JavaScript. Если реферер отсутствует, параметр можно не передавать.
- out=xjson — формат ответа.

Платформа регистрирует переход и возвращает уникальный идентификатор в поле doc["cntid"]["$"] JSON-ответа. Полученный идентификатор сохраняется на стороне сайта и передаётся параметром при последующем редиректе в BILLmanager.

Пример с нормализацией

Пример HTML-страницы с интеграцией реферальной программы и кнопкой перехода в BILLmanager:

<html>
<head>
    <script type="text/javascript">
        function getBillCntid() {
            var req = new XMLHttpRequest();
            req.responseType = 'json';
            req.onload = function() {
                if (req.status == 200) {
                    var json = req.response;
                    var doc = json.doc;
                    if (doc["cntid"]) {
                        // Сохранение cntid в localStorage
                        localStorage.setItem("bill_cntid", doc["cntid"]["$"]);
                    }
                }
            }
            
            // Формирование адреса для параметра p
            var referralParam;
            
            // Нормализация ссылки: оставляем только протокол и домен
            // Это гарантирует совпадение с настройками реферальной программы,
            // даже если пользователь перешёл на страницу с путём (например, /catalog/)
            if (typeof URL === "function") {
                var urlObj = new URL(window.location.href);
                urlObj.pathname = "/";   // сбрасываем путь к корню
                urlObj.search = "";      // опционально: убираем параметры запроса
                referralParam = encodeURIComponent(urlObj.toString());
            } else {
                // Fallback для старых браузеров: используем как есть
                referralParam = encodeURIComponent(window.location.href);
            }
            
            // Замените bill.example.com на адрес вашей платформы
            var billUrl = "https://bill.example.com/billmgr";
            
            // Отправка запроса
          
            req.open("GET", billUrl +
            "?func=referralprogram.registerclick&p=" + encodeURIComponent(window.location.href) + "&r=" +  encodeURIComponent(document.referrer)  + "&out=xjson", true);
req.send(null);
        }
        if (!localStorage.hasOwnProperty("bill_cntid")) {
            getBillCntid();
        }
    </script>
</head>
<body>
    <script type="text/javascript">
        function gotoBillManager() {
            // Замените bill.example.com на адрес вашей платформы
            var url = "https://bill.example.com/billmgr";
            // Если нашли идентификатор подключения к реферальной программе (bill_cntid) в localStorage, то добавляем параметром:
            if (localStorage.getItem("bill_cntid") !== null) {
                url += "?cntid=" + localStorage.getItem('bill_cntid');
            }
            window.location.href = url;
        }
    </script>
    <input type="button" onclick="gotoBillManager();" value="Go to BILLmanager">
</body>
</html>

Пояснения к HTML-коду

Таблицы БД

Таблица referralprogram содержит информацию о реферальных программах:

name	project	url	promocode	account_group	account_group_restrict	assign_by_default	start_date	end_date
Referral Program	1	`https://example.com/ref`	PROMO2025	5	10	1	2025-01-01	2025-12-31

Пояснения к таблице БД

Таблица referralprogram_rule содержит правила реферальных программ, задаваемые для конкретной реферальной программы:

referralprogram	reward_value_fixed	reward_value_percent	reward_max_amount	reward_months_after	reward_expense_period	reward_period	reward_payment_interval	status
1	0.00	10.00	5000.00	1	1	12	1	0

Пояснения к таблице БД

Таблица referralprogram_condition содержит условия, задаваемые для конкретного правила реферальной программы:

referralprogram_rule	ctype	cgroup	comparison	amount	orderperiods	item_count	referral_count	product_tree	status
1	1	0	ge	10000.00	3	NULL	NULL	NULL	0

Пояснения к таблице БД

Таблица referralprogram_click фиксирует переходы к реферальной программе:

referer_account	referral_account	ip	sesid	site	cdate	project
101	205	192.168.1.100	a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8	`https://example.com/ref?ref=101`	2025-11-01 14:30:00	1

Пояснения к таблице БД

Таблица referralprogram_referer устанавливает связь реферера с реферальной программой:

account	project	referralprogram
101	1	3

Пояснения к таблице БД

Таблица referralprogram_link устанавливает связь реферера, реферала и реферальной программы:

referer_account	referral_account	referralprogram
101	205	3

Пояснения к таблице БД

Таблица referralprogram_reward содержит информацию о вознаграждениях по реферальной программе:

referralprogram	referralprogram_rule	referral_account	referer_account	amount	currency	expense	payment	cdate
3	1	205	101	1250.00	RUB	5001	7890	2025-11-05 10:15:00

Пояснения к таблице БД

Переход клиента по реферальной ссылке

Учёт переходов по ссылке

При переходе по реферальной ссылке BILLmanager делает запись в базу:

Запись в таблицу БД

INSERT INTO referralprogram_click (cdate, ip, method, project, referer_account, referralprogram, sesid, site) VALUES('2025-11-10 03:28:25', '10.4.202.1', '2', '2', '2', '7', '1762745305.hvtgBc', 'http://localhost:8080/?from=2')

Пояснения к записи в базу

Если у клиента в браузере не было сессии, реферал будет привязан, но запись в таблице не будет создана. Такое может быть, например, при режиме инкогнито или при использовании прокси.

Логи переходов по реферальной ссылке находятся в файле /usr/local/mgr5/var/counter.log.

Регистрация нового клиента по реферальной ссылке

Добавление нового пользователя в качестве потенциального реферера:
Запись в таблицу БД
```
INSERT INTO referralprogram_referer (account, project, referralprogram) VALUES('44', '2', '5')
```
Пояснения к записи
- account — идентификатор лицевого счёта клиента, который станет реферером;
- project — код провайдера;
- referralprogram — идентификатор реферальной программы.
Добавление связи зарегистрированного клиента-реферала с реферером и реферальной программой:
Запись в таблицу БД
```
INSERT INTO referralprogram_link (cdate, referer_account, referral_account, referralprogram) VALUES('2025-11-10', '2', '43', '1')
```
Пояснения к записи в базу
- cdate — дата регистрации реферала;
- referer_account — идентификатор клиента-реферера;
- referral_account — идентификатор реферала;
- referralprogram — идентификатор реферальной программы. Например, 1.

Добавление ID реферала в referralprogram_click:

Запись в таблицу БД

SELECT * FROM referralprogram_click WHERE referer_account = 2 AND sesid = '1762745305.hvtgBc' FOR UPDATE
UPDATE referralprogram_click SET referral_account='44', referralprogram='1' WHERE referer_account='2' AND sesid='1762745305.hvtgBc'

Начисление вознаграждения

По умолчанию вознаграждения за реферальную программу начисляются по заданию в cron первого числа каждого месяца в 03:10 по времени сервера:

Задание в cron

10 3 1 * *      /usr/local/mgr5/sbin/billmaintain --command affiliatemonthly >/dev/null 2>&1

При начислении вознаграждения за реферальную программу BILLmanager:

Обнаруживает новое вознаграждение и выполняет запрос:

Пример запроса

Aug  1 12:00:47 [134624:19] core_module INFO Request [billmaintain][root] 'func=referralprogram.createreward&out=xml&referer_account=49&referral_expense=538&referralprogram_rule=11&reward_amount=100.00&reward_cdate=2025%2D08%2D01'

Отправляет SQL-запрос на создание записи о вознаграждении в базу данных:
Запись в таблицу БД
```
INSERT INTO referralprogram_reward (amount, cdate, currency, expense, id, referer_account, referral_account, referralprogram, referralprogram_rule) VALUES('100.0000', '2025-08-01', '126', '538', '308', '49', '50', '9', '11')
```
Пояснения к записи в базу
- amount — сумма вознаграждения;
- cdate — дата начисления вознаграждения;
- currency — код валюты. Например, 126 соответствует евро, 810 — российскому рублю;
- expense — идентификатор расхода реферала, на основе которого начислено вознаграждение;
- id — уникальный идентификатор записи о вознаграждении;
- referer_account — идентификатор клиента-реферера;
- referral_account — идентификатор клиента-реферала;
- referralprogram — идентификатор реферальной программы;
- referralprogram_rule — правило реферальной программы, по которому применено вознаграждение.

Если дата зачисления вознаграждения совпадает с текущей датой, создаётся платёж:

Пример запроса

Aug  1 12:00:47 [134624:20] core_module INFO Request [billmaintain][root] 'func=referralprogram.createpayment&out=xml&referer_account=49&referralprogram=9&reward_date=2025%2D08%2D01'

Выполняется SQL-запрос на создание платежа:
Пример записей в БД
```
INSERT INTO payment (createdate, currency, id, paymethodamount, randomnumber, status, subaccount, subaccountamount, usedamount) VALUES('2025-08-01 12:00:47', '126', '585', '100.0000', 'mRj2cTHawIeA', '1', '46', '100.0000', '0.0000')
```
Пояснения к записи в базу
- createdate — дата и время создания платежа;
- currency — код валюты платежа;
- id — уникальный идентификатор платежа;
- paymethodamount — сумма в валюте метода оплаты;
- randomnumber — уникальный внутренний номер платежа;
- status — статус платежа. Например, 1 — новый, 4 — зачислен и т.д.;
- subaccount — лицевой счёт реферера, на который зачисляется вознаграждение;
- subaccountamount — сумма в валюте лицевого счёта;
- usedamount — израсходованная часть платежа.

Обработка реферальных связей при объединении клиентов

При объединении двух клиентов система применяет следующие правила:

сохранение и дополнение связей: текущие связи основного клиента (статус реферера или реферала) сохраняются в полном объёме. При этом к основному клиенту переносятся все рефералы и рефереры присоединяемого клиента, которых у основного ещё не было;
перенос данных: если основной клиент не участвует в программе, система переносит реферальные связи из присоединяемого клиента;
сохранение вознаграждений: система сохраняет все фактические и планируемые вознаграждения обоих клиентов, даже если они ещё не начислены;
разрыв циклических связей: если клиенты были реферером и рефералом друг для друга, система удаляет эту связь. Остальные их реферальные связи сохраняются;
разделение по провайдерам: при наличии связей с разными провайдерами система сохраняет независимые записи для каждого провайдера.

Примеры

Пример 1. Основной клиент — реферер, а присоединяемый клиент — реферал без собственных рефералов

После объединения основной клиент сохраняет статус реферера. Поскольку у присоединяемого клиента нет своих рефералов, переносить некого. Основной клиент становится рефералом для того, кто ранее привлекал присоединяемого клиента.

До объединения:

Клиент А (основной) — реферер, у него есть рефералы: Клиент В и Клиент Г;
Клиент Б (присоединяемый) — реферал, его реферер — Клиент Д, собственных рефералов у Клиента Б нет.

После объединения:

Клиент А сохраняет статус реферера и своих рефералов (Клиент В и Клиент Г остаются привязаны к нему);
Клиент А становится рефералом для Клиента Д (перенимает связь Клиента Б);
Учётная запись Клиента Б удаляется, все его связи переносятся на Клиента А.

Пример 2. Оба клиента — рефереры (у каждого есть свои рефералы)

После объединения основной клиент сохраняет всех своих рефералов. Дополнительно к нему переходят все рефералы присоединяемого клиента. Основной клиент становится реферером для объединённой группы.

До объединения:

Клиент А (основной) — реферер, у него есть рефералы: Клиент В и Клиент Г;
Клиент Б (присоединяемый) — реферер, у него есть рефералы: Клиент Д и Клиент Е.

После объединения:

Клиент А сохраняет статус реферера и своих рефералов (Клиент В и Клиент Г остаются привязаны к нему);
Клиент Д и Клиент Е (бывшие рефералы Клиента Б) переходят под управление Клиента А;
Клиент А становится реферером для объединённой группы из четырёх клиентов: В, Г, Д и Е.

Пример 3. Основной клиент — реферал, присоединяемый — реферер

После объединения основной клиент сохраняет связь со своим реферером. Дополнительно к нему переходят все рефералы присоединяемого клиента. Основной клиент одновременно остаётся рефералом для своего реферера и становится реферером для новой группы.

До объединения:

Клиент А (основной) — реферал, его реферер — Клиент В;
Клиент Б (присоединяемый) — реферер, у него есть рефералы: Клиент Г и Клиент Д.

После объединения:

Клиент А сохраняет связь со своим реферером Клиентом В (остаётся его рефералом);
Клиент Г и Клиент Д (бывшие рефералы Клиента Б) переходят под управление Клиента А;
Клиент А одновременно остаётся рефералом для Клиента В и становится реферером для Клиентов Г и Д.

Логирование

Дополнительная информация для диагностики содержится в логах файла /usr/local/mgr5/var/ billmaintain.log. Чтобы включить печать отладочной информации по формированию вознаграждений по реферальной программе в лог billmaintain.log, повысьте уровень логирования:

Настройка уровня логирования

billmaintain.referral 9

Может быть полезно

Связанные статьи:

Реферальная программа. Общая информация