Метки акций¶
Метка акции — значение из отдельного справочника, которым маркетолог объединяет акции в кампанию. По меткам работают фильтр каталога акций и условие «участие в акциях»: клиент, поучаствовавший в помеченной акции, попадает в «группу метки», на которую нацеливаются другие акции (см. Условия акции). На клиенте метка не хранится.
Метка не заменяет поле «Группа акций»:
| Группа акции | Метка акции | |
|---|---|---|
| Сколько значений у акции | одно | ноль или несколько |
| Зачем | классификация для человека, поиск и фильтр каталога | набор акций для условий отбора клиентов |
| Действие во времени | описательное | ретроактивное: пометили идущую акцию — её прошлые участники сразу попали в наборы условий, сняли метку — вышли |
Носитель метки — версия акции
Метка стоит на конкретной версии акции. Метка на трёх версиях одной акции даёт счётчик «Акций» = 3.
Права¶
| Право | Что даёт |
|---|---|
LOYALTY_PROMOTION_LABEL_READ |
Справочник меток: экран, поиск, карточка значения; колонка и фильтр «Метки» в каталоге акций, поле «Метки» в карточке акции |
LOYALTY_PROMOTION_LABEL_WRITE |
Изменение справочника: добавление, переименование, слияние, удаление, выгрузка и загрузка бандла; создание метки из поля «Метки» |
LOYALTY_PROMOTION_WRITE |
Проставление и снятие меток у акций (это атрибут акции, а не правка справочника) |
Маркетологу по умолчанию выдаются оба права на справочник. Общие права на справочники
(LOYALTY_DICTIONARY_*) справочник меток не открывают.
Справочник меток акций¶
Экран открывается из реестра справочников: «Администрирование» → «Справочники» → «Метки акций». Строка справочника видна только с правом чтения меток. Вернуться в реестр — ссылка «← Справочники».
Состав экрана¶
| Элемент | Назначение |
|---|---|
| Поле «Поиск по значению метки…» | Подстрока значения без учёта регистра, поиск серверный |
| Колонка «Значение» | Значение метки; сортировка по алфавиту (по умолчанию — по возрастанию) |
| Колонка «Акций» | Число акций-носителей; сортируется, в заголовке — фильтр «С акциями» / «Без акций» |
| «Выгрузить бандл», «Импортировать», «Добавить метку» | Действия справочника; без права записи кнопок нет |
Размер страницы — 10, 15 или 20 записей. Поиск, фильтр, сортировка и страница действуют только в текущем сеансе работы с экраном и между открытиями не сохраняются. Пустой справочник показывает «Справочник пуст» и кнопку «Добавить метку»; пустой результат поиска — «Ничего не найдено» и «Сбросить фильтры».
Выбор строк чекбоксами включает панель внизу («Выбрана 1 метка» / «Выбрано меток: N») с кнопкой «Удалить». Двойной клик по строке открывает карточку значения; правый клик — меню: «Открыть», «Переименовать», «Объединить с другой меткой…», «Удалить» (пункты правки видны только с правом записи).
Значение метки¶
Значение нормализуется на сервере: краевые пробелы обрезаются, внутренние пробелы схлопываются в
один, регистр приводится к нижнему. Запрещены символы ; и , (разделители списков) и управляющие
символы. Длина — от 1 до 60 символов. Значения уникальны: одно и то же значение дважды в справочнике
не заводится.
Добавление и переименование¶
«Добавить метку» открывает окно «Добавить метку» с полем (подсказка «например, nloto-summer») и счётчиком длины. Занятое значение — ошибка «Метка «X» уже есть в справочнике.» и подсказка «Переименуйте её иначе или объедините эти две метки в одну.» с переходом к слиянию («Объединить с «X»»). Успех — «Метка «X» добавлена».
«Переименовать» правит одну запись: акции-носители и условия других акций сразу показывают новое значение — обходить акции не нужно. Успех — «Метка «X» переименована в «Y»». Если метку одновременно изменил другой пользователь, операция отклоняется: «Метка изменена другим пользователем. Обновите список и повторите.»
Объединение синонимов¶
«Объединить с другой меткой…» сливает выбранную метку (источник) в цель, выбранную из справочника. Окно показывает последствия до подтверждения:
- «Останется одна метка — «цель».»;
- «N акций с меткой «источник» получат вместо неё «цель».» — носители переходят к цели без дублей;
- «Условия акций, которые отбирают по метке «источник», начнут отбирать по «цель» — они продолжат работать.» Ссылки переписываются и в работающих акциях, слиянию они не мешают;
- «Метка «источник» будет удалена из справочника. Отменить это действие нельзя.»
Успех — «источник» объединена с «цель».
Удаление¶
Удаление необратимо и каскадно снимает метку со всех акций-носителей. Перед подтверждением окно «Удаление метки» показывает, где метка используется:
| Ситуация | Поведение |
|---|---|
| Метка стоит в условиях работающих акций (Активна, Пауза, Запланирована; архивность не важна) | Удаление недоступно: «Удалить нельзя: метка используется в условиях работающих акций (N). Чтобы удаление стало доступно, уберите метку из их условий.» |
| Метка присвоена акциям и/или используется в условиях черновиков и завершённых акций | Удаление доступно, последствия названы: «Метка «X» будет снята с N акций — это действие нельзя отменить.» и «Она также используется в условиях N акций (черновики и завершённые) — эти условия станут недействительными, запустить такие акции будет нельзя, пока условие не поправят.» |
| Метка нигде не используется | «Метка «X» не присвоена ни одной акции и не используется в условиях.» |
| Проверку не удалось выполнить | Удаление недоступно: «Не удалось проверить, где используется метка. Удаление недоступно — попробуйте ещё раз.» |
Ниже выводится таблица связанных акций (см. Карточка метки). Если акцию запустили в тот момент, когда окно уже открыто, удаление отклоняется: «Удалить не удалось: метка используется в условиях работающей акции. Обновите окно — список акций изменился.»
Массовое удаление (кнопка «Удалить» на панели выделения) проверяет все выбранные метки сразу: строки с блокирующими акциями отмечены замком, сняты с удаления и не отмечаются; сводка — «Выбрано значений: N. Будет удалено: M. Не будет удалено: K — используются в условиях работающих акций.», кнопка «Удалить {M}». Развернув строку, можно посмотреть её акции. Больше 200 меток за раз проверить нельзя — «Часть выбранных меток может использоваться в условиях работающих акций — проверить их сразу нельзя. Удаляйте меньшими группами.»
Каждая метка удаляется отдельно: успешно удалённые не откатываются. Итог — окно с перечнем необработанных и причинами («Не найдена — возможно, уже удалена», «Изменена другим пользователем»). Если запрос не прошёл целиком — «Удаление не выполнено. Ни одна метка не удалена.» или «Удаление прервано. Часть меток могла быть удалена — обновите список и проверьте перед повторным запуском.»
Карточка метки¶
Двойной клик по строке или пункт «Открыть» открывает карточку «Метка «X»» (только чтение):
- «Значение», «Присвоена акциям» (число носителей), «Создана»;
- блок «Используется в условиях N акций» — таблица связанных акций: «Акция» (ссылка, открывается в новой вкладке), «Статус» (тег статуса и «В архиве»), «Период действия». Акции, которые не дают удалить метку, помечены замком и идут первыми; остальные — значком фильтра («Акция отбирает по этой метке»);
- по умолчанию показаны только блокирующие статусы («Показаны статусы: Активна, Пауза, Запланирована»), переключатель «Показать все статусы» снимает ограничение. Кнопка «Показать ещё» догружает следующие акции.
Если метка в условиях не используется — «Эта метка не используется в условиях акций» (или «…в этих статусах»).
Перенос справочника между контурами¶
«Выгрузить бандл» сохраняет все значения справочника в JSON-файл
(promotion-labels-ГГГГ-ММ-ДД.json). «Импортировать» загружает такой файл: импорт добавляет
только недостающие значения, существующие не меняются, ничего не удаляется, связи меток с акциями
бандл не переносит. Итог — «Добавлено меток: N, пропущено: M». Файл не того вида — «Файл не похож на
бандл справочника меток. Выгрузите его кнопкой «Выгрузить бандл» в исходном контуре.»; недопустимое
значение внутри файла отклоняет импорт целиком — «В файле есть значения, которые не проходят проверку.
Импорт не выполнен — ни одна метка не добавлена.»
Метки на акции¶
Поле «Метки» находится в карточке акции на вкладке «Общие данные», сразу после «Группы акций» (и в блоке просмотра акции). Значения выбираются только из справочника — свободного ввода нет.
- У новой, ещё не сохранённой акции поле работает как обычное поле формы: выбранные метки уходят вместе с созданием акции. Если метку удалили из справочника, пока форма была открыта, появляется ошибка «Метка «X» удалена из справочника — уберите её из выбора».
- У сохранённой акции поле сохраняется сразу, отдельной операцией, в любом статусе — включая активную, завершённую и архивную акцию и заблокированную для правки форму (подсказка «Метки можно менять в любом статусе — они не влияют на начисления»). Кнопка «Сохранить» формы метки не затрагивает.
- Снятие метки подтверждается: «Снять метку «X»?» — «Участники этой акции перестанут попадать в условия других акций по метке «X» — их число участий по этой метке уменьшится. Действие можно отменить, вернув метку.»
- Иконка копирования рядом с полем (подсказка «Скопировать список») копирует выбранные значения через «;» — доступна и в режиме чтения, пока у акции есть метки; крестик очистки в поле снимает весь набор — открывает окно «Снять метки» по этой акции.
- С правом
LOYALTY_PROMOTION_LABEL_WRITEметку можно завести прямо из поля: если в выдаче ничего не найдено, появляется «Создать метку «X»». - Без права
LOYALTY_PROMOTION_WRITEполе доступно только для чтения.
Проставление или снятие метки не меняет саму акцию: её версия и дата изменения остаются прежними, начисления не затрагиваются.
Метки в каталоге акций¶
В каталоге акций метки представлены:
- колонкой «Метки» (видна по умолчанию) — чипсы со значениями;
- фильтром в заголовке колонки: множественный выбор из справочника и способ совпадения «Любая из выбранных» (по умолчанию) или «Все выбранные»;
- действиями «Проставить метки…» и «Снять метки…» в контекстном меню строки и на панели массовых действий — в любом статусе и при любом признаке архива.
Окно «Проставить метки» содержит счётчик «Выбрано акций: N» и селектор меток; окно «Снять метки» — перечень меток выбранных акций с чекбоксами (все отмечены; «У выбранных акций нет меток», если метки отсутствуют). Одна акция — итог сообщением; несколько — окно «Выполняется…» и отчёт по каждой акции («Название акции», «Статус акции», «Причина») с пометкой «Успешно обработанные акции остаются обработанными — изменения не откатываются.»
За один раз метки проставляются или снимаются максимум 10 000 акциям и не больше 200 меток. Если метку успели удалить из справочника, запрос отклоняется целиком: «Метки уже нет в справочнике — обновите страницу.» Метки проверяются в той же транзакции, что и запись: удаление или слияние метки, начатое во время проставления, дождётся его окончания, поэтому метка из набора молча не выпадает.
Метки и версии акции¶
| Действие | Что происходит с метками |
|---|---|
| Новая версия акции | новая версия получает метки исходной; дальше метки у каждой версии свои |
| «Сохранить как» (копия) | копия создаётся без меток — это новая кампания |
| Перенос между контурами | бандл акций несёт метки значениями; импорт находит их без учёта регистра и заводит недостающие вместе с акцией |
| Удаление акции | метки снимаются вместе с удалённым черновиком |
Условие «участие в акциях» считает метку по тем версиям, которые несут её в момент проверки: проставленная метка меняет группу задним числом.
История изменения меток акции¶
Каждое фактическое изменение набора меток акции фиксируется: проставлена, снята, снята вместе с удалением метки из справочника, заменена при слиянии — со значением метки словами и автором изменения. Отдельного экрана истории у акции пока нет.
REST API¶
| Метод и путь | Право | Назначение |
|---|---|---|
GET /v1/promotion-labels |
LOYALTY_PROMOTION_LABEL_READ |
Список: search, hasPromotions, withCounts (число акций-носителей), sort=value\|createdAt\|updatedAt\|promotionsCount, page, size; ids= — метки по идентификаторам одной страницей (до 200) |
POST /v1/promotion-labels |
LOYALTY_PROMOTION_LABEL_WRITE |
Завести метку; значение нормализуется на сервере |
PATCH /v1/promotion-labels/{labelId} |
LOYALTY_PROMOTION_LABEL_WRITE |
Переименовать; версия записи — в заголовке If-Match |
POST /v1/promotion-labels/{labelId}/merge |
LOYALTY_PROMOTION_LABEL_WRITE |
Слить метку-источник в эту метку — цель адресуется путём (её версия — в заголовке If-Match), источник и его версия — телом {sourceId, sourceVersion} |
POST /v1/promotion-labels/bulk-delete |
LOYALTY_PROMOTION_LABEL_WRITE |
Удалить метки ({items[{labelId, version}]}, до 10 000) со снятием со всех носителей |
POST /v1/promotion-labels/lookup |
LOYALTY_PROMOTION_LABEL_READ |
Массовая проверка наличия по значениям (до 1000): найденные с id, ненайденные — как пришли; ничего не заводит |
GET /v1/promotion-labels/{labelId}/condition-promotions |
LOYALTY_PROMOTION_LABEL_READ |
Акции, связанные с меткой: носители (CARRIER) и отбирающие по ней в условиях (CONDITION); блокирующие удаление — первыми |
GET /v1/promotion-labels/condition-promotions?ids= |
LOYALTY_PROMOTION_LABEL_READ |
Свод по меткам (до 200): число связанных и блокирующих акций |
GET /v1/promotion-labels/export |
LOYALTY_PROMOTION_LABEL_WRITE |
Выгрузить справочник бандлом |
POST /v1/promotion-labels/import |
LOYALTY_PROMOTION_LABEL_WRITE |
Загрузить бандл (файлом); недостающие значения добавляются |
POST /v1/promotions/bulk-label-assign |
LOYALTY_PROMOTION_WRITE |
Проставить метки акциям ({promotionIds[], labelIds[]}, до 10 000 акций и до 200 меток) |
POST /v1/promotions/bulk-label-remove |
LOYALTY_PROMOTION_WRITE |
Снять метки; снятие отсутствующей метки ошибкой не считается |
Метки новой акции передаются в POST /v1/promotions: labelIds — только существующие метки (так
отправляет форма), labels — значениями (так передают интеграции). Недостающее значение заводится
только при праве LOYALTY_PROMOTION_LABEL_WRITE, иначе запрос отклоняется с перечнем недостающих.
Создание атомарно. PUT /v1/promotions/{id} метки не принимает.
Пределы пакетов настраиваются: loyalty.promotion-labels.max-bulk-targets (10 000 — акций в пакете
меток и меток в пакетном удалении), max-batch-ids (200 — идентификаторов в запросах ids= и меток в
пакете проставления или снятия), max-lookup-values (1000). Превышение — 400 bulk_size_exceeded.
Коды ошибок¶
| Код | HTTP | Когда |
|---|---|---|
label_not_found |
404 | метки нет в справочнике (в том числе в пакете проставления меток) |
label_already_exists |
409 | значение занято другой меткой; ответ называет занявшую запись |
label_value_invalid |
422 | значение не проходит правило (пусто, запрещённые символы, длиннее 60) |
label_merge_into_itself |
422 | попытка слить метку саму с собой |
label_in_use |
409 | метка, стоящая в условиях работающей акции, — как строка отчёта пакетного удаления (одиночного и массового) |
label_bundle_invalid |
422 | файл не является бандлом меток или его не удалось прочитать |
unknown_label |
422 | при создании акции переданы метки, которых нет в справочнике (и нет права их завести) |
promotion_labels_not_accepted |
400 | метки переданы в PUT /v1/promotions/{id} |
version_conflict |
409 | запись изменена другим пользователем (переименование, слияние, удаление) |
version_required |
428 | не передана версия записи в If-Match |
bulk_size_exceeded |
400 | превышен предел размера пакета или списка идентификаторов |