Настройка акции

Экран «Администрирование» → «Настройка акции» — реестр условий, из которых маркетолог собирает вкладку «Условия» акции. Здесь администратор видит коробочные условия продукта, скрывает ненужные заказчику, задаёт порядок и добавляет свои условия — на переменную, которую касса передаёт в покупке, или на поле профиля клиента. Новое отраслевое условие (бренд, номер тиража, регион клиента) появляется в форме акции без доработки продукта.

Как маркетолог заполняет условия в акции и как они проверяются при покупке — в разделе «Условия акции».

Доступ

Просмотр экрана — право LOYALTY_DICTIONARY_READ, изменения — LOYALTY_DICTIONARY_WRITE. Без права записи экран открывается только для чтения: кнопки «Добавить» и «Сохранить», переключатели и перетаскивание недоступны, пункты меню строки неактивны, форма условия открывается для просмотра с кнопкой «Закрыть».

Состав экрана

Над списком — кнопка «Добавить», в шапке — «Сохранить». Пока на экране есть несохранённые правки, рядом видны надпись «Есть несохранённые изменения» и кнопка «Отменить изменения» (подтверждение «Отмена изменений» — «Вы уверены, что хотите отменить все несохранённые изменения? Действие необратимо»).

Колонка	Содержимое
«Условие»	Название и тег «Коробочное» или «Добавлено»; у ещё не сохранённого — тег «Новое, не сохранено». У добавленного условия второй строкой — источник: «Из входящего события — ‹переменная›» или «Из профиля — ‹поле›»
«Тип значения»	Способы задать значение добавленного условия через « — », например «Из справочника «Бренды» — Ручной ввод, текст»; у коробочного пусто
«Где доступно»	«Применяется и не применяется», «Только применяется» или «Только не применяется»
«Показывать в акции»	Переключатель: предлагать ли условие в новых акциях

Порядок строк меняется перетаскиванием — в этом порядке условия стоят на вкладке «Условия» акции. Щелчок по строке добавленного условия открывает его форму, правый щелчок — меню «Изменить» и «Удалить условие». Строка коробочного условия форму не открывает.

Все правки — добавление, изменение, скрытие, порядок, удаление — копятся на экране и сохраняются одним запросом по кнопке «Сохранить». Если хотя бы одна правка не проходит проверку, не сохраняется ничего. При закрытии или перезагрузке вкладки браузера с несохранёнными правками браузер предупреждает об их потере.

Коробочные условия

Продукт поставляется с девятью коробочными условиями: «Категории товаров», «Артикулы (SKU)», «Регион», «Город», «Магазин», «Мерчант», «Канал продаж», «Сегменты клиентов», «Сумма чека». У коробочного условия можно только скрыть его переключателем «Показывать в акции» и переставить; название, подсказки, зоны и правило сравнения зашиты в продукт.

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

Добавленное условие

Кнопка «Добавить» открывает окно «Новое условие» (у существующего — «Изменить условие»):

Поле	Назначение
«Название»	Подпись условия в акции, обязательное, до 255 символов
«Добавить подсказку»	Чекбокс открывает поля «Подсказка, когда акция применяется» и «Подсказка, когда акция не применяется» (до 1000 символов) — они показываются у названия условия в своей зоне акции
«Выбрать переменную»	Источник значения: «Из входящего события» или «Из профиля клиента»
«Название переменной» / «Поле профиля»	Имя переменной покупки или поле профиля клиента
«Способы задать значение»	Один или несколько способов (см. ниже)
«Где доступно»	«Обе зоны», «Только «Акция применяется, если»» или «Только «Не применяется, если»»

Кнопка «Готово» кладёт условие в список экрана — в базу оно попадает только по «Сохранить».

Код условия собирается сам: purchase.<переменная> для переменной покупки и customer.<код поля> для поля профиля. Одна переменная — одно условие, регистр не различается: повтор отклоняется ещё в форме — «Переменная «X» уже используется в условии «Y»».

Переменная из входящего события

Касса или внешняя система передаёт в покупке произвольные переменные «название — значение»: в чеке кассы — на весь чек и у каждой позиции (attributes), в событии покупки — на всю покупку. Формат переменных в покупке — в разделе «Интеграции». Название переменной — латиница, цифры, «» и «-», не длиннее 64 символов (иначе «Латиница, цифры, «» и «-», не больше 64 символов»).

Под полем «Название переменной» — статистика прихода переменной за последние 7 дней: сколько покупок пришли с ней, где она приходит («в позициях чека», «в чеке», «в позициях чека и в чеке») и последние значения, например «За 7 дней: 12 покупок, в позициях чека. Последние значения: 105, 106, 107». Если у условия выбран тип значения «Число» или «Дата» и за эти дни приходили значения, которые так не разбираются, статистика показывает ещё «Не разобрано как число или дата: N». Если переменная не приходила — «За 7 дней покупок с этой переменной не было. Проверьте переменную и интеграцию»: ошибка в названии иначе незаметна, а акция просто не сработает. Семь дней считаются по операционным дням программы, включая текущий.

Поле профиля клиента

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

Тип поля	Допустимые способы
Строка	«Ручной ввод», текст
Число	«Ручной ввод» и «Диапазон», число
Дата	«Ручной ввод» и «Диапазон», дата
Список из справочника	«Из справочника» — справочник самого поля, сравнение по коду

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

Способы задать значение

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

Способ	Настройки	Как сравнивается
«Из справочника»	«Название справочника» — любой справочник продукта; «Переменная» — с чем сравнивается значение: «Код» или «Название» записи; «Можно выбрать несколько значений»	значение переменной равно коду или названию одной из выбранных записей
«Ручной ввод»	«Тип значения»: «Текст», «Число» или «Дата»	значение равно одному из введённых
«Диапазон»	«Тип значения»: «Число» или «Дата»	значение попадает в границы, границы включительны

Значение сравнивается с переменной без учёта регистра и пробелов по краям; если значений несколько, условие выполнено, когда переменная совпала с любым из них. Число передаётся с десятичной точкой без разделителей разрядов, дата — в формате ГГГГ-ММ-ДД; значение другого вида считается отсутствующим.

Изменение условия, которое уже используется

Если условие заполнено хотя бы в одной акции (в любом статусе, в том числе в архиве), у него нельзя изменить источник, переменную или поле профиля, снять или изменить способ, выбранный в акциях (с его справочником и полем сравнения), и снять зону, в которой условие заполнено. Форма у такого условия строже: недоступны источник и переменная, настройки всех уже сохранённых способов и варианты «Где доступно», которые сняли бы сохранённую зону. Отказ сервера показывается текстом «Условие «X» уже используется в акциях — эти поля изменить нельзя». Название, подсказки, порядок и показ меняются всегда; добавить способ или зону можно.

Скрытие условия

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

Удаление условия

«Удалить условие» — из меню строки или кнопкой в форме условия:

• ещё не сохранённое условие удаляется сразу — «Условие «X» удалено — оно ещё не было сохранено»;
• сохранённое — после подтверждения «Удаление условия»; если условие заполнено в акциях, в подтверждении предупреждение «Условие заполнено в акциях. Если среди них есть работающие, сохранение отклонит удаление».

Удаление проверяется при «Сохранить». Условие, заполненное в акциях со статусом «Активна», «Пауза» или «Запланирована», удалить нельзя: открывается окно «Удаление условия» — «Условие используется в акциях. Чтобы удалить его, уберите его из этих акций или дождитесь их завершения» — с таблицей «Акция» (ссылка на акцию), «Статус», «Период действия». Все такие условия возвращаются в список, остальные правки экрана остаются несохранёнными.

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

Одновременная правка

Если реестр успел изменить другой администратор, сохранение отклоняется, и над списком появляется сообщение «Настройку акции изменил другой пользователь. Обновите страницу и повторите.» Правки экрана при этом остаются, а «Отменить изменения» возвращает экран к свежей версии реестра.

Предупреждение при запуске акции

При запуске кнопкой «Запустить» в шапке формы акции с дополнительным условием на переменную покупки система проверяет, приходила ли переменная за последние 7 дней. Если нет, окно запуска предупреждает: «Переменная «X» за последние 7 дней не приходила в покупках — условие «Y» может не сработать». Запуск это не блокирует. Запуск из каталога акций и со страницы акции в режиме чтения такого предупреждения не показывает.

REST API

Метод и путь	Право	Назначение
GET /v1/admin/promotion-criteria	LOYALTY_DICTIONARY_READ	Реестр целиком: revision и условия с code, origin (BOX/CUSTOM), label, hintInclude, hintExclude, source (PURCHASE/CUSTOMER), attributeKey, methods, zones, visible, sortOrder, usedInPromotions
PUT /v1/admin/promotion-criteria	LOYALTY_DICTIONARY_WRITE	Сохранить реестр целиком и атомарно: {criteria: [...]} в порядке формы, новое условие — без code, отсутствующее в списке добавленное условие удаляется. Ревизия из GET — в заголовке If-Match
GET /v1/admin/promotion-criteria/attribute-stats?key=	LOYALTY_DICTIONARY_READ	Статистика переменной покупки за 7 операционных дней, включая текущий (periodDays): число покупок, из них с переменной у позиций и на весь чек, unparsed по типам NUMBER и DATE, до пяти последних значений
GET /v1/promotions/criteria	LOYALTY_PROMOTION_READ	Условия для вкладки «Условия» акции: только показываемые и исполняемые, в порядке реестра
GET /v1/promotions/{id}/criteria/attribute-activity	LOYALTY_PROMOTION_READ	По каждому дополнительному условию акции на переменную покупки — число покупок с ней за те же 7 операционных дней

Способ в methods — {kind, refDict, refField, multiple, valueType}: kind — REF_LIST, MANUAL или RANGE; refDict и refField (CODE/NAME) — у REF_LIST; valueType — TEXT, NUMBER или DATE (у RANGE — только NUMBER и DATE). Зоны — INCLUDE и EXCLUDE.

Статистика переменных хранится с запасом над окном в 7 дней — срок задаёт loyalty.purchase-attributes.stats-retention (по умолчанию P30D, 30 дней). Уборку по сроку включает расписание loyalty.purchase-attributes.cleanup-cron; по умолчанию оно выключено.

Ошибки

Код	HTTP	Когда
validation_failed	400	Пустое название или зоны, у нового условия нет источника или переменной, неизвестный код, повтор кода в запросе; недопустимое название переменной в запросе статистики attribute-stats
criterion_box_immutable	422	Изменение или удаление коробочного условия, кроме показа и порядка
criterion_key_invalid	422	Недопустимое название переменной; поля профиля нет или оно в архиве
criterion_key_duplicate	422	Переменная уже занята другим условием
criterion_method_invalid	422	У добавленного условия нет способов, способ повторён, справочник неизвестен, тип значения недопустим или способ не подходит полю профиля
criterion_locked_after_use	422	Изменение полей условия, заполненного в акциях: источник, переменная, справочник, поле сравнения, использованный способ, заполненная зона
criterion_in_use	409	Удаление условий, заполненных в работающих акциях; в теле — все такие условия criteria [{code, label}] и акции promotions, каждая один раз
version_conflict	409	Реестр уже изменил другой администратор
version_required	428	Сохранение без заголовка If-Match
profile_field_used_in_criterion	409	Удаление поля профиля, на котором построено условие; в теле — условия criteria [{code, label}], в пакетном удалении полей — то же в строке errors[]

В отказах criterion_box_immutable, criterion_locked_after_use и criterion_method_invalid условие, на котором остановилась проверка, приходит в теле полем criterion {code, label}; у criterion_key_duplicate в этом поле — условие, которое уже заняло переменную.