Партнёрские предложения

Партнёрские предложения — совместные акции лояльности на продуктах внешних партнёров (связка Loyalty × CM Ocean Promo). Программа лояльности одного участника показывает клиенту выгоду на продукте другого: например, банк выводит в своём кабинете скидку партнёрского кафе и начисляет кэшбэк за покупки у этого партнёра. Раздел позволяет оператору вести реестр партнёров, заводить офферы, управлять их жизненным циклом и наблюдать статус в единой таблице.

От обычных акций (раздел «Акции») партнёрские предложения отличаются двумя вещами: они привязаны к внешнему партнёру из реестра и описываются набором из четырёх независимых осей, которые задают способ доставки выгоды, порядок активации, охват аудитории и того, кто платит.

Четыре оси оффера

Оффер (partner_offer) описывается четырьмя ортогональными осями. Оси независимы — любое сочетание значений допустимо, и вместе они однозначно определяют поведение оффера.

Ось	Значение	Что означает
Доставка (delivery)	PROMOCODE	Выгода отдаётся промокодом; редемпшн (погашение) ведёт CM Ocean Promo.
	CALCULATED	Кэшбэк рассчитывает сама программа Loyalty по транзакциям у партнёра.
Акцепт (acceptance)	OPT_IN	Клиент активирует предложение сам.
	AUTO	Доступно сразу, без активации.
Аудитория (audience)	ALL	Доступно всем клиентам.
	SEGMENT	Доступно только заданным сегментам.
Финансирование (funding)	PARTNER	Вознаграждение оплачивает партнёр.
	PROGRAM	Вознаграждение оплачивает программа.
	SHARED	Совместное финансирование партнёра и программы.

Почему оси ортогональны

Оси не зависят друг от друга: PROMOCODE-оффер может быть как AUTO, так и OPT_IN; CALCULATED-оффер может финансироваться партнёром, программой или совместно. Это позволяет собирать нужную комбинацию из простых понятных значений, а не выбирать из длинного списка фиксированных шаблонов.

Вознаграждение

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

Поле	Значение	Описание
valueKind	PERCENT	Процент от суммы чека.
	POINTS	Начисление в баллах.
	FIXED	Фиксированная величина.
value	—	Числовое значение вознаграждения в выбранных единицах.
maxReward (maxRewardMinor)	—	Потолок вознаграждения на одну атрибуцию (cap).

Как считается вознаграждение

• PERCENT — доля от суммы транзакции.
• POINTS и FIXED — номинал задаётся в баллах и переводится в минорные единицы по точности валюты баллов из справочника валют: при баллах с сотыми номинал «5» — это 500 минорных единиц, при целых баллах — 5. Та же величина попадает в отчёт о взаиморасчётах, а при финансировании партнёром (PARTNER, SHARED) — и в списание с его счёта.
• Результат округляется математически (половина — вверх), так же как начисление по механикам акций: одна и та же сумма даёт один и тот же балл, каким бы путём она ни начислялась.
• Потолок maxReward применяется после округления.

Условные поля доставки

Набор дополнительных полей зависит от оси Доставка:

• PROMOCODE — задаются promocode (сам код) и promoCampaignId (кампания на стороне CM Ocean Promo, которая ведёт погашение).
• CALCULATED — задаётся mechanicCode: код механики, соответствующей диаграмме RT Flow, по которой программа рассчитывает кэшбэк.

Ограничения оффера

Поле	Описание
minAmount	Минимальная сумма чека, при которой оффер применяется.
budget	Общий бюджет вознаграждений по офферу.
perCustomerLimit	Лимит вознаграждений на одного клиента.
newCustomerOnly	Признак «только новым» — оффер доступен клиентам без прежних атрибуций у этого партнёра.

Реестр партнёров

Партнёры ведутся в отдельном реестре (CRUD). Оффер всегда привязан к записи партнёра.

Поле	Описание
code	Код партнёра (натуральный ключ, используется при резолве транзакций).
name	Наименование партнёра.
category	Категория партнёра.
logoUrl	Логотип партнёра.
status	Состояние партнёра: ACTIVE — «Активен», BLOCKED — «Заблокирован».

Мерчанты партнёра

Идентификаторы мерчанта (MID) и код категории мерчанта (MCC) хранятся не в записи партнёра, а в справочнике мерчантов: у каждого мерчанта свой MID (уникален; хранится как передан и после создания не меняется), название, описание, партнёр, MCC, город и состояние — ACTIVE или CLOSED. Мерчант закрывается, а не удаляется: на него ссылаются уже проведённые транзакции и условия отработавших акций. Справочник ведётся через API /v1/admin/merchants (права LOYALTY_MERCHANT_READ / LOYALTY_MERCHANT_WRITE); отдельного экрана в интерфейсе у него нет. Тот же справочник даёт значения условию акции «Мерчант» — см. «Условия акции».

Как транзакция находит партнёра

При начислении кэшбэка по транзакциям (card-linked) партнёр определяется по цепочке:

1. по коду партнёра, если он передан в транзакции;
2. по MID — прямым поиском мерчанта в справочнике, точным совпадением с учётом регистра (обрамляющие пробелы отбрасываются); закрытый мерчант по-прежнему указывает на своего партнёра;
3. по MCC — только среди действующих мерчантов и только если MCC однозначно указывает на одного партнёра.

Транзакция, для которой партнёр по MID не найден (мерчанта нет или он не отнесён к партнёру), учитывается отдельным техническим показателем — так «почему партнёр не начислил» можно найти.

Поля «MID» и «MCC» в реестре партнёров

Боковая панель «Реестр партнёров» всё ещё показывает поля и колонки «MID» и «MCC», но сервер эти значения у партнёра больше не принимает и не возвращает: введённое в них не сохраняется, а в таблице выводится «—». Мерчанты заводятся в справочнике мерчантов.

Экран администратора

Экран открывается из меню «Администрирование → Партнёрские предложения». Он состоит из таблицы кампаний, фильтра по статусу, формы создания/редактирования оффера и отдельного реестра партнёров.

Таблица кампаний

Каждая строка — партнёрский оффер. Состав колонок:

Колонка	Назначение
Партнёр	Партнёр из реестра, к которому привязан оффер.
Название	Наименование оффера.
Механика	Способ доставки: Промокод или Расчёт по транзакциям.
Акцепт	Акцептное (OPT_IN) или Безакцептное (AUTO).
Аудитория	Охват: все клиенты или заданные сегменты.
Вознаграждение	Вид и величина выгоды (процент / баллы / фикс).
Период	Интервал действия оффера — даты и точное время начала и окончания.
Статус	Текущее состояние оффера в жизненном цикле.

Код оффера

При создании оффер получает человекочитаемый код вида PO-0000001 — по нему оффер виден в отчёте о взаиморасчётах и в ответах интеграционного приёма транзакций. Код присваивается автоматически и не редактируется.

Фильтр по статусу

Над таблицей расположен сегмент-переключатель фильтрации: Все / Черновики / Активно / Пауза / Архив. Он ограничивает список офферами выбранного статуса.

Форма создания оффера

Создание и редактирование оффера выполняется в боковой панели (Drawer). Четыре оси задаются радио-переключателями, а набор дополнительных полей появляется условно в зависимости от выбранной доставки:

• при доставке Промокод — поля промокода и кампании CM Ocean Promo;
• при доставке Расчёт по транзакциям — выбор механики RT Flow.

Реестр партнёров — отдельный Drawer

Управление партнёрами вынесено в самостоятельную боковую панель «Реестр партнёров» (CRUD), которая открывается кнопкой «Партнёры (N)» над таблицей. В ней заводятся и правятся записи партнёров; мерчанты партнёра (MID, MCC) ведутся в справочнике мерчантов — см. «Мерчанты партнёра».

Сегменты аудитории

При аудитории «Сегмент» сегменты выбираются из справочника сегментов клиентов, состав которых загружается из внешней системы. Если выбранный сегмент удалили, пока форма была открыта, сохранение отклоняется (422 partner_offer_segment_not_found) с сообщением «Ошибка сохранения».

Период действия — с точным временем

Даты начала и конца периода можно задать с точным временем; если время не тронуто — по умолчанию 00:00 у начала и 23:59 у конца (весь выбранный день включительно). Обе границы периода — включительные: оффер, действующий в момент, равный времени окончания, ещё участвует в отборе. Дата и время вводятся и показываются в часовом поясе программы — под полем подсказка со смещением пояса, например «Часовой пояс: UTC+3»; при создании оффера прошедшие дни недоступны.

Жизненный цикл оффера

Оффер проходит управляемый жизненный цикл статусов, аналогичный жизненному циклу акций.

Статус	Значение
DRAFT	Черновик. Оффер заведён, но ещё не запущен.
ACTIVE	Активен. Оффер участвует в отборе и начислениях в пределах своего периода.
PAUSED	Приостановлен. Действие временно остановлено без архивирования.
ARCHIVED	В архиве. Оффер выведен из эксплуатации.

stateDiagram-v2
    [*] --> DRAFT: создать
    DRAFT --> ACTIVE: запустить
    ACTIVE --> PAUSED: приостановить
    PAUSED --> ACTIVE: возобновить
    ACTIVE --> ARCHIVED: архивировать
    PAUSED --> ARCHIVED: архивировать
    ARCHIVED --> [*]

Истечение периода

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

Автоматическая пауза при исчерпании бюджета

При начислении кэшбэка по транзакциям, если бюджет оффера исчерпан, оффер пропускается и автоматически переводится в статус PAUSED.

Удаление оффера и партнёра

Денежная история партнёра не удаляется — она архивируется. Поэтому удалить можно только то, по чему ещё не было движения денег:

Что удаляют	Когда удаление отклоняется	Код
Оффер	Оффер в статусе ACTIVE — сначала приостановите или архивируйте его.	409 partner_offer_active
Оффер	По офферу уже есть атрибуции (вознаграждённые транзакции) — такой оффер только архивируется.	409 partner_offer_in_use
Партнёр	У партнёра есть офферы, есть проводки по счёту финансирования или есть мерчанты в справочнике.	409 partner_in_use

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

Взаиморасчёты с партнёром

Отчёт о взаиморасчётах — GET /v1/partners/{id}/settlement?days=30 (роль LOYALTY_PROMOTION_READ, в интерфейсе экрана нет) — показывает вознаграждения по офферам партнёра за окно из последних days дней и итоги финансирования. Все величины отчёта, кроме одной, относятся к одному окну, границы которого возвращаются в ответе (from, to):

• fundedInPeriodMinor — сколько профинансировал партнёр за окно отчёта: сопоставимо со строками отчёта и пригодно для выставления счёта за период;
• fundedTotalMinor — сколько профинансировал партнёр за всё время: остаток по счёту, а не итог периода.

Подробнее о составе отчёта — в руководстве администратора, «Отчёт взаиморасчётов».

Видимость промокода

Для PROMOCODE-офферов действует правило видимости кода клиенту:

• промокод виден сразу — только для офферов с акцептом AUTO;
• для офферов с акцептом OPT_IN промокод становится виден только после акцепта (активации клиентом).

Код скрыт до активации

Клиент не видит промокод OPT_IN-оффера, пока не активирует предложение. До акцепта в карточке оффера показывается кнопка активации, а не сам код.

Как клиент видит офферы

Партнёрские офферы показываются конечному клиенту в личном кабинете (B2C) — на вкладке «Партнёры». В карточке оффера клиент видит партнёра, категорию и величину выгоды; для AUTO-офферов (или после акцепта OPT_IN) отображается копируемый промокод, для OPT_IN — кнопка активации, а для CALCULATED-офферов — подпись о том, что кэшбэк начислится автоматически.

Подробнее о клиентском контуре, вкладках и активации офферов — на странице Личный кабинет клиента (B2C).

Роли и доступ

Управление реестром партнёров и офферами требует прав на акции.

Действие	Роль
Просмотр партнёров и офферов	LOYALTY_PROMOTION_READ
Создание, изменение, переходы статуса	LOYALTY_PROMOTION_WRITE

Административные эндпоинты:

Эндпоинт	Назначение	Роли
/v1/partners	CRUD реестра партнёров.	LOYALTY_PROMOTION_READ / LOYALTY_PROMOTION_WRITE
/v1/partner-offers	CRUD офферов и переходы статуса.	LOYALTY_PROMOTION_READ / LOYALTY_PROMOTION_WRITE
/v1/partners/{id}/settlement	Отчёт о взаиморасчётах с партнёром за период.	LOYALTY_PROMOTION_READ
/v1/admin/merchants	Справочник мерчантов: список, карточка, создание, правка, закрытие и возврат в работу.	LOYALTY_MERCHANT_READ / LOYALTY_MERCHANT_WRITE

Доступ

Запросы выполняются от имени авторизованного пользователя. Без роли на чтение раздел закрыт; без роли на запись доступен только просмотр.