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

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

Обратите внимание!

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

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

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

Общая логика работы

Со стороны провайдера

Создайте реферальную программу в разделе меню: Маркетинг → Реферальные программы → кнопка Создать.
Укажите размер вознаграждения и URL-адрес сайта провайдера.
Разместите, как минимум, на одной странице сайта провайдера, следующий код:
```
<script language="javascript">
  var counter_url = "https://billmgr.domain/mancgi/counter?rnd="+Math.random()+"&project=1&r="+escape(document.referrer)+"&p="+escape(window.location.href);
  document.write("<img src='" + counter_url + "' border=0 width=0 height=0 style='display: none;'>");
</script>
```
Пояснения
- billmgr.domain — доменное имя биллинговой системы провайдера
- rnd — параметр для предотвращения кеширования
- project — идентификатор (id) провайдера реферальной программы
- r — параметр для регистрации страницы или домена, с которого перешёл реферал
- p — полный URL текущей страницы. Из него извлекается идентификатор партнера, который привёл реферала
Если нужно, чтобы сайтом реферальной программы был BILLmanager, разместите указанный код в настройках бренда. Для этого перейдите в раздел Провайдер → Провайдеры → выберите провайдера → кнопка Настройка бренда → блок HTML-вставка → заполните поле Заголовок (head).
Этот код нужен для учёта переходов и регистраций по реферальным ссылкам.

Обратите внимание!

Один клиент может быть подключён только к одной реферальной программе.

Со стороны клиента

Клиент (реферер) переходит в раздел Клиент → Реферальная программа и копирует там ссылку или промокод. Пользователи, которые перешли по этой ссылке или при заказе первой услуги ввели промокод реферера, становятся рефералами клиента.

Клиент (реферер) может посмотреть статистику переходов по реферальной ссылке в разделе меню Клиент → Реферальная программа → Статистика. В статистике отображено количество переходов по ссылке и сколько из перешедших зарегистрировались в BILLmanager и совершили оплату.

Таблицы БД

Таблица affiliate содержит общую информацию о реферальной программе:

name

project

integration

billurl

url

promocode

reward

period

account_group

account_group_restrict

name_lt

name_ru

name_ua

url_lt

url_ru

url_ua

NULL

LULULU@ID@

1000

NULL

Ref

NULL

http://172.30.20.103:8080/?p=

NULL

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

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

id	affiliate	itemtype	pricelist	reward
1	1	103	1	50

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

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

account	project	affiliate	affiliatereferer	affiliateprogram	assigning_date
2 3 5 6 7	1 1 2 1 1	1 1 NULL NULL NULL	NULL NULL NULL 3 3	NULL NULL NULL 1 1	2020-01-08 2020-01-08 2020-01-10 2020-01-10 2020-01-12

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

Таблица affiliateclick содержит список переходов по реферальной ссылке:

site	account	referal	ip	project	sesid	cdate
	2 2 2 3	NULL 6 NULL 7	172.30.20.1 172.30.20.1 172.30.20.1 172.30.20.1	1 1 1 1	1578689949.b7XKmd 1578689962.GLQNPy 1579183750.OC4uK2 1578833311.M0DVRk	2020-01-10 20:59:09 2020-01-10 20:59:22 2020-01-16 14:09:10 2020-01-12 12:48:43

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

Таблица affiliatereward — список начислений за реферальную программу:

id	affiliate	account	referal	amount	currency	payment	cdate	itemtype	pricelist	reward
1	1	3	6	1000.0000	126	3	2020-02-01	NULL	NULL	1000

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

Создание реферальной программы

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

Пример записи в таблицу БД

INSERT INTO affiliate (id, name_ru, project, reward, url_ru) VALUES('1', 'Пригласи друга', '1', '15', 'http://billmanager.docker:8080/?from=')

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

При добавлении особых правил реферальной программы в меню Маркетинг → Реферальные программы → Правила → Создать, BILLmanager делает запись в базу данных:

Пример записи в таблицу БД

INSERT INTO affiliateitemtype (affiliate, id, itemtype, pricelist, reward) VALUES('1', '1', '103', '1', '50')

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

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

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

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

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

INSERT INTO affiliateclick (site, account, ip, project, sesid, cdate) VALUES ('', '2', '172.30.20.1', '1', '1579183750.OC4uK2', NOW())

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

Привязка реферала делается в следующих случаях:

при переходе на витрину;
вручную в настройках лицевого счёта клиента;
вручную в настройках клиента;
при регистрации.

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

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

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

Привязка клиента к провайдеру:
Запись в таблицу БД
```
INSERT INTO affiliate (id, name_ru, project, reward, url_ru) VALUES('1', 'Пригласи друга', '1', '15', 'http://billmanager.docker:8080/?from=')
```
Пояснения к записи
- id — код программы
- name_ru — наименование реферальной программы на русском языке
- project — код провайдера, на котором работает реферальная программа
- reward — процент поощрения по реферальной программе
- url_ru — URL сайта провайдера
Подключение нового клиента к реферальной программе:
Запись в таблицу БД
```
UPDATE account2project SET affiliate='1' WHERE account='3' AND project='1'
```
Пояснения к записи в базу
- affiliate — партнёрская программа, используемая клиентом у провайдера
- account — код клиента
- project — код провайдера
Привязка нового клиента к рефереру в качестве реферала:
Запись в таблицу БД
```
UPDATE account2project SET affiliateprogram='1', affiliatereferer='3' WHERE account='5' AND project='1'
```

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

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

Задание в cron

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

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

Делает запросы для каждого реферала:

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

Jan 16 12:40:16 [12:151] core_module INFO Request [billmaintain][root] 'affiliate=1&func=affiliate.process&month=2020%2D01%2D20&out=xml&referal=6&referer=2'

Проверяет разрешено ли рефереру участвовать в реферальной программе:

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

SELECT Count(*)
    FROM   affiliate a
       LEFT JOIN account2group a2g
              ON a2g.account = 2
                 AND a2g.accountgroup = a.account_group
       LEFT JOIN account2group rest
              ON rest.account = 2
                 AND rest.accountgroup = a.account_group_restrict
    WHERE  a.id = '1'
       AND ( a.account_group IS NULL
              OR a2g.account IS NOT NULL )
       AND rest.account IS NULL

В случае отрицательного ответа в логе будут отображаться ошибки вида:

Пример ошибки в логе

Jan 10 20:11:20 [2724:1586] libmgr ERROR Error: Type: 'access' Object: 'affiliate' Value: '1'

Проверяет были ли уже вознаграждения за реферала за расчётный месяц:
Пример запроса
```
select count(*) from affiliatereward where account=2 and referal=6 and affiliate=1 and cdate='2020-02-01'
```

Считает расходы реферала запросом:

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

SELECT e.amount,
       s.currency,
       ai.reward,
       e.operationparams,
       ai.id AS rewardid
FROM   subaccount s
       join expense e
         ON e.subaccount = s.id
       left join item i
              ON i.id = e.item
       left join pricelist p
              ON p.id = i.pricelist
       left join pricelist pparent
              ON pparent.id = p.parent
       left join affiliateitemtype ai
              ON ai.affiliate = 1
                 AND ( ai.pricelist IS NULL
                       AND ( ai.itemtype = p.itemtype
                              OR ai.itemtype = pparent.itemtype )
                        OR ( ai.pricelist = p.id
                              OR ai.pricelist = p.pricelist_group
                              OR ai.pricelist = pparent.id
                              OR ai.pricelist = pparent.pricelist_group )
                           AND ( ai.itemtype = p.itemtype
                                  OR ai.itemtype = pparent.itemtype ) )
       left join pricelist aip
              ON aip.id = ai.pricelist
WHERE  s.account = 6
       AND s.project = 1
       AND e.realdate >= '2020-01-01'
       AND e.realdate < '2020-02-01'
ORDER  BY IF(ai.pricelist IS NULL, 0, 1) DESC,
          IF(aip.isgroup = 'on', 0, 1) DESC

Если условия выполняются и у реферала есть расходы за расчётный период, начисляет рефереру вознаграждение:
Пример записи в таблицу БД
```
INSERT INTO affiliatereward (account, affiliate, amount, cdate, currency, id, referal, reward) VALUES('2', '1', '10.00', '2020-02-01', '126', '1', '6', '10')
```
Для каждого реферера, которому было начислено вознаграждение, делает запрос:
Пример запроса
```
Jan 16 12:40:16 [12:153] core_module INFO Request [billmaintain][root] 'cdate=2020%2D02%2D01&func=affiliate.createpayment&out=xml&referer=2'
```
Создаёт и зачисляет авансовые платежи вознаграждения с номером вида PartnerPayment/ID:
Пример записей в БД
```
INSERT INTO payment (createdate, currency, id, paymethodamount, randomnumber, status, subaccount, subaccountamount, usedamount) VALUES('2020-01-16 12:40:16', '126', '2', '10.00', 'oRBId9qgDJOr', '1', '1', '10.00', '0.0000')
   UPDATE payment SET number='PartnerPayment/2' WHERE id='2'
   UPDATE payment SET description='Авансовый платеж #2' WHERE id='2'
   UPDATE payment SET status='4' WHERE id='2'
   UPDATE payment SET description='Partner Payment - Gym' WHERE id='2'
   UPDATE affiliatereward SET payment='2' WHERE id='1'
```
Пояснения к записи в базу
- createdate — дата создания
- id — код платежа
- paymethodamount — сумма платежа в валюте метода оплаты
- randomnumber — уникальный номер моментального платежа
- status — текущий статус платежа
  - 1 — новый
  - 2 — оплачивается
  - 3 — обещанный платёж
  - 4 — зачислен
  - 5 — ожидает возврата
  - 6 — возвращён клиенту полностью
  - 7 — мошеннический
  - 8 — новый платёж с быстрым зачислением
  - 100 — удаляется
- subaccount — код лицевого счета, к которому привязан платёж
- subaccountamount — сумма платежа в валюте лицевого счета
- usedamount — израсходованная сумма платежа
- number — номер платежа
- description — назначение авансового платежа
- payment — код платежа, которым начислено поощрение
Обратите внимание!
Платежи за награждение по реферальной программе создаются без указания плательщика и акты по таким платежам сделаны не будут.