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

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

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

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

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

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

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

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

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

Если URL — сторонний сайт, выполните дополнительные действия:

  1. Со стороны сайта выполните запрос к платформе следующего вида:

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

    Где:

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

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

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

    <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 передаёт текущий URL, который может содержать параметр с реферером.
            req.open("GET", "https://billmgr_addr/?func=referralprogram.registerclick&p=" + encodeURIComponent(window.location.href) + "&out=xjson", true);
            req.send(null);
        }
        if (!localStorage.hasOwnProperty("bill_cntid")) {
            getBillCntid();
        }
    </script>

</head>
<body>
    <script type="text/javascript">
        function gotoBillManager() {
            var url = "https://billmgr_addr";
            // Если нашли идентификатор подключения к реферальной программе (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 Clouden">
</body>
</html>
    XML
    • getBillCntid() — функция отправляет запрос к платформе для регистрации перехода по реферальной ссылке;
    • encodeURIComponent(window.location.href) — функция кодирует текущий URL страницы, включая параметр from=ID, указывающий на реферера;
    • localStorage.setItem("bill_cntid", ...) — функция сохраняет полученный уникальный идентификатор перехода между сессиями;
    • gotoBillManager() — функция формирует URL для перехода в платформу с добавлением параметра cntid, если он был сохранён;
    • cntid — параметр позволяет платформе привязать будущую регистрацию или покупку к конкретному переходу по реферальной ссылке.

Таблицы БД

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

nameprojecturlpromocodeaccount_groupaccount_group_restrictassign_by_defaultstart_dateend_date
Referral Program1https://example.com/refPROMO202551012025-01-012025-12-31
  • name — наименование реферальной программы. Локализованное поле;
  • project — провайдер;
  • url — URL сайта, с которого осуществляется переход к реферальной программе;
  • promocode — промокод;
  • account_group — разрешённая группа клиентов;
  • account_group_restrict — запрещённая группа клиентов;
  • assign_by_default — автоматическое подключение к присоединённым к провайдеру клиентам;
  • start_date — начало действия;
  • end_date — окончание действия.

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

referralprogramreward_value_fixedreward_value_percentreward_max_amountreward_months_afterreward_expense_periodreward_periodreward_payment_intervalstatus
10.0010.005000.00111210
  • referralprogram — ID реферальной программы;
  • reward_value_fixed — фиксированное значение вознаграждения;
  • reward_value_percent — процентное значение вознаграждения (процент от покупки);
  • reward_max_amount — максимальная сумма вознаграждения (выбирается эта сумма, если полученный процент от покупки превышает её);
  • reward_months_after — количество месяцев, по прошествии которых будет выплачено вознаграждение;
  • reward_expense_period — определяет, какие расходы берутся для начисления вознаграждения:
    • 0 — при покупке;
    • 1 — за всё время;
  • reward_period — период вознаграждения, в месяцах;
  • reward_payment_interval — периодичность выплат вознаграждений, в месяцах;
  • status — статус:
    • 0 — активен;
    • 1 — удалён.

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

referralprogram_rulectypecgroupcomparisonamountorderperiodsitem_countreferral_countproduct_treestatus
110ge10000.003NULLNULLNULL0
  • referralprogram_rule — ID правила реферальной программы;
  • ctype — тип условия:
    • 0 — без условий;
    • 1 — объём продаж реферала;
    • 2 — по количеству услуг, купленных рефералом;
    • 3 — по количеству приведённых рефералов;
    • 4 — объём продаж всех рефералов;
  • cgroup — группа условий;
  • comparison — знак сравнения; возможные значения: eq, ne, gt, ge, lt, le;
  • amount — сумма;
  • orderperiods — период заказа;
  • item_count — количество услуг;
  • referral_count — количество рефералов;
  • product_tree — дерево продуктов;
  • status — статус:
    • 0 — активен;
    • 1 — удалён.

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

referer_accountreferral_accountipsesidsitecdateproject
101205192.168.1.100a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8https://example.com/ref?ref=1012025-11-01 14:30:001
  • referer_account — ID реферера (таблица account);
  • referral_account — ID реферала (таблица account);
  • ip — IP-адрес при переходе по ссылке;
  • sesid — уникальный идентификатор сессии;
  • site — ссылка перехода;
  • cdate — дата создания записи;
  • project — провайдер.

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

accountprojectreferralprogram
10113
  • account — ID реферера (таблица account);
  • project — провайдер;
  • referralprogram — реферальная программа.

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

referer_accountreferral_accountreferralprogram
1012053
  • referer_account — ID реферера (таблица account);
  • referral_account — ID реферала (таблица account);
  • referralprogram — ID реферальной программы.

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

referralprogramreferralprogram_rulereferral_accountreferer_accountamountcurrencyexpensepaymentcdate
312051011250.00RUB500178902025-11-05 10:15:00
  • referralprogram — ID реферальной программы;
  • referralprogram_rule — ID правила реферальной программы;
  • referral_account — ID реферала (таблица account);
  • referer_account — ID реферера (таблица account);
  • amount — сумма вознаграждения;
  • currency — валюта;
  • expense — ID расхода, по которому сформировано вознаграждение;
  • payment — платёж зачисления вознаграждения;
  • cdate — дата создания записи.

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

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

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

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

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')
CODE
  • cdate — дата и время перехода;
  • ip — IP-адрес, с которого был осуществлён переход;
  • method — способ перехода. Например, через витрину, регистрацию и т.д.;
  • project — код провайдера, в рамках реферальной программы которого зарегистрирован переход;
  • referer_account — код клиента-партнёра, чья ссылка использовалась;
  • referralprogram — идентификатор реферальной программы;
  • sesid — уникальный ключ сессии;
  • site — URL-адрес страницы, с которой был произведён переход.

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

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

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

  1. Добавление нового пользователя в качестве потенциального реферера:

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

    INSERT INTO referralprogram_referer (account, project, referralprogram) VALUES('44', '2', '5')
    CODE
    • account — идентификатор лицевого счёта клиента, который станет реферером;
    • project — код провайдера;
    • referralprogram — идентификатор реферальной программы.

  2. Добавление связи зарегистрированного клиента-реферала с реферером и реферальной программой:

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

    INSERT INTO referralprogram_link (cdate, referer_account, referral_account, referralprogram) VALUES('2025-11-10', '2', '43', '1')
    CODE
    • cdate — дата регистрации реферала;
    • referer_account — идентификатор клиента-реферера;
    • referral_account — идентификатор реферала;
    • referralprogram — идентификатор реферальной программы. Например, 1.

  3. Добавление 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'
    CODE

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

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

Задание в cron

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

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

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

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

    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'
    CODE

  2. Отправляет 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')
    CODE
    • amount — сумма вознаграждения;
    • cdate — дата начисления вознаграждения;
    • currency — код валюты. Например, 126 соответствует евро, 810 — российскому рублю;
    • expense — идентификатор расхода реферала, на основе которого начислено вознаграждение;
    • id — уникальный идентификатор записи о вознаграждении;
    • referer_account — идентификатор клиента-реферера;
    • referral_account — идентификатор клиента-реферала;
    • referralprogram — идентификатор реферальной программы;
    • referralprogram_rule — правило реферальной программы, по которому применено вознаграждение.

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

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

    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'
    CODE

  4. Выполняется 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')
    CODE
    • createdate — дата и время создания платежа;
    • currency — код валюты платежа;
    • id — уникальный идентификатор платежа;
    • paymethodamount — сумма в валюте метода оплаты;
    • randomnumber — уникальный внутренний номер платежа;
    • status — статус платежа. Например, 1 — новый, 4 — зачислен и т.д.;
    • subaccount — лицевой счёт реферера, на который зачисляется вознаграждение;

    • subaccountamount — сумма в валюте лицевого счёта;

    • usedamount — израсходованная часть платежа.

Логирование

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

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

billmaintain.referral 9
CODE

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

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