Конфигурации программы¶
Конфигурация программы лояльности — набор базовых правил программы: какими акциями клиент зарабатывает баллы, как он может их списывать, какие есть уровни и как клиент переходит между ними. Конфигураций может быть несколько, но действует ровно одна — активная; остальные хранятся как черновики. Новая редакция правил готовится в черновике и включается активацией, без правки действующих правил «на живую».
Раздел меню — «Конфигурации программы» (виден при праве LOYALTY_PROGRAM_CONFIG_READ). Он заменил
прежний экран «Уровни»: уровни теперь существуют только в составе конфигурации — см.
Уровни (тиры).
Что конфигурация не выбирает
Валюта баллов и счёт начисления в конфигурации не настраиваются: программа начисляет в валюту
баллов программы (параметр points.currency операционной конфигурации)
на её базовый субсчёт (Субсчета баллов). На шаге «Основное» об этом
напоминает строка «Программа начисляет в валюте баллов «…» на базовый субсчёт «…»» со ссылками на
разделы администрирования «Валюты» и «Субсчета баллов»; если валюта баллов или её базовый субсчёт не
заданы, вместо строки выводится предупреждение «Валюта баллов не выбрана — программа не сможет
начислять баллы.». Базовый срок жизни баллов задаёт валюта
(Справочник валют), свой срок можно задать уровню.
Состав конфигурации¶
| Раздел | Что задаёт |
|---|---|
| Основное | «Название конфигурации» — обязательное и уникальное; в интерфейсе — до 255 символов. |
| Акции программы | Акции, которые образуют базовое начисление программы. Привязанную акцию нельзя удалить. |
| Правила списания | Где и сколько баллов клиент может списать за покупку. Пока правила не заданы, действует общая политика списания раздела «Настройка ПЛ». |
| Уровни | Набор уровней с порогами входа, «Механика перехода на следующий уровень», акции начисления уровней, лимит списания и срок жизни баллов уровня, блок «Как клиент получает и теряет уровень». |
| Как живут баллы | Сводка только для чтения (в карточке конфигурации): срок жизни баллов по субсчетам и уровням. |
Справа от формы — панель «Как это сработает»: пример «Клиент Анна, покупки за год» на шкале уровней формы (покупки, переходы, пересмотры) и сводка правил — как считается уровень, на что и сколько можно списать, базовый срок жизни баллов, ставки начисления акций. Пример пересчитывается при каждом изменении поля. Пока параметров недостаточно, панель показывает подсказку «Заполните параметры программы — и здесь появится пример, как она сработает для клиента.».
Каталог конфигураций¶
Экран «Конфигурации программы лояльности» состоит из двух вкладок: «Конфигурации» и «История активаций».
На вкладке «Конфигурации» активная конфигурация всегда закреплена первой строкой, независимо от сортировки, и отмечена точкой у названия. Поиск (поле «Введите текст») ищет по названию и по сводке механики.
| Колонка | Содержимое |
|---|---|
| Название | Название конфигурации. Под названием черновика, на котором ещё живут клиенты, — пометка «на ней N клиентов». Колонку нельзя скрыть. |
| Статус | «Черновик» или «Активна». Колонку нельзя скрыть. |
| Уровней | Число уровней в конфигурации. |
| Как считается уровень | «Сумма покупок, ₽» (символ базовой валюты), «Количество покупок» или «Сумма и количество покупок». |
| Механика | Диапазон ставок работающих акций программы, например «3–7 % от чека баллами». Прочерк — ставок нет или они несопоставимы (например, процент от чека и баллы за единицу). |
| Дата изменения | Дата последней правки; фильтр по периоду. |
| Пользователь | Автор последней правки в виде «ФИО (логин)»; фильтр — множественный выбор из авторов. |
Клик по строке выбирает её, двойной клик открывает карточку, правый клик — контекстное меню.
| Действие | Где | Условия |
|---|---|---|
| Добавить конфигурацию | Кнопка над таблицей | LOYALTY_PROGRAM_CONFIG_WRITE; открывает мастер создания. |
| Открыть (редактирование) / Открыть (в режиме чтения) | Контекстное меню | Для чтения открываются активная конфигурация и черновик, на котором есть клиенты. |
| Дублировать | Панель над таблицей, меню, карточка | LOYALTY_PROGRAM_CONFIG_WRITE; одну или несколько. Имя копии задаёт сервер: «(копия)», «(копия 2)» и т. д. |
| Активировать | Панель над таблицей, меню | LOYALTY_PROGRAM_CONFIG_ACTIVATE; ровно одна неактивная конфигурация. Без права — подсказка «Недостаточно прав для активации». |
| Удалить | Панель над таблицей, меню | LOYALTY_PROGRAM_CONFIG_WRITE; только черновики без клиентов. |
Удаление недоступно, если в выборке есть активная конфигурация («Активную конфигурацию удалить нельзя — снимите её из выбора») или черновик с клиентами («На конфигурации ещё есть клиенты — до их пересмотра её нельзя удалить. Снимите её из выбора»). Подтверждение «Удаление конфигурации» предупреждает: «Уровни и настройки внутри будут удалены. Это действие нельзя отменить.». Пакетное удаление выполняется целиком или не выполняется вовсе. Вместе с конфигурацией её уровни вычищаются из условий «Уровень клиента» всех акций.
Мастер создания¶
Кнопка «Добавить конфигурацию» открывает мастер «Новая конфигурация программы» из четырёх шагов; по каждому шагу — один вопрос:
| Шаг | Вопрос |
|---|---|
| 1. Основное | «Основные параметры программы» |
| 2. Акции программы | «Как клиент зарабатывает баллы?» |
| 3. Правила списания | «Как клиент может списывать баллы?» |
| 4. Уровни | «Уровни этой конфигурации» |
Перейти к шагам 2–4 можно только после ввода названия. Внизу — «Отмена» (черновик не создаётся), «Назад», счётчик «Шаг N из 4» и «Далее»; на последнем шаге — «Создать черновик». Базовый уровень создаётся сразу с названием «Базовый» — его можно переименовать. Шаг с ошибкой в правилах списания отмечается на полосе шагов. После создания открывается карточка черновика с сообщением «Конфигурация создана».
Суммы в мастере (пороги уровней, «Сумма покупки от») вводятся в базовой денежной валюте программы из справочника валют и подписываются её символом; мастер получает валюту отдельным запросом и открывается только после её загрузки.
Карточка конфигурации¶
Карточка содержит те же разделы, что и мастер, плюс сводку «Как живут баллы». В шапке — название, статус и кнопка «Дублировать»; внизу у черновика — «Отмена» и «Сохранить» («Изменения сохранены»).
- Активная конфигурация открывается только для просмотра: «Активная конфигурация не редактируется. Дублируйте её, измените копию и активируйте.».
- Черновик, на котором остались клиенты, тоже только для просмотра: «На этой конфигурации ещё N клиентов — до их пересмотра её нельзя менять. Дублируйте её и измените копию.». Клиенты освобождают черновик по мере перехода на активную конфигурацию — при первой операции или на своём пересмотре.
- Если черновик сохранил другой пользователь, сохранение отклоняется: «Конфигурацию изменил другой пользователь. Обновите страницу, чтобы увидеть актуальные настройки.» — со ссылкой «Обновить».
Акции программы¶
Таблица привязанных акций: «Акция» (ссылка на карточку акции), «Статус», «Уровень или сегмент» (пока не заполняется — прочерк), «Ставка» (подпись ставки собирает сервер, например «7 % от чека»), «Период». Кнопка «Добавить акцию» открывает выбор из каталога акций: поиск «Поиск по названию или коду», колонки «Название», «Код», «Дата создания», «Механика», «Статус»; уже привязанные помечены «уже привязана», завершённые и архивные в списке не показываются.
- Привязка не запускает акцию и не меняет её период — акция работает по своим правилам.
- Привязка держится за линию версий акции: новая версия акции привязку не теряет.
- Привязанную акцию нельзя удалить из каталога акций (
422 promotion_bound_to_config); в каталоге акций у неё признакboundToConfig. - «Снять привязку» спрашивает подтверждение; если акция назначена уровням, в подтверждении они перечислены — с уровней акция тоже будет убрана.
- Если акций нет, раздел предупреждает: «Программа не начисляет баллы по базовым правилам — добавьте хотя бы одну акцию.». Сохранить конфигурацию без акций можно.
Правила списания¶
| Настройка | Подпись в интерфейсе | Поле API (redemptionRule) |
|---|---|---|
| Область списания | «Баллы можно списать на»: «любые покупки», «покупки от суммы» («Сумма покупки от»), «только товары из списка», «только категории из списка» | scope: any, min_amount (minPurchaseMinor), product_list (productCodes), category_list (categoryCodes) |
| Максимум за покупку | «Максимум за одну покупку — не более» N «баллов» или «% от чека»; флажок «своё значение на каждом уровне» | max (type FIX/PERCENT, value, mode uniform/per_tier); значение уровня — tiers[].redemptionMax |
| Минимум за раз | «Дополнительные настройки» → «Минимальное списание за раз — не менее» | min |
| Минимальный баланс | «Списание доступно от» N «баллов на балансе» | minBalanceMinor |
| Кратность | «Списывать кратно» N «баллам» | multiplicityMinor |
Ноль — «без ограничения». При режиме «своё значение на каждом уровне» в таблице уровней появляется колонка «Лимит списания, баллов» или «Лимит списания, % чека»; единица одна на все уровни. Товары и категории выбираются из справочников (под правом на чтение акций; без него выбранные коды показываются как есть). Очередь списания по субсчетам задаётся не здесь, а приоритетом субсчёта в разделе «Субсчета баллов».
Списание проверяется по правилам активной конфигурации в порядке: минимальный баланс, область,
минимум и максимум, кратность. Сумма не подгоняется: нарушение отклоняет списание своим кодом —
redemption_below_min_balance, redemption_scope_not_eligible, redemption_below_min,
redemption_above_max, redemption_not_multiple, redemption_items_required (для областей «товары»
и «категории» касса передаёт позиции чека items[] {sku, category, amountMinor} в hold/redeem;
процентный максимум считается от суммы подходящих позиций), redemption_purchase_amount_required.
Минимум и максимум из лимитов по разрезам (уровень, сегмент, валюта) раздела «Настройка ПЛ» по-прежнему
сильнее минимума и максимума конфигурации; минимальный баланс, область и кратность конфигурации
действуют и при них — см. Операционная конфигурация.
Свои правила или общая политика
У новой конфигурации своих правил нет, пока оператор не изменит раздел «Правила списания», — до этого действует общая политика списания раздела «Настройка ПЛ». Сохранённые правила конфигурации вернуть к общей политике нельзя. В снимке активации конфигурации без своих правил выводится «Своих правил не было — действовала общая политика списания из «Настроек».».
Уровни¶
Один уровень. Показывается поле «Название уровня» и пояснение «Все клиенты на уровне «…», он присваивается при регистрации.». Начисление одинаково для всех клиентов — действуют все акции программы. Кнопка «Добавить уровень» превращает раздел в таблицу.
Два и более уровней. Над таблицей — «Механика перехода на следующий уровень»: «Сумма покупок, ₽», «Количество покупок» или «Сумма и количество покупок» (оба условия должны выполниться). Смена механики спрашивает подтверждение «Сменить механику перехода?» и очищает пороги по оси, которая больше не используется.
| Колонка | Содержимое |
|---|---|
| Уровень | Название уровня. У базового уровня — замок: «Базовый уровень нельзя удалить — на него переводятся клиенты при регистрации». |
| Условие перехода | У базового — «При регистрации»; у остальных — нижний порог по сумме и/или количеству покупок. Верхняя граница берётся у следующего уровня, поэтому между уровнями нет ни дыр, ни пересечений. |
| Акции начисления | «Выбрать акции» — какие акции программы начисляют баллы клиентам уровня. Одна акция может стоять на нескольких уровнях, на уровне — несколько акций. |
| Лимит списания | Только при режиме максимума «своё значение на каждом уровне». |
| Срок жизни, дней | Необязательный свой срок жизни баллов уровня (1–3 650). Пустое поле показывает действующий базовый срок валюты, например «365 — базовый», или «не сгорают». |
Правила набора уровней: ровно один базовый уровень с порогом 0 по каждой оси механики; пороги строго растут; при механике «Сумма и количество покупок» обе оси растут вместе; названия не повторяются. Порядок уровней сервер выводит из порогов.
Назначение акций уровню меняет саму акцию
Акции уровня хранятся в условии «Уровень клиента» самих акций — парой «конфигурация + код уровня»
(см. Условия акции). Поэтому сохранение, которое меняет акции уровня,
снимает акцию программы, стоящую на уровне, или удаляет уровень с акциями, требует права
LOYALTY_PROMOTION_WRITE («Недостаточно прав для правки акций: назначение акции уровню меняет саму
акцию»). Условие по уровням черновика действует только на клиентов этого черновика: акция активной
конфигурации от правки черновика не выключается.
Под таблицей — блок «Как клиент получает и теряет уровень», раздел «За какой период считаем»:
| Режим | Настройки | Поле API (tierRecalc) |
|---|---|---|
| «Считать покупки за период» — уровень плавно снижается, если клиент перестал покупать | «Учитываем покупки за» N «дней» (1–365), «проверяем раз в» N «день/неделю/месяц/год» «после перехода на уровень» (от 1 дня до 10 лет) | mode: rolling, windowDays, reviewInterval {count, unit} |
| «Уровень на срок с даты получения» — уровень закреплён на срок; чтобы продлить, нужно снова набрать порог своего уровня | «Уровень действует» N «дней» (1–3 650), флажок «Переносить излишек в новый период» | mode: personal, periodDays, carryOver |
Общего дня пересмотра нет: дата своя у каждого клиента и считается от его перехода на уровень. При пересмотре каждый день интерфейс предупреждает, что клиент потеряет уровень на следующий день после того, как сумма в окне опустится ниже порога. Значения по умолчанию — окно 365 дней с пересмотром раз в месяц. Как это работает для клиента — в разделе Уровни (тиры).
Как живут баллы¶
Сводка только для чтения под разделом «Уровни»: строки — субсчета валюты баллов программы, столбцы — уровни. В ячейке — срок жизни баллов и его источник: «— свой срок субсчёта», «— задано для уровня», «— из валюты», либо «не сгорают» / «в дату …». Срок, заданный в акции, действует вместо указанного здесь. Порядок выбора срока — в разделе Сгорание баллов.
Активация¶
Активировать конфигурацию можно из каталога (панель над таблицей или контекстное меню). Окно «Активировать конфигурацию «…»?» объясняет последствия:
- прежняя активная конфигурация становится черновиком — переключение атомарное;
- новые клиенты сразу попадают на новые правила;
- текущий клиент переходит на новую конфигурацию при первой покупке или списании баллов (в том числе резерве), а если операций не будет — в дату своего пересмотра. До этого он живёт по уровням и порогам прежней конфигурации, и она остаётся «черновиком с клиентами».
Флажок «Отправлять клиентам сообщения о смене уровня» (включён по умолчанию) сохраняется в истории
активаций и передаётся в событии о смене уровня — отправлять ли сообщение, решает получатель события.
Активировать можно только конфигурацию с базовым уровнем (422 config_base_tier_required — «Добавьте
базовый уровень, чтобы активировать конфигурацию»). Нужно отдельное право
LOYALTY_PROGRAM_CONFIG_ACTIVATE — право на правку конфигураций его не даёт.
История активаций¶
Вкладка «История активаций» — неизменяемый журнал: «Дата и время», «Пользователь» («ФИО (логин)»), «Конфигурация» (ссылка на карточку), «Была активна до», «Уведомления» («Отправлялись» / «Нет»). Двойной клик по строке открывает снимок «Снимок «…» на <дата>» — настройки, акции, правила списания и уровни на момент активации, только для просмотра.
Роли¶
| Роль | Возможности |
|---|---|
LOYALTY_PROGRAM_CONFIG_READ |
Пункт меню, каталог, карточка, история активаций и снимки. |
LOYALTY_PROGRAM_CONFIG_WRITE |
Создание, правка черновика, дублирование, удаление. |
LOYALTY_PROGRAM_CONFIG_ACTIVATE |
Активация конфигурации. |
LOYALTY_PROMOTION_WRITE |
Дополнительно — для сохранения, которое меняет акции уровней. |
API¶
| Метод и путь | Назначение | Роль |
|---|---|---|
GET /v1/program-configs |
Каталог: search, updatedFrom/updatedTo, updatedBy (список id), страница и сортировка |
LOYALTY_PROGRAM_CONFIG_READ |
GET /v1/program-configs/{id} |
Конфигурация с уровнями, акциями и правилами | LOYALTY_PROGRAM_CONFIG_READ |
POST /v1/program-configs |
Создать черновик вместе с набором уровней | LOYALTY_PROGRAM_CONFIG_WRITE |
PATCH /v1/program-configs/{id} |
Изменить черновик (набор уровней — целиком); If-Match: <version> |
LOYALTY_PROGRAM_CONFIG_WRITE |
DELETE /v1/program-configs/{id}, POST /v1/program-configs/bulk-delete |
Удалить черновик / выбранные черновики | LOYALTY_PROGRAM_CONFIG_WRITE |
POST /v1/program-configs/duplicate |
Дублировать одну или несколько | LOYALTY_PROGRAM_CONFIG_WRITE |
POST /v1/program-configs/{id}/activate |
Активировать; тело {notifyCustomers} |
LOYALTY_PROGRAM_CONFIG_ACTIVATE |
GET /v1/program-configs/activations, .../activations/{activationId} |
История активаций и снимок | LOYALTY_PROGRAM_CONFIG_READ |
GET /v1/program-configs/authors |
Авторы изменений — опции фильтра «Пользователь» | LOYALTY_PROGRAM_CONFIG_READ |
GET /v1/program-configs/base-currency |
Базовая денежная валюта {baseCurrency: {code, symbol, precision}} |
LOYALTY_PROGRAM_CONFIG_READ |
Тело POST/PATCH: name, tiers[] (code, name, thresholdMinor, entryCount, promotionIds[],
redemptionMax, pointsExpiryDays), programPromotions[] (id акций), tierMetric
(amount/count/both), tierRecalc, redemptionRule. Отсутствующие programPromotions,
tiers[].promotionIds и redemptionRule при правке означают «не менять». Отсутствующие tierMetric и
tierRecalc, наоборот, не означают «не менять»: без tierMetric механика становится «сумма покупок»,
без tierRecalc — режим скользящего окна. Их передают при каждом сохранении.
Ответ дополнительно содержит status (draft/active), version, updatedAt, updatedBy
(UserRef {id, displayName, login}), programPromotions[] с подписью ставки rateLabel и периодом
startsAt/endsAt, у уровня — ordinal и работающие акции promotions[], mechanicSummary (диапазон
ставок, null — несопоставимы), customersCount (сколько клиентов ещё живут по черновику; у активной —
null) и baseCurrency (code, symbol, precision; суммы конфигурации — в минорных единицах этой
валюты).
BREAKING (26.3.0)
- Уровни записываются только в составе конфигурации:
PUT/DELETE /v1/tiers/{code}удалены, кодtier_ordinal_taken— тоже.GET /v1/tiersостался на чтение. updatedByконфигурации иactivatedByактивации — объектUserRef, а не строка; фильтрupdatedBy— список id.- Блок
defaultPointsExpiryконфигурации и кодconfig_tier_points_expiry_requiredудалены: базовый срок жизни баллов — у валюты, у уровня — необязательныйpointsExpiryDays. - Условие акции «Уровень клиента» — список пар
params.conditions.client.levels [{configId, code}]вместо строкиlevel.
Коды ошибок¶
| HTTP | Код | Когда |
|---|---|---|
| 404 | config_not_found |
Конфигурации нет. |
| 409 | config_name_duplicate |
Название уже занято. |
| 422 | config_active_readonly |
Попытка изменить активную конфигурацию. |
| 422 | config_has_customers |
Правка или удаление черновика, на котором есть клиенты. |
| 422 | config_active_undeletable |
Удаление активной (в пакете — отказ всему запросу). |
| 409 | config_already_active |
Конфигурация уже активна. |
| 422 | config_base_tier_required |
Активация без базового уровня. |
| 409 | version_conflict |
Черновик изменён другим пользователем (If-Match). |
| 409 | tier_code_duplicate, tier_name_duplicate |
Код или название уровня повторяется в наборе. |
| 422 | tier_threshold_required |
Не задан порог по оси механики перехода. |
| 422 | tier_threshold_not_monotonic |
Пороги не растут строго. |
| 422 | tier_base_threshold_required |
Нет уровня с нулевым порогом. |
| 422 | tier_base_undeletable |
Из набора исключён прежний базовый уровень. |
| 404 | promotion_not_found |
Привязываемой акции нет. |
| 422 | promotion_not_bindable |
Завершённую или архивную акцию нельзя привязать; неработающую — назначить уровню. |
| 422 | promotion_not_in_program |
Акция уровня не входит в акции программы. |
| 403 | access_denied |
Сохранение меняет акции уровней без LOYALTY_PROMOTION_WRITE. |
| 400 | validation_failed |
Значение вне диапазона (срок уровня, окно, период, правила списания) — с путём поля. |
Полный реестр — Коды ошибок.