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

Синоніми: Coupon, купон.

Що це таке

Купон — окремий екземпляр, емітований із Серії Купонів (KNOW-015), що несе конкретну вигоду (знижку, бонус, подарунок), збережену вартість (сертифікат / подарункова картка) або зовнішній код (промокод) і має власний код, статус та життєвий цикл. Купон не існує сам по собі: він завжди належить рівно одній Серії, від якої успадковує тип, термін дії та правила погашення, і завжди прив'язаний до Бренду (loyalty_id) та Бізнесу (business_id), що володіє Серією.

Купон зазвичай знаходиться у гаманці конкретного Роздрібного Покупця (customer), але може бути й «на пред'явника» — на руках без прив'язки до облікового запису, доки його не додадуть у гаманець або не погасять.

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

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

Купон — листовий вузол цієї гілки: Серія є шаблоном-генератором і точкою конфігурації, Купон — її матеріалізованим екземпляром. Володіння транзитивне: Купон належить Бренду, а через нього — Бізнесу. Погашення Купона може відбуватися в межах купонного правила програми лояльності або поза ним (пряме застосування на Терміналі, видача промокоду, активація сертифіката).

Статуси та життєвий цикл

Статус Купона (status) набуває трьох значень:

• open — випущений і чинний, доступний до погашення;
• redeemed — погашений; зафіксовано транзакцію погашення (redeem_transaction, redeem_dt);
• cancelled — анульований (cancel_dt).

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

1. Емісія — Купон створюється із Серії; фіксуються emission_dt та транзакція емісії (emission_transaction).
2. Отримання Покупцем — Купон додається у гаманець (taken_by_customer_dt), прив'язується до customer.
3. Поширення (за share_allowed у Серії) — Покупець ділиться Купоном; видається код поширення (share).
4. Погашення — застосування Купона; статус → redeemed, для промокодних серій повертається/розкривається зовнішній код.
5. Завершальні стани — анулювання (cancelled) або видалення Покупцем зі свого гаманця (deleted_by_customer, deleted_by_customer_dt); закінчення строку дії (expire_date).

Прапорець locked позначає Купон, тимчасово заблокований процесом транзакції.

Атрибути

• Ідентифікація: id, код (code), назва й опис (title, description — успадковані від Серії).
• Належність: batch / batch_id (Серія), business_id, loyalty_id, customer (CouponCustomer — власник), emitter_batch (батч-емітент для обмінних/похідних серій).
• Стан і час: status, emission_dt, taken_by_customer_dt, redeem_dt, cancel_dt, expire_date, deleted_by_customer, deleted_by_customer_dt, locked.
• Транзакції: emission_transaction / emission_transaction_id, redeem_transaction / redeem_transaction_id.
• Спеціалізації: gift_card (дані подарункової картки / збереженої вартості), share (дані поширення).

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

Купон фігурує у трьох API: адміністрування — у Business API (KNOW-006), операції на місці продажу — у Terminal API (KNOW-009), гаманець покупця — у Client API (KNOW-008). Випуск і конфігурація серій — у самій Серії Купонів (KNOW-015).

Business API — облік і адміністрування окремих Купонів:

• POST /coupons — список Купонів Бізнесу з фільтрами (за Серією, статусом, Покупцем тощо).
• GET /coupons/coupon/{code} — інформація про Купон за кодом; GET /coupons/coupon/{code}/html — те саме у форматі HTML для друку/відображення.
• GET /coupons/coupon/{coupon_id}/cancel — анулювання Купона.
• POST /coupons/customers_bulk_ids — масове отримання ідентифікаторів Покупців-власників Купонів.
• GET /coupons/exchange — перелік серій, доступних на Біржі купонів.
• POST /gift_cards/coupons — перелік Купонів, що є подарунковими картками.

Terminal API — пошук, видача та погашення на Терміналі/Кіоску:

• POST /coupons/coupon/get — знайти Купон за id, кодом або зовнішнім кодом.
• POST /coupons/redeem — погасити Купон (за кодом/ідентифікатором).
• GET /coupons/user — список Купонів конкретного Покупця; GET /customers/benefits/coupons — Купони у складі доступних Покупцю вигод.
• POST /coupons/user/add — додати Купон Покупцю; POST /coupons/user/redeem — погасити Купон Покупця.
• (/coupons/{user_id_value}… — застарілі (DEPRECATED) варіанти тих самих операцій.)

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

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

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

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

Джерела

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