Реферальная программа¶

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

Термин	Кто это
Реферер	Клиент, который пригласил: владелец реферального кода
Реферал (приглашённый)	Новый клиент, указавший код реферера при регистрации
Реферальная связь	Запись «реферер → реферал» со статусом и суммами начисленного

Объём текущей версии

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

sequenceDiagram
    participant R as Реферер
    participant N as Новый клиент
    participant L as Loyalty
    R->>N: Передаёт свой реферальный код
    N->>L: Регистрация с кодом (POST /v1/customers, referralCode)
    L-->>L: Связь в статусе «ожидает» (pending)
    N->>L: Первая покупка (POST /v1/events/purchase)
    L-->>L: Связь → «активирована» (activated)
    L-->>R: Начисление рефереру
    L-->>N: Начисление рефералу (в составе покупки)

Реферальный код клиента¶

Свойство	Значение
Когда появляется	Автоматически при создании клиента; клиентам, созданным до появления программы, код присвоен при обновлении
Формат	8 символов: латинские заглавные буквы и цифры без `0`, `O`, `1`, `I` (чтобы код не путали при диктовке)
Уникальность	Уникален в программе
Изменяемость	Не меняется и не перевыпускается
Где виден	Карточка клиента, вкладка «Рефералы»; поле `referralCode` в ответах `POST/GET /v1/customers`

При вводе код приводится к верхнему регистру, пробелы по краям отбрасываются — abcd2345 и ABCD2345 считаются одним кодом.

Реферальная связь¶

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

Какой код принимается¶

Переданный код	Результат
Код существующего активного клиента	Связь создаётся в статусе `pending`
Код клиента в статусе «Заблокирован»	Связь создаётся — блокировка не лишает права приглашать
Код клиента «В архиве» или удалённого клиента	Связь не создаётся
Несуществующий код	Связь не создаётся
Собственный код регистрируемого клиента	Связь не создаётся (самореферал)

Регистрация не отказывает из-за кода

Неподходящий реферальный код не является ошибкой: клиент создаётся как обычно, просто без связи. Ни интерфейс, ни API не сообщают, что код не подошёл. Проверить результат можно на вкладке «Рефералы» у нового клиента (блок «Пригласил») или у реферера.

Статусы связи¶

Статус (API)	Подпись в таблице	Подпись в фильтре	Значение
`pending`	Ждёт первой покупки	Ожидает	Реферал зарегистрирован, первой покупки ещё не было
`activated`	Первая покупка совершена, начислено	Активирован	Первая покупка состоялась; вознаграждение начислено, если была действующая реферальная акция

Переход только один — pending → activated, обратного нет.

Активация первой покупкой¶

Связь активируется событием покупки реферала (POST /v1/events/purchase). Ручные начисления, начисления из интеграций и другие операции связь не активируют. Активация происходит один раз: последующие покупки реферала реферальных начислений не дают.

При активации система ищет действующую акцию с механикой REFERRAL («Реферальная»):

учитываются только акции в статусе «Активна», в пределах периода действия (обе границы включительно);
если таких акций несколько, выбирается одна — по приоритету акции, при равенстве — по более ранней акции (тот же порядок арбитража, что у остальных акций);
аудитория, условия и ограничения по чеку для реферальной акции не проверяются — важны только статус, период и приоритет.

Ситуация	Результат
Действующая реферальная акция есть	Связь `activated`, в ней запоминается акция; рефереру и рефералу начислено по параметрам акции
Действующей реферальной акции нет	Связь всё равно `activated`, начислений нет, акция в связи не указана
Одно из двух начислений не прошло	Не применяется ни одно, связь остаётся `pending`, откатывается вся обработка покупки

Акцию нужно запустить заранее

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

Параметры реферальной акции¶

Реферальная акция заводится в разделе «Акции» с механикой «Реферальная». У механики четыре обязательных параметра в группе «Реферальная»:

Параметр (ключ)	Подпись	Значения
`referrerRewardValue`	Вознаграждение реферера	Число ≥ 0
`referrerRewardUnit`	Единица вознаграждения реферера	`POINTS` — «баллы», `PERCENT` — «%»
`refereeRewardValue`	Вознаграждение реферала	Число ≥ 0
`refereeRewardUnit`	Единица вознаграждения реферала	`POINTS` — «баллы», `PERCENT` — «%»

Как считается вознаграждение каждой стороны:

POINTS — значение задаётся в минорных единицах баллов (при точности баллов 2 значение 50000 — это 500 баллов);
PERCENT — процент от суммы первой покупки реферала, с округлением до целой минорной единицы по правилу «половина вверх»;
максимальный бонус акции (maxBonus), если задан, ограничивает каждую сторону отдельно.

Бюджет и лимиты участий

Бюджет акции и лимиты участий при реферальной активации не проверяются — действует только ограничение максимального бонуса на каждую сторону.

Настройки баллов реферальной акции на вкладке «Механика» действуют на оба начисления — и рефереру, и рефералу:

«Срок жизни начисляемых баллов» — срок обоих начислений отсчитывается от момента первой покупки реферала; в сроках сгорания клиента источник такого срока — «срок задан при начислении». Поле пустое — срок определяется по общей цепочке (субсчёт, уровень клиента, валюта), см. Сгорание баллов;
«Тип начисляемых баллов» — субсчёт, на который попадают оба начисления; по умолчанию — «Акционные баллы» (см. Субсчета баллов).

Уведомления¶

Начисление рефералу входит в сумму уведомления о начислении за его покупку. Рефереру отдельное уведомление в текущей версии не отправляется.

Работа в интерфейсе¶

Реферальный код при создании клиента¶

В форме «Новый клиент» (раздел «Клиенты»), в секции «Идентификатор», после поля «ID клиента» расположено необязательное поле «Реферальный код» (подсказка «Код клиента, который пригласил»). Формат и существование кода интерфейс не проверяет — см. правила выше.

Вкладка «Рефералы» в карточке клиента¶

Карточка клиента → категория «Клиент» → вкладка «Рефералы».

Верхний блок:

Элемент	Содержание
Реферальный код	Код клиента и кнопка «Скопировать код» (после нажатия подсказка «Скопировано»)
Пригласил	Имя реферера со ссылкой на его карточку. Строки нет, если клиента никто не приглашал
Пришли по коду: N	Число клиентов, зарегистрировавшихся с кодом этого клиента
Совершили первую покупку: N	Из них — сколько уже активировали связь
Начислено за рефералов: N	Сумма, начисленная этому клиенту как рефереру, в баллах

Таблица приглашённых:

Колонка	Содержание
Клиент	Имя реферала (если профиль в MDM недоступен — его ID); двойной клик открывает карточку
Статус	«Ждёт первой покупки» / «Первая покупка совершена, начислено»
Дата приглашения	Когда создана связь (сортируемая)
Дата первой покупки	Когда связь активирована (сортируемая)
Начислено рефереру	Начисление рефереру по этой связи, в баллах
Начислено рефералу	Начисление рефералу по этой связи, в баллах

Над таблицей — фильтр «Статус»: «Все», «Ожидает», «Активирован». По умолчанию список отсортирован по «Дата приглашения» (сначала новые). Выбранные фильтр, сортировка и размер страницы запоминаются в браузере. Пустой список — «Клиент ещё никого не пригласил».

Суммы — снимок на момент активации

Суммы «Начислено рефереру» и «Начислено рефералу» фиксируются в связи в момент активации и дальше не пересчитываются.

Отчёт по реферальной программе¶

Сводные показатели программы показывает раздел «Отчёты», вкладка «Рефералы» (см. Отчёты): «Срез состояния» на момент запроса — «Всего связей», «Активировано», «Ждут первой покупки», — а также величины за период, когорту периода и «Начислено сторонам». Отчёт доступен по GET /v1/reports/referrals (роль LOYALTY_MONITORING_READ): срез — в поле snapshot, а поле pending — сколько приглашений ждали первой покупки на конец выбранного периода. pending считается по моменту активации связи, поэтому связь, созданная в периоде и активированная уже после него, на конец периода считается ожидающей.

REST API¶

Метод и путь	Назначение	Права
`POST /v1/customers`	Создание клиента; необязательное поле `referralCode` — код реферера. В ответе — собственный `referralCode` клиента	`LOYALTY_CUSTOMER_WRITE`
`GET /v1/customers/{externalId}`	Клиент; в ответе — `referralCode`	`LOYALTY_CUSTOMER_READ`
`GET /v1/customers/{externalId}/referral`	Реферальный блок: код, кто пригласил, агрегаты	`LOYALTY_PROFILE_READ` и `LOYALTY_MONITORING_READ`
`GET /v1/customers/{externalId}/referrals`	Список приглашённых этим клиентом (постранично)	`LOYALTY_PROFILE_READ` и `LOYALTY_MONITORING_READ`

Отдельной роли у реферальной программы нет: просмотр требует тех же прав, что и карточка клиента.

Реферальный блок¶

{
  "referralCode": "K7MX4QPA",
  "referrer": { "externalId": "CUST-100200", "fullName": "Иванова Мария" },
  "referredCount": 5,
  "activatedCount": 3,
  "totalReferrerAccruedPointsMinor": 150000
}

Поле	Описание
`referralCode`	Собственный код клиента
`referrer`	Кто пригласил клиента; `null`, если никто. `fullName` — из MDM, при его отсутствии равен `externalId`
`referredCount`	Сколько клиентов пришло по коду
`activatedCount`	Сколько из них активировали связь
`totalReferrerAccruedPointsMinor`	Сумма начисленного клиенту как рефереру, в минорных единицах

Список приглашённых¶

GET /v1/customers/{externalId}/referrals?status=&page=&size=&sort= — ответ в стандартном постраничном конверте (items, total, …).

Параметр	Описание
`status`	Необязательный фильтр: `pending` или `activated`
`sort`	`createdAt` или `activatedAt`, направление `asc`/`desc`; по умолчанию `createdAt,desc`
`page`, `size`	Номер страницы (с 0) и размер

Элемент списка: referralLinkId, referee (externalId, fullName), status, createdAt, activatedAt, referrerAccruedPointsMinor, refereeAccruedPointsMinor (суммы — null, пока связь не активирована или если акции не было).

Ошибки¶

Код	HTTP	Когда
`referral_status_invalid`	400	Недопустимое значение фильтра `status`
`referral_sort_invalid`	400	Сортировка по полю, отличному от `createdAt` / `activatedAt`
`customer_not_found`	404	Клиента с таким `externalId` нет
`referral_code_generation_failed`	500	Не удалось подобрать уникальный код при создании клиента (крайне маловероятно)

См. также¶

Профиль участника — создание клиента и карточка
Механики начисления — каталог механик, включая REFERRAL
Достижения и бейджи