Теги клиента

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

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

Правила значения тега

Значение нормализуется на сервере:

• краевые пробелы обрезаются, повторяющиеся пробелы внутри схлопываются в один;
• значение приводится к нижнему регистру;
• длина — от 1 до 60 символов;
• запрещены символы ;, , и управляющие символы (в форме — подсказка «Значение не должно содержать «;», «,» и переводов строки»).

Нарушение — отказ 422 tag_value_invalid. Значение уникально без учёта регистра: попытка завести или переименовать тег в занятое значение — 409 tag_already_exists с указанием занявшей записи (conflictingTagId).

Сопоставление везде идёт по нормализованному виду: VIP находит и присваивает vip.

Справочник тегов

Экран открывается из Администрирование → Справочники → «Теги клиентов» (строка видна только при роли LOYALTY_TAG_READ). Заголовок экрана — «Справочник тегов».

Элемент	Назначение
Поиск «Поиск по значению тега…»	Подстрока значения без учёта регистра, по всему справочнику
Флажок «Без клиентов»	Только теги, не присвоенные никому — для уборки справочника
«Выгрузить бандл» / «Импортировать»	Перенос значений между контурами
«Добавить тег»	Завести значение
Таблица «Значение»	Сортировка по значению, страницы по 10/15/20

Двойной клик по строке (или пункт «Открыть») открывает карточку значения. Правый клик — меню: «Открыть», «Переименовать», «Объединить с другим тегом…», «Удалить». Кнопки и пункты изменения показываются только при роли LOYALTY_TAG_WRITE; роли с просмотром остаётся «Открыть». Числа носителей в списке нет — есть только признак «есть носители» (он же фильтр).

Создание и переименование

• «Добавить тег» — поле значения со счётчиком длины; значение нормализуется на сервере. Тост «Тег «vip» добавлен».
• «Переименовать тег «vip»» — то же поле с текущим значением. Тост «Тег «vip» переименован в «vip-клиент»». Новое значение немедленно видно у всех носителей; записей в историю клиентов переименование не делает.

Правка идёт с контролем версии записи: если тег изменил другой пользователь, форма отвечает «Тег изменён другим пользователем. Обновите список и повторите.» (409 version_conflict). При попытке переименовать тег в уже занятое значение форма предлагает объединить два тега в один.

Слияние синонимов

Пункт «Объединить с другим тегом…» открывает окно «Объединить «вип» с другим тегом»: выбирается тег-цель, окно показывает последствия — сколько клиентов с тегом-источником получат вместо него целевой, что условия акций, отбирающие по источнику, начнут отбирать по цели и продолжат работать, и что источник будет удалён безвозвратно.

• Носители источника получают целевой тег без дублей.
• Клиенту, у которого целевой тег уже был, набор тегов не меняется и запись в историю не делается.
• Запись источника удаляется, ссылки в условиях акций переписываются на цель.
• Слияние тега с самим собой — 422 tag_merge_into_itself.

Карточка значения

Карточка «Тег «vip»» показывает значение и таблицу акций, которые отбирают по этому тегу в условиях аудитории: «Акция», «Статус», «Период действия». По умолчанию выводятся акции в статусах «Активна», «Пауза», «Запланирована» — именно они блокируют удаление (у таких строк иконка замка с подсказкой «Эта акция не даёт удалить значение»); переключатель «Показать все статусы» добавляет черновики и завершённые.

Удаление

Удаление тега снимает его у всех клиентов-носителей и необратимо.

• Тег, стоящий в условии работающей акции (статусы «Активна», «Пауза», «Запланирована»; архивность акции не важна), удалить нельзя: «Удалить нельзя: тег используется в условиях работающих акций (N). Чтобы удаление стало доступно, уберите тег из их условий.» (код tag_in_use).
• Если тег стоит только у клиентов и в условиях неработающих акций, окно называет последствия: «Тег «vip» будет снят у N клиентов — это действие нельзя отменить» и, при наличии, «Он также используется в условиях N акций (черновики и завершённые) — эти условия станут недействительными, запустить такие акции будет нельзя, пока условие не поправят».
• Если носителей и связей нет — «Тег «vip» не присвоен ни одному клиенту и не используется в условиях».
• Если проверить связи не удалось, удаление недоступно: «Не удалось проверить, где используется тег.»

Массовое удаление. Отметьте строки в таблице — внизу появится «Выбрано тегов: N» и красная кнопка «Удалить». Окно «Удаление тегов» показывает по каждому тегу число носителей и связанных акций, а сводкой — «Выбрано значений: N. Будет удалено: M. Не будет удалено: K — используются в условиях работающих акций». Заблокированные строки отметить нельзя. Итог — отчёт по каждому тегу; причины отказа: «Используется в условии работающей акции», «Изменён другим пользователем» (версия устарела), «Не найден — возможно, уже удалён». Уже удалённые теги остаются удалёнными.

Каждому носителю удалённого тега пишется запись истории «тег удалён из справочника».

Перенос между контурами

• «Выгрузить бандл» — JSON-файл customer-tags-<дата>.json со значениями без идентификаторов.
• «Импортировать» — загрузка бандла: добавляются только отсутствующие значения, существующие пропускаются, ничего не удаляется, связи с клиентами не переносятся. Итог — «Добавлено тегов: N, пропущено: M». Чужой или неизвестной версии файл — 422 tag_bundle_invalid; значение, нарушающее правило значения, отклоняет импорт целиком (tag_value_invalid).

Присвоение и снятие тегов

Присвоить можно только существующий тег справочника: при присвоении тег не заводится автоматически.

Из каталога клиентов

Действия «Добавить теги» и «Снять теги» доступны в контекстном меню строки и на панели массовых действий при роли LOYALTY_CUSTOMER_TAG_WRITE. Они работают с клиентом в любом статусе и в архиве. Для одного клиента в шапке модалки — «ФИО — ID», для выделения — «Выбрано клиентов: N».

• «Добавить теги» — селектор тегов; выбранные теги добавляются к уже стоящим, ничего не стирая. Повторное присвоение уже стоящего тега ошибкой не является и дубля не создаёт.
• «Снять теги» — список объединения тегов выбранных клиентов с флажками (все отмечены); по кнопке «Снять» снимается отмеченное. Снятие тега, которого у клиента нет, — не ошибка. Если тегов нет: «У клиента нет тегов» / «У выбранных клиентов нет тегов».

Итог: для одного клиента — тост «Теги присвоены» / «Теги сняты»; для выделения — окно «Присвоение тегов» / «Снятие тегов» и отчёт по каждому клиенту. Если один из выбранных тегов успели удалить из справочника, запрос отклоняется целиком, выбор сохраняется, а модалка сообщает: «Этих тегов уже нет в справочнике: … Уберите их из выбора.»

Предел одного запроса — 10 000 клиентов (loyalty.tags.max-bulk-targets) и 1000 значений тегов; больше — 400 bulk_size_exceeded, ни один клиент не изменён.

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

Из ручных операций по списку

Чтобы разметить тегом большой список клиентов (до миллиона строк из файла), используйте экран «Ручные операции»: на шаге «Операция» при роли LOYALTY_CUSTOMER_TAG_WRITE есть вкладки «Добавить теги» и «Снять теги» с селектором тегов — без причины, суммы, субсчёта и срока. Пакет выполняется тем же асинхронным конвейером, что и операции с баллами, см. Ручные операции.

• Добавление объединяет выбранные теги с уже стоящими, снятие убирает только стоящие; строка без изменений считается успешной и в историю не пишется. Автор записей истории — оператор пакета.
• Заблокированные клиенты и клиенты без бонусного счёта к операциям с тегами годятся: строку отбраковывают только ошибка формата, повтор и отсутствие клиента. Сводка проверки — «Для операций с тегами готово: N из M».
• Если тег удалили из справочника до запуска, запуск отклоняется, а чипсы удалённых тегов снимаются из поля: «Некоторые теги удалены из справочника — выберите теги заново». Тег, удалённый или слитый после приёма пакета, отказывает строкам кодом execution_unknown_tag: набор применяется к клиенту целиком или никак.

Селектор тегов

Общий контрол выбора тегов (каталог, форма создания клиента, условия акций):

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

Теги при создании клиента

В модалке «Новый клиент» секция «Теги» видна при роли LOYALTY_CUSTOMER_TAG_WRITE. Форма передаёт идентификаторы выбранных тегов. Если тег успели удалить (в том числе слиянием), пока форма была открыта, сохранение отклоняется: «Тег «vip» удалён из справочника — уберите его из выбора» — заново такой тег не заводится.

В API POST /v1/customers два необязательных поля (можно вместе, повтор даёт одно присвоение):

Поле	Кто использует	Поведение
tagIds	Форма создания	Только существующие теги. Неизвестный или удалённый id — 422 unknown_tag при любом праве
tags	Интеграции	Значения тегов. Найденные присваиваются; недостающие заводятся в справочнике, но только при роли LOYALTY_TAG_WRITE, иначе 422 unknown_tag со списком unknownTags

Непустое поле тегов требует LOYALTY_CUSTOMER_TAG_WRITE (без него — 403). Создание атомарно: при отказе не создаётся ни клиент, ни теги. Заводить недостающие значения может только создание клиента (и импорт) — присвоение уже существующему клиенту принимает лишь существующие теги. Проверить свой список заранее интеграция может массовой проверкой наличия (см. API).

Теги в импорте клиентов

Файл импорта принимает необязательную колонку tags — значения через запятую внутри ячейки (точка с запятой занята разделителем колонок). Непустая колонка требует LOYALTY_CUSTOMER_TAG_WRITE, иначе весь импорт отклоняется с 403.

• С ролью LOYALTY_TAG_WRITE недостающее значение — не ошибка. Проверка файла возвращает newTags — перечень значений, которые заведёт загрузка, с числом строк у каждого; редкие идут первыми, чтобы опечатка («рекативация» в 2 строках рядом с «реактивация» в 214) была видна до загрузки. Считаются только строки, которые будут созданы.
• Без роли LOYALTY_TAG_WRITE неизвестное значение — проблема строки unknown_tag в любом режиме проверки. Клиента без присланного тега импорт не создаёт: строка либо пропускается, либо останавливает импорт — по выбранному режиму.
• Значение, не проходящее правило значения тега, — проблема строки tag_value_invalid при любом праве.

Подробнее о мастере и параметрах — Импорт клиентов.

Фильтр «Теги» в каталоге

Колонка «Теги» каталога имеет фильтр по справочнику с серверным поиском: клиент попадает в выдачу, если у него есть хотя бы один из выбранных тегов. В API связка задаётся параметром tagMatch: ANY (по умолчанию) или ALL — «есть все перечисленные». Значения в выдаче отсортированы; у клиента без тегов список пуст. Фильтр и колонка работают при любом режиме MDM: теги хранятся в базе лояльности.

Фильтр доступен при роли LOYALTY_TAG_READ или LOYALTY_CUSTOMER_TAG_WRITE.

История тегов клиента

Каждое фактическое изменение набора тегов клиента записывается в его историю: действие, значение тега на момент события (даже если тег потом переименовали или удалили), автор из токена и время. Записи делаются при:

• присвоении — в том числе при создании клиента, импорте и пакете ручных операций;
• снятии;
• замене тега при слиянии — со значениями источника и цели;
• снятии из-за удаления тега из справочника.

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

Экрана истории тегов пока нет

История ведётся на сервере; отдельный экран и эндпоинт её просмотра появятся отдельной задачей.

Права

Роль	Что открывает
LOYALTY_TAG_READ	Просмотр справочника тегов: список, поиск, число носителей, связанные акции; строка «Теги клиентов» в реестре справочников
LOYALTY_TAG_WRITE	Изменение справочника: создание, переименование, слияние, удаление, выгрузка и загрузка бандла; заведение недостающих значений при создании клиента по API и импорте
LOYALTY_CUSTOMER_TAG_WRITE	Присвоение и снятие тегов клиентам — из каталога и пакетом в «Ручных операциях»; поле «Теги» при создании клиента и колонка tags в импорте; чтение списка тегов для селектора и фильтра

Общие права LOYALTY_DICTIONARY_READ / LOYALTY_DICTIONARY_WRITE справочник тегов не открывают, а универсальные операции над записями справочников на нём отвечают 409 dictionary_own_screen: данные тегов ходят только через собственный API. Присвоение тегов отделено и от прав справочника, и от LOYALTY_CUSTOMER_WRITE.

REST API тегов

Метод и путь	Роль	Назначение
GET /v1/tags	LOYALTY_TAG_READ или LOYALTY_CUSTOMER_TAG_WRITE	Справочник: search, hasCustomers, страницы; по умолчанию по алфавиту
POST /v1/tags	LOYALTY_TAG_WRITE	Завести тег (значение нормализуется)
PATCH /v1/tags/{tagId}	LOYALTY_TAG_WRITE	Переименовать; версия записи — в заголовке If-Match
POST /v1/tags/{tagId}/merge	LOYALTY_TAG_WRITE	Слить источник в этот тег (цель — в пути)
POST /v1/tags/bulk-delete	LOYALTY_TAG_WRITE	Удалить теги со снятием у носителей
POST /v1/tags/lookup	LOYALTY_TAG_READ или LOYALTY_CUSTOMER_TAG_WRITE	Массовая проверка наличия по значениям (до 1000): найденные с id, ненайденные — как пришли; ничего не заводит
GET /v1/tags/customer-counts?ids=	LOYALTY_TAG_READ	Число носителей по списку id (до 200); теги без носителей — с нулём
GET /v1/tags/{tagId}/condition-promotions	LOYALTY_TAG_READ	Акции, отбирающие по тегу; блокирующие — первыми
GET /v1/tags/condition-promotions?ids=	LOYALTY_TAG_READ	Свод по выделению: число связанных и блокирующих акций
GET /v1/tags/export, POST /v1/tags/import	LOYALTY_TAG_WRITE	Выгрузка и загрузка бандла
POST /v1/customers/bulk-tag-assign, bulk-tag-remove	LOYALTY_CUSTOMER_TAG_WRITE	Присвоить / снять теги ({externalIds[], tags[]})

Текущие теги клиента отдаёт и карточка клиента — поле tags в GET /v1/customers/{externalId}/card (значения в том же порядке, что в каталоге; нет тегов — пустой список); в интерфейсе карточки они пока не выводятся.

Запись справочника — {id, value, hasCustomers, version}. Переименование и слияние требуют актуальной версии: без заголовка If-Match — 428 version_required, при расхождении — 409 version_conflict. Пакетные ответы имеют вид {status: completed|aborted, succeeded[], errors[]}: aborted означает, что сервер не дошёл до конца пакета — уже выполненное не откатывается.

Код	HTTP	Когда
tag_not_found	404	Тега нет (в том числе уже удалён)
tag_already_exists	409	Значение занято (без учёта регистра)
tag_value_invalid	422	Значение нарушает правило значения тега
tag_merge_into_itself	422	Слияние тега с самим собой
tag_in_use	409	Тег стоит в условии работающей акции — удаление запрещено
tag_bundle_invalid	422	Файл не бандл тегов или неизвестная версия
unknown_tag	422	В запросе есть значение или id, которых нет в справочнике
bulk_size_exceeded	400	Превышен предел пакета или списка
version_conflict / version_required	409 / 428	Версия записи не совпала / не передана
dictionary_own_screen	409	Обращение к тегам через универсальный API справочников

Миграция прежних тегов

Теги, заведённые до появления справочника, переведены на него автоматически: значения приведены к нижнему регистру, ;, , и управляющие символы заменены пробелом, длина обрезана до 60 символов, пустые после нормализации связи удалены. Значения, совпавшие после нормализации (например «VIP» и «vip» у одного клиента), сведены к одному тегу.