работа с промокодами

Работа с промокодами

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

Генерация промокода (в кабинете клиента)

Перейти: https://cabinet.clientomer.ru/[поинт]/promocodes/
Нажать «Добавить» и заполнить конфигурацию промокода.
Нажать «Сохранить».
После сохранения нажать кнопку «Генерировать промокоды».
Через ~1 минуту промокоды будут готовы.
Статистику применения смотреть по клику на название промокода.

Настройки промокода

При создании/настройке промокода доступны поля:

Поле	Описание
Текст промокода	Сам код или серия.
Уникальные значения	Каждый экземпляр промокода уникален.
Описание	Произвольное описание.
Период действия	Дата начала и дата окончания.
Срок действия	Количество дней действия.
Общее количество использований	Лимит на весь промокод (пусто = без ограничения).
Количество использований на человека	Доступно, если промокод не анонимный.
Только на первый заказ	Доступно, если промокод не анонимный.
Реферальный	Доступно, если промокод не анонимный.
Анонимный	Можно использовать без чекина гостя.
Активный	Включает/выключает промокод.
Количество уникальных символов	Доступно при выключенных «уникальных значениях».
Случайный номер промокода	Генерация случайных кодов.

Если ограничение по полю не нужно — поле оставляют пустым. Рядом с «общим количеством использований» и «количеством использований на человека» есть подсказка об этом.

При вводе количества уникальных символов система показывает, сколько промокодов будет доступно (со случайными значениями: 1 символ — 5 значений, 2 символа — 50 и т. д.; без случайных — 1 символ — 10 значений).

Логика работы (блоки условий и действий)

Блок настройки логики напоминает редактор акции в системе лояльности, но без выбора триггера. В редактор добавляются специальные блоки:

Сочетание с акциями (действие) — список чекбоксов всех акций поинта в формате «Название ПЛ → Название акции» и выбор типа применения (чёрный/белый список).
Владелец промокода (условие) — какие действия применить к гостю-владельцу промокода.
Не владелец промокода (условие) — какие действия применить к гостю, использовавшему чужой промокод.

Структура данных (для разработки и диагностики)

Промокоды хранятся в трёх основных таблицах:

Таблица	Назначение
`promocode_configs`	Настройки всех промокодов (период, лимиты, флаги анонимности/реферальности/активности).
`promocode_items`	Отдельные экземпляры промокодов (текст, статус `active`/`used`/`overdue`, гость, сроки).
`promocode_using_log`	Лог использований (гость, дата/время, статус `success`/`error`).

Применение через API (LoyaltyV1API)

В методах MakeDiscount / MakePreTransaction промокоды передаются массивом строк promocodes на верхнем уровне запроса. В ответе возвращается массив promocodes и объект promocode_status.

Успешное применение:

"promocode_status": { "status": "ok" }

Ошибка:

"promocode_status": {
  "status": "error",
  "error": "not found",
  "promo": "NY24",
  "message": "Промокод не найден"
}

Типы ошибок промокодов

Код ошибки	Сообщение пользователю
`not found`	Промокод не найден
`limit exhausted`	Лимит исчерпан
`expired`	Промокод истёк
`app mes`	Сообщение от обработчика (например, «Невозможно совместить с промокодом …»)

Отчёт об использовании

Страница отчёта состоит из двух блоков: настройки промокода (только для чтения) и таблица использований. В таблице два типа строк: описание экземпляров промокодов (из promocode_items) и записи об их использовании (из promocode_using_log). Для реферальных промокодов использования раскрываются по клику на строку.