Сутність «Серія Купонів» в системі inCust

Синоніми: Coupon Batch, серія купонів, батч купонів.

Що це таке

Серія Купонів — самостійна сутність Бренду, що описує шаблон-генератор однотипних Купонів і задає спільні для всіх своїх Купонів правила випуску, видачі та погашення. Окремі Купони не створюються поштучно «з нуля» — вони емітуються із Серії, успадковуючи її тип, термін дії, обмеження та вигоду. Серія є точкою конфігурації, Купон — її екземпляром у гаманці конкретного Покупця або на руках пред'явника.

Серія Купонів цілком належить одному Бренду; через володіння Брендом контроль над нею транзитивно отримує Бізнес. У специфікації Business API кожна Серія несе business_id і прив'язку до Бренду через емісію (loyalty_id).

Місце в доменній моделі

Серія Купонів — операційно-маркетинговий актив Бренду, паралельний правилам програми лояльності, а не їх частина:

Бізнес  →  Бренд  →  Серія Купонів  →  Купон  →  гаманець Роздрібного Покупця

Купони можуть видаватися та погашатися в межах правил програми лояльності (купонне правило видає вигоду за пред'явленим Купоном), але це лише один зі сценаріїв: випуск і застосування Купонів можливі й поза програмою лояльності (пряма роздача коду, продаж сертифіката, квиток, видача промокоду). Це узгоджено з означенням у Сутності «Бренд» (KNOW-003), де Купони і серії купонів названо самостійною сутністю Бренду.

Типи серій

Тип Серії (type) визначає природу вигоди, яку несе випущений Купон:

• Купон вигоди — надає знижку, бонус, подарунок чи інше право згідно з прив'язаним купонним правилом лояльності.
• Сертифікат / подарункова картка — Купон зі збереженою вартістю: Серія задає тип і суму поповнення рахунку (charge_type, charge_amount), а сам Купон функціонує як передоплачений інструмент.
• Обмінний купон (Біржа купонів) — Серія, похідна від базової (base_batch_id / base_batch_code), з власною комісією за погашення (exchange_coupon_redeem_fee) для крос-маркетингу між Брендами.
• Купон із промокодом / зовнішнім кодом — Серія, основна цінність якої — сам код, заданий із зовнішнього джерела (промокод партнера, ключ активації, код стороннього сервісу). При погашенні Купон повертає Покупцю прив'язаний промокод/зовнішній код. Детально — у розділі «Серії з промокодами та зовнішніми кодами».

Серії з промокодами та зовнішніми кодами

Для цього типу Серії носієм вигоди є не внутрішнє нарахування inCust, а зовнішній код (промокод), який Серія зберігає й видає Покупцю. inCust у цьому сценарії виступає сховищем, засобом роздачі та обліку погашень кодів, згенерованих або наданих ззовні.

Джерело кодів. Серія тримає пул зовнішніх кодів:

• завантажених із зовнішнього джерела — POST /coupons/batch/{batch_id}/external_codes/add (масив рядків-кодів); перегляд — GET …/external_codes; вилучення — POST …/external_codes/delete;
• або згенерованих системою, якщо ввімкнено auto_generated_external_codes. Пул відображається у external_codes_list (елементи типу CouponBatchExtCode); поле external_code зберігає код самої Серії (до 256 символів).

Прив'язка коду до Купона. Спосіб роздачі визначають два прапорці:

• use_one_external_code (0/1) — уся Серія використовує один спільний зовнішній код для всіх своїх Купонів (типово для єдиного публічного промокоду);
• інакше кожному емітованому Купону призначається власний код із пулу (по одному коду на Купон), що дозволяє відстежувати погашення поіменно й не допускати повторного використання. Окремо use_unique_coupon_code (0/1) керує тим, чи має сам Купон власний унікальний внутрішній code (на додачу до зовнішнього).

Момент розкриття коду задає external_code_visibility_type:

• always-open — код видно одразу після отримання Купона (відкритий промокод);
• on-redeem — код прихований до погашення і відкривається Покупцю лише в момент застосування Купона (захищена видача — наприклад, одноразові ключі).

Процес застосування (погашення). При погашенні такого Купона система не нараховує вигоду всередині inCust, а повертає прив'язаний промокод/зовнішній код — для введення на сайті партнера, активації послуги чи отримання знижки в сторонній системі. Якщо діє on-redeem, саме погашення є моментом, коли код стає видимим. Факт погашення фіксується транзакцією Бренду, а код позначається як виданий, що унеможливлює його повторну видачу (для серій з унікальними кодами з пулу).

Атрибути та конфігурація

Серія задає параметри, спільні для всіх випущених із неї Купонів:

• Ідентифікація: код серії (code), публічні назва й опис (public_title, public_description), зображення (image), прапорець активності (active).
• Зовнішні коди / промокоди: код Серії (external_code), пул кодів (external_codes_list), авто-генерація (auto_generated_external_codes), один спільний код на серію (use_one_external_code), унікальний внутрішній код Купона (use_unique_coupon_code), видимість коду (external_code_visibility_type: always-open / on-redeem).
• Емісія: період випуску (emission_period_begin / emission_period_end), сумарний ліміт випущених Купонів (emission_quantity_limit, 0 — без ліміту), ліміт на одного Покупця (emission_per_customer_limit), лічильник уже випущених (emitted_coupons_quantity, readonly).
• Термін дії Купона: тип і значення (coupon_expire_type, coupon_expire_value, coupon_expire_date) — відносний строк від моменту випуску або фіксована дата.
• Ціна емісії: для платних Купонів і сертифікатів — тип, сума, валюта чи спецрахунок оплати (customers_price_type, customers_price_amount, customers_price_currency, customers_price_special_account_id).
• Погашення та поширення: погашення лише на Терміналі (redeem_at_terminal), дозвіл Покупцю ділитися Купоном (share_allowed), автоматичне погашення при додаванні в гаманець (auto_redeem_on_add_to_wallet), доступ анонімного користувача до приватних даних власних Купонів (anonymous_owned_data_access_allowed).
• Канали роздачі: посилання (links) та аліаси (CouponBatchAlias) — іменовані під-коди з власними лімітами, строком дії та, за потреби, прив'язкою до конкретного Покупця.

Життєвий цикл

1. Створення Серії з конфігурацією (тип, ліміти, період, термін дії, ціна; для промокодних серій — параметри зовнішніх кодів).
2. Наповнення кодами (для типу з промокодами) — завантаження пулу зовнішніх кодів або ввімкнення авто-генерації.
3. Емісія окремих Купонів із Серії в межах її лімітів і періоду; за потреби — призначення Купону коду з пулу.
4. Видача / роздача — розсилання Покупцям, поширення через посилання, аліаси та зовнішні коди, додавання Купона в гаманець Покупця.
5. Погашення — у складі купонного правила лояльності або напряму на Терміналі / в додатку Покупця; для промокодних серій погашення повертає (а за on-redeem — розкриває) зовнішній код.
6. Скасування — анулювання окремого Купона.

Представлення в API

Управління Серіями зосереджене в Business API (KNOW-006); випуск і погашення доступні також через Terminal і Client API.

Business API — конфігурація і керування серіями:

• GET|POST /coupons/batches, GET|PATCH /coupons/batch/{batch_id} — список, створення, читання та зміна Серії (Бренд задається через тіло запиту).
• …/batch/{batch_id}/emission — емісія Купонів із Серії.
• GET /coupons/batch/{batch_id}/external_codes, POST …/external_codes/add, POST …/external_codes/delete — пул зовнішніх кодів/промокодів: перегляд, завантаження ззовні, вилучення.
• /coupons/coupon/send, …/aliases, …/links — розсилання, аліаси, посилання для роздачі.
• GET /coupons/coupon/{code}, …/cancel — окремий Купон і його скасування.

Terminal API (KNOW-009) — операції на Терміналі/Кіоску:

• GET /coupons/batch/{code}/emission — випуск Купона із Серії на місці.
• POST /coupons/coupon/get, POST /coupons/redeem, GET /coupons/user, POST /coupons/user/add, POST /coupons/user/redeem, GET /customers/benefits/coupons — пошук, додавання та погашення Купонів Покупця (погашення промокодного Купона повертає зовнішній код).

Client API (KNOW-008) — гаманець Роздрібного Покупця:

• GET|POST /coupons — список і додавання Купона за кодом Купона, кодом Серії або кодом подарункової картки.
• GET /coupon/{coupon_id}, …/redeem, …/share, DELETE /coupon/{coupon_id}, GET /coupons/coupon/{code} — перегляд, погашення (за on-redeem — розкриття коду), поширення, видалення.

Наслідки для запитів і доступу

• Серії та їхні Купони належать Бренду; запити Business API фільтруються за Брендом (loyalty_id) явно або через межі прав Робітника. Керування Серіями входить у роль Менеджер Бренду; ролі рівня Покупців/Транзакцій бачать Купони лише в контексті відповідних операцій.
• Транзакції погашення Купонів проходять як термінальні/лояльнісні операції Бренду й у звітності «за Бізнесом» враховуються транзитивно (див. Сутність «Бізнес», KNOW-002).
• Для промокодних серій з унікальними кодами з пулу облік погашень забезпечує одноразовість видачі кожного коду.

Зовнішні точки входу

• Бізнес-Панель (https://business.incust.com/) — розділ керування Серіями купонів, сертифікатами, промокодами/зовнішніми кодами та Біржею купонів.

Джерела

Канонічне технічне джерело — специфікація Business API (KNOW-006); поведінка на місці продажу та в гаманці — Terminal API (KNOW-009) і Client API (KNOW-008). Дотичне доменне означення — Сутність «Бренд» (KNOW-003) і Словник (KNOW-004).