Редактирование: работа-с-промокодами

Путь: 05_Лояльность_и_бизнес-процессы/работа-с-промокодами.md

Содержимое (Markdown)

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

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

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

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

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

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

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

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

При вводе количества уникальных символов система показывает, сколько промокодов будет доступно (со случайными значениями: 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`.

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

```json
"promocode_status": { "status": "ok" }
```

Ошибка:

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

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

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

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

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

Отмена