Механики начисления¶

Механика — шаблон акции, определяющий, как из события покупки вычисляется бонус в баллах. Каждая акция создаётся на основе одной механики и доопределяет её параметрами (ставка награды и другие значения, нужные расчёту), периодом, условиями и ограничениями.

Каталог механик — справочник, который ведёт администратор в разделе «Справочники»; каждая запись соответствует диаграмме расчёта RT Flow. При создании акции механика выбирается из этого справочника на вкладке «Механика», а форма показывает поля именно её параметров — см. «Создание и редактирование акции».

Метод и путь	Назначение	Право
`GET /v1/mechanics`	Каталог механик	`LOYALTY_PROMOTION_READ`
`GET /v1/mechanics/{code}`	Механика с диаграммой и параметрами (для формы акции)	`LOYALTY_PROMOTION_READ`
`GET /v1/admin/mechanics/export`	Выгрузка механик с параметрами для переноса между контурами	`LOYALTY_PROMOTION_READ`
`POST /v1/admin/mechanics/import`	Загрузка механик; `dryRun=true` — предпросмотр без записи	`LOYALTY_PROMOTION_WRITE`

Загрузка проверяет механику и её параметры так же, как заведение в админке, — см. «Перенос настроек между контурами».

Запись механики содержит код (code), наименование (title), тип (type, у всех механик начисления — ACCRUAL), описание, имя диаграммы (rtFlowDiagram), число ссылающихся акций (usedByPromotions), признак deletable и два признака для формы акции:

accruesPoints — начисляет ли механика баллы. От него зависит, доступны ли в акции срок жизни и тип начисляемых баллов (см. Начисляемые баллы);
paramsConfigured — заведены ли у механики параметры. В новой акции форма предлагает только такие механики.

Механику, на которую ссылаются акции, удалить нельзя — 409 mechanic_in_use; решение сервер отдаёт в ответе, поэтому интерфейс не показывает кнопку, которая заведомо откажет.

Параметры механики¶

У механики может быть описан набор параметров (param_def) — из них форма строит вкладку «Механика». Каждый параметр несёт ключ, подпись, тип, обязательность, значение по умолчанию, группу, порядок, подсказку, единицу и границы min/max; у списков — варианты значений.

Тип параметра	Контрол в форме	Проверка на сервере
`PERCENT`, `MONEY`, `INT`, `DECIMAL`	число с единицей и границами	число, не меньше `min` и не больше `max`
`BOOLEAN`	переключатель	только обязательность
`ENUM`, `MULTISELECT`	список значений	только обязательность
`CATEGORY`, `SKU`, `SEGMENT`	ввод значений чипсами	только обязательность
`STRING`	текстовое поле	только обязательность

Обязательный параметр без значения — 422 promotion_param_required (проверяется всегда, даже если params пустой); нечисловое значение — promotion_param_type, выход за границы — promotion_param_min / promotion_param_max. Ключи, которых нет в описании механики, сервер принимает и хранит: так в params живут условия по клиенту (conditions.client). Параметры типа MONEY (деньги и баллы) хранятся в минорных единицах — форма умножает введённое значение на 100. Значение по умолчанию из справочника форма подставляет в поле.

Награда — один из параметров. Отдельного поля «значение вознаграждения» нет: ставку, по которой считается бонус, сервер берёт из параметра-награды механики. Поле value запроса для механик с параметром-наградой не используется, форма его не передаёт.

Механика без параметров (например, заведённая администратором собственная механика RT Flow, у которой параметры ещё не описаны) в форме новой акции не предлагается: награду задать негде. Существующая акция на такой механике открывается с плашкой «Настройки этой механики ещё не заведены — акцию на ней пока не собрать. Обратитесь к администратору», а её черновик не запускается — 409 promotion_mechanic_not_configured.

Каталог механик¶

Код	Наименование	Что делает	Параметры (подпись в форме)	Начисляет баллы
`CASHBACK`	Кэшбэк	Процент от суммы покупки баллами	«Процент кэшбэка» (`cashbackPercent`, 0–100 %) — награда	да
`UNIT_BONUS`	Начисление за единицу	Баллы за натуральный объём (литры, штуки)	«Баллов за единицу» (`pointsPerUnit`) — награда	да
`MULTIPLIER`	Множитель	Сумма покупки × множитель	«Множитель» (`multiplier`, от 0,01) — награда	да
`GIFT`	Подарок	Фиксированное начисление за событие	«Баллов в подарок» (`giftMinor`) — награда	да
`REFERRAL`	Реферальная	Вознаграждение за приведённого друга	«Вознаграждение реферера» и «Вознаграждение реферала», у каждого — своя единица	да
`BUNDLE_1PLUS1`	1+1=3	Бандл: покупка N единиц — M в подарок; логику исполняет диаграмма RT Flow	«Покупает единиц», «Дополнительных единиц», «Стоимость дополнительной единицы» (по умолчанию 1 ₽)	нет — выдаёт единицы товара

Параметры «1+1=3» форма показывает фразой «За покупку [N] шт товара клиент дополнительно получает ещё [M] шт по стоимости [1] ₽ за штуку»; какой именно товар участвует, задаётся на вкладке «Условия» (категории, SKU).

Изменение 26.3.0: параметры механик пересобраны

У «Кэшбэка» удалены параметры «Макс. бонус», «Мин. сумма чека» и «Сегменты клиентов»: потолок бонуса задаётся только ограничением акции «Максимальное количество баллов», сумма чека и сегменты — условиями на вкладке «Условия». Сохранённый в акции «Макс. бонус» перенесён в ограничение акции. У «Множителя», «Подарка» и «Начисления за единицу» награда стала обязательным параметром; у ранее сохранённых акций параметр заполнен прежней ставкой, начисление не изменилось. У «1+1=3» удалён параметр «Категория товаров» (товар задаётся условиями), «В подарок единиц» переименован в «Дополнительных единиц», добавлена обязательная «Стоимость дополнительной единицы».

Расчёт бонуса¶

Все механики считают бонус в минорных единицах баллов, округляют до целого по правилу «половина вверх» (HALF_UP) и ограничиваются сверху ограничением акции «Максимальное количество баллов» (maxBonusMinor), если оно задано. Ставка (value) — значение параметра-награды.

Механика	Формула
`CASHBACK`	`bonus = round(amountMinor × value / 100)` — `value` в процентах
`UNIT_BONUS`	`bonus = round(quantity × value)` — `value` в баллах-минор за единицу
`MULTIPLIER`	`bonus = round(amountMinor × value)` — `value` — множитель
`GIFT`	`bonus = round(value)` — не зависит от суммы покупки
`REFERRAL`	в расчёте по покупке — `0`

Механики, которых нет в таблице (например, BUNDLE_1PLUS1 и заведённые администратором собственные механики RT Flow), ядром не рассчитываются: акция на такой механике создаётся и хранится, а начисление выполняет диаграмма RT Flow через интеграционный вызов начисления.

Пример

Покупка на 1000,00 (amountMinor = 100000), механика «Кэшбэк», cashbackPercent = 5, «Максимальное количество баллов» — 4000 баллов-минор. Сырой бонус: 100000 × 5 / 100 = 5000. После ограничения: min(5000, 4000) = 4000.

Изменение 26.3.0: «Множитель» и «Подарок» действительно начисляют

Раньше расчёт был реализован только для «Кэшбэка» и «Начисления за единицу», а акции на «Множителе» и «Подарке» молча давали нулевой бонус (и потому отсеивались подбором). Теперь обе механики считают начисление.

Начисление за единицу¶

Бонус начисляется за натуральный объём: количество единиц × ставка. Если событие не содержит количества, механика возвращает 0 и акция не применяется. Единица измерения подразумевается условиями акции (категория, артикул).

Изменение 26.3.0: механика заработала на кассовом канале

Строка кассового чека не несла количества и единицы измерения — настроенная акция «10 баллов за литр» на кассе молча не применялась. Теперь позиция чека принимает quantity и unitCode (необязательные: штучная позиция без явного количества остаётся корректной), как их с самого начала принимала прямая ручка покупки.

Реферальная механика¶

В пер-событийном расчёте по покупке REFERRAL не начисляет ничего: вознаграждение уходит другому клиенту (пригласившему), и из события одной покупки его не вывести. Такую акцию использует реферальная программа: когда покупка активирует реферальную связь, она начисляет обеим сторонам по параметрам активной акции с механикой REFERRAL — «Вознаграждение реферера» и «Вознаграждение реферала», у каждого своя единица («баллы» — значение в минорных единицах, «%» — процент от суммы активирующей покупки). «Максимальное количество баллов» акции ограничивает каждую сторону отдельно.

Начисляемые баллы¶

У акции на механике, которая начисляет баллы (accruesPoints), на вкладке «Механика» задаются:

Настройка	Поле API	Поведение
«Срок жизни начисляемых баллов»	`pointsLifetimeDays`	1–36 500 дней. Пусто — срок партии определяется при начислении по цепочке: свой срок субсчёта → срок уровня клиента в его конфигурации программы → базовый срок валюты баллов → не сгорают. Срок и его источник фиксируются в партии и потом не пересчитываются
«Тип начисляемых баллов»	`pointsSubaccountCode`	Субсчёт валюты баллов программы, в который идёт начисление. Пусто — «Акционные баллы» (`PROMO`)

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

У механики, которая баллы не начисляет, эти настройки недоступны: непустое значение отклоняется 422 promotion_points_settings_not_applicable. Субсчёт, которого нет в валюте баллов программы или который не принимает начисления, — 422 promotion_points_subaccount_invalid. Подробнее о сроках и субсчетах — «Сгорание баллов» и «Субсчета баллов».

Параметры акции, влияющие на расчёт¶

Параметр	Назначение
Параметр-награда механики	Процент, баллы за единицу, множитель, размер подарка
«Максимальное количество баллов» (`maxBonusMinor`)	Верхний предел бонуса по одному событию
«Приоритет» (`priority`)	Порядок арбитража конкурирующих акций (меньше — выше); обязателен
«Совмещение» (`stacking`)	«Совмещается» (`STACKABLE`) или «Только одна» (`EXCLUSIVE`)

Прочие ограничения (бюджет, лимиты участий) на величину бонуса не влияют, но решают, применится ли акция, — см. «Ограничения и лимиты акции». Сумма чека — условие акции на вкладке «Условия», см. «Условия акции».

Отбор и арбитраж акций¶

Для события покупки из активных акций отбираются те, что проходят период, условия акции (категория, артикул, география, мерчант, канал продаж, сегменты, сумма чека, дополнительные условия) и условия по клиенту (см. «Условия акции»), дают положительный бонус и укладываются в ограничения. Только затем выполняется арбитраж: акции упорядочиваются по приоритету, затем по идентификатору.

flowchart TD
    A[Событие покупки] --> B{Период?}
    B -- нет --> X[Пропустить]
    B -- да --> C{"Условия акции —<br/>товары, место, сумма чека?"}
    C -- нет --> X
    C -- да --> K{Условия<br/>по клиенту?}
    K -- нет --> X
    K -- да --> D{Бонус &gt; 0?}
    D -- нет --> X
    D -- да --> E{Лимиты и бюджет?}
    E -- нет --> X
    E -- да --> F[Сортировка по приоритету, id]
    F --> G{Старшая акция<br/>«Только одна»?}
    G -- да --> H[Применяется только она]
    G -- нет --> I[Складываются все совмещаемые]

Если акция с наивысшим приоритетом помечена «Только одна» — применяется только она.
Иначе складываются все совпавшие совмещаемые акции (акции «Только одна» с более низким приоритетом отбрасываются).
Акция, выбывшая по ограничению, в арбитраже не участвует и не блокирует совместимые.

Условия акции

Выключенное условие не ограничивает. Событие должно выполнить все включённые условия зоны «Акция применяется, если» и ни одного условия зоны «Не применяется, если» (для сегментов достаточно совпадения хотя бы по одному). Незнакомое движку условие акцию не применяет.

Поверх акций может работать базовое начисление программы (глобальная механика) — оно настраивается отдельно и в арбитраже акций не участвует.

Возврат покупки¶

Когда касса сообщает о возврате по чеку, баллы, начисленные по этому чеку акциями и базовым начислением, сторнируются пропорционально доле возвращённой суммы; при возврате всего чека остаток каждого начисления сторнируется точно. Сторно не больше доступного остатка на субсчёте исходного начисления: уже потраченные клиентом баллы не сторнируются, баланс в минус не уходит. Запись сторно наследует привязку к акции, поэтому расход бюджета акции уменьшается; использованное участие возврат не возвращает. Отмена возврата начисляет баллы обратно с той же привязкой к акциям.