Доменна сутність шару програми лояльності; учасник лояльності Бренду, проекція Користувача на конкретний Бренд. «Клієнт» вживається як неканонічний синонім.

Сутність «Роздрібний Покупець» в системі inCust

Синоніми: Клієнт (неканонічна назва; канон — «Роздрібний Покупець»).

Що це таке

Роздрібний Покупець — доменна сутність шару програми лояльності inCust, що представляє приватну особу — учасника лояльності конкретного Бренду. Роздрібний Покупець є об'єктом обліку, з яким система пов'язує покупки, кредити, бонусні та клієнтські рахунки, а також купони, додані до гаманця.

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

Місце в архітектурі

Шар ідентичності (Користувач) → шар лояльності (Роздрібний Покупець) → шар володіння (Бренд) → шар замовника (Бізнес).

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

Модель володіння та зв'язки

Власник: Бренд. Усі Роздрібні Покупці належать рівно одному Бренду; перенесення між Брендами не передбачено.
Унікальність: один Користувач — рівно один Роздрібний Покупець у межах одного Бренду. Дублювання записів на один і той самий Користувач у одному Бренді (наприклад, по одному на Точку продажу або по одному на канал контакту) не допускається.
Ізоляція між Брендами: якщо Бізнес має кілька Брендів, Роздрібні Покупці кожного з них є окремими записами і не діляться даними. Спільного «Покупця Бізнесу» не існує.
Зв'язок з Користувачем: обов'язковий від моменту створення. Користувач — це шар ідентичності (зареєстрований акаунт inCust); Роздрібний Покупець — це участь цієї ідентичності в лояльності конкретного Бренду.

Атрибути

Канонічно сутність Роздрібний Покупець має такі атрибути:

тип доступу Покупця до програми лояльності (access_type) — визначає, які операції з бонусами та рахунками для нього доступні. Канонічні значення:
- full-bonuses-access — повний доступ до бонусів (нарахування і списання);
- add-bonuses-only — дозволено лише нарахування бонусів та коштів на рахунки Покупця; списання заблоковано;
- waiting-for-confirmation — Покупець очікує підтвердження менеджером Бренду; нарахування та списання заблоковані;
- in-black-list — Покупець у чорному списку.
категорія Покупця у програмі лояльності Бренду (card_category) — є окремим керованим об'єктом з полями id, title і type. Поле type має два канонічних значення:
- base — системна (базова) категорія, наприклад NEW CUSTOMERS;
- custom — категорія, створена Брендом самостійно (наприклад, GOLD, PLATINUM).
Категорія Покупця змінюється на Терміналі окремою операцією; присвоєння нової категорії потребує її попереднього існування у переліку категорій Бренду.
анкета покупця — список довільних параметрів, склад яких задається Брендом. Кожне поле анкети має ідентифікатор, назву, порядок відображення, тип значення (рядок, словник із фіксованим набором значень, ціле число, дата) і саме значення. Брендом може бути заведена довільна кількість таких полів.
номер картки лояльності — власний ідентифікатор Покупця у межах Бренду, який можна використовувати на Терміналі поряд з ідентифікаторами пов'язаного Користувача.
картка для Apple Wallet — цифрове представлення картки лояльності Покупця у форматі Apple Wallet.

Решта особистих даних (телефон, email, ім'я, дата народження, стать тощо) належить шару ідентичності — Користувачу — і не дублюється на рівні Роздрібного Покупця.

Канонічне джерело визначень access_type, card_category, анкети покупця — DOC-031, розділи «Отримання категорій покупців», «Отримання даних про покупця», «Зміна типу доступу покупця», «Зміна категорії покупця», «Отримання анкети покупця».

Ідентифікація на Терміналі

Касир знаходить існуючого Роздрібного Покупця за будь-яким ідентифікатором пов'язаного Користувача (телефон, email, зовнішній ідентифікатор тощо) або за номером картки лояльності як додатковим власним ідентифікатором Покупця.

Чим Роздрібний Покупець володіє і з чим пов'язаний

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

Окремі сутності, якими Роздрібний Покупець володіє

Купон — стає власністю Покупця тільки після додавання до його гаманця (встановлення зв'язку). До цього моменту Купон існує як самостійна сутність без власника-Покупця.
Покупка — кожна покупка є окремою сутністю, пов'язаною з Роздрібним Покупцем.
Кредит — кожне нарахування або списання є окремою сутністю, пов'язаною з Роздрібним Покупцем.
Екземпляр бонусного рахунку — окрема сутність, пов'язана з Роздрібним Покупцем.
Екземпляр клієнтського рахунку — окрема сутність, пов'язана з Роздрібним Покупцем.

Не є окремими сутностями, а є агрегатами, якими володіє Роздрібний Покупець

Баланс Кредитів — похідне значення зі списку пов'язаних Кредитів.
Історія покупок — список пов'язаних Покупок.
Список екземплярів клієнтських рахунків.
Список екземплярів бонусних рахунків.
Гаманець — складений агрегат, що містить списки Купонів і рахунків (екземплярів бонусних та клієнтських рахунків) Покупця.

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

Створення

Запис Роздрібного Покупця створюється за одним з трьох канонічних тригерів:

Перша покупка на Терміналі — Покупець заводиться автоматично у процесі обслуговування на Точці продажу.
Ручне додавання касиром — на Терміналі під час або поза процесом покупки.
Ручне додавання або імпорт у Панелі управління Бізнесом — операторами Бізнесу / Бренду.

Реєстрація Користувача сама по собі не створює Роздрібного Покупця в жодному Бренді — Користувач і Роздрібний Покупець є окремими сутностями різних шарів, і участь у програмі лояльності конкретного Бренду — окрема подія. Виняток: реєстрація Користувача через White Label додаток може автоматично створювати Роздрібного Покупця Бренду, якщо це явно задано у налаштуваннях такого додатку.

Видалення Роздрібного Покупця

Видалення Роздрібного Покупця відбувається за моделлю soft-delete: запис не видаляється фізично, а позначається як видалений, зберігаючи цілісність історичних посилань (Покупок, Кредитів, рахунків).

За окремим зверненням пов'язаного Користувача дані Роздрібного Покупця можуть бути повністю анонімізовані згідно з вимогами GDPR — у цьому випадку особисті ідентифікатори видаляються, а агрегатні та операційні записи зберігаються в знеособленому вигляді.

Поведінка при видаленні пов'язаного Користувача

Якщо пов'язаний Користувач видаляється, Роздрібний Покупець переходить у термінальний стан: історичні дані зберігаються, будь-які нові операції з Покупцем неможливі. Цей стан незворотній — відновлення Покупця та продовження роботи з ним за поверненням Користувача не передбачено.

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

Поведінка при видаленні Бренду

Видалення Бренду відбувається виключно за моделлю soft-delete.

API-поверхня

Сутність Роздрібного Покупця має поверхню у трьох з шести API inCust. User API (KNOW-007) і Corporate Client API (KNOW-011) до Роздрібного Покупця не стосуються: перший працює виключно з шаром ідентичності (Користувач), другий — з окремою сутністю Корпоративного Покупця.

Terminal API (канонічне джерело)

Див. Swagger Terminal API (KNOW-009), DOC-031. Інтерфейс касира і Терміналу.

Ідентифікація і пошук:

Метод	Шлях	Призначення
`POST`	`/customers`	Знайти Покупця за масивом ідентифікаторів і повернути його дані
`GET`	`/customers/all/search`	Розширений пошук серед Покупців (Роздрібних і Корпоративних)
`GET`	`/customers/identification`	Перелік ідентифікаторів Покупця
`POST`	`/customers/identification`	Додати ідентифікатор пов'язаному Користувачу
`DELETE`	`/customers/identification`	Видалити ідентифікатор
`GET`	`/display_customer`	Поточний Покупець на дисплеї касира

Створення і життєвий цикл:

Метод	Шлях	Призначення
`POST`	`/customers/add`	Створити Користувача і одночасно Роздрібного Покупця
`POST`	`/customers/consent`	Зафіксувати згоду Покупця

Атрибути:

Метод	Шлях	Призначення
`GET` `PATCH`	`/customers/access_type`	Прочитати / змінити `access_type`
`GET` `PATCH`	`/customers/card_category`	Прочитати / змінити `card_category`
`GET` `PATCH`	`/questionnaire`	Значення полів анкети покупця
`GET`	`/customer_fields`	Схема доступних полів анкети (визначається Брендом)

Гаманець та операції з агрегатами:

Метод	Шлях	Призначення
`GET`	`/customers/benefits/accounts`	Список екземплярів рахунків Покупця
`GET`	`/customers/benefits/accounts/{account_id}`	Один екземпляр рахунку
`GET`	`/customers/benefits/bonuses`	Баланс Кредитів
`GET`	`/customers/benefits/bonuses/{currency}`	Баланс Кредитів у конкретній валюті
`GET`	`/customers/benefits/coupons`	Купони у гаманці
`POST`	`/customers/benefits/topup`	Поповнити рахунок
`POST`	`/customers/benefits/write_off`	Списати з рахунку
`POST`	`/customers/benefits/adjust`	Корекція (одним викликом нарахування або списання)

Чеки і фіскалізація:

Метод	Шлях	Призначення
`GET`	`/transactions/receipt/customer/print/required`	Транзакції, для яких треба друкувати чек Покупцю
`GET`	`/transactions/receipt/customer/print/{transaction_id}/processed`	Позначити чек як надрукований

Ендпоінти виду /customers/{user_id_value}/... і /questionnaire/{user_id_value}/... у специфікації позначені як DEPRECATED — це старі варіанти з ID в URL, замінені на ідентифікацію через тіло запиту. У новому коді спиратися на сучасні варіанти зі списків вище.

Business API

Див. Swagger Business API (KNOW-006). Адмін-кабінет Бізнесу/Бренду; третій канонічний тригер створення Покупця (ручне додавання та імпорт).

Адміністрування окремого Покупця:

Метод	Шлях	Призначення
`GET` `POST` `PATCH`	`/customer`	Знайти / створити / змінити Покупця
`GET`	`/customer/{user_id}`	Дані конкретного Покупця
`POST`	`/customer/consent`	Додати згоду Покупця
`PATCH`	`/customer/access`	Змінити `access_type`
`POST`	`/customer/import`	Імпорт списку Покупців
`GET`	`/customer/import/preferences`	Налаштування формату імпорту
`POST`	`/customer/customers_bulk_ids`	ID для bulk-операцій
`POST`	`/customers`	Список Покупців Бізнесу або програми лояльності
`GET`	`/customers/{user_id}/user_profile`	Профіль пов'язаного Користувача (cross-layer Customer → User)

Анкета покупця (схема):

Метод	Шлях	Призначення
`GET` `POST` `PATCH`	`/customer/field`	Поля анкети
`DELETE` `PATCH`	`/customer/field/{field_id}`	Окреме поле

Кредити Покупця:

Метод	Шлях	Призначення
`GET`	`/customer/{user_id}/bonuses`	Баланс і історія Кредитів
`POST`	`/customer/{user_id}/bonuses/{currency}/refill`	Нарахувати
`POST`	`/customer/{user_id}/bonuses/{currency}/write_offs`	Списати
`POST`	`/customer/{user_id}/bonuses/{currency}/adjust`	Корекція

Екземпляри спецрахунків Покупця:

Метод	Шлях	Призначення
`GET` `POST`	`/customer/{user_id}/special_accounts`	Список / додати екземпляр
`GET` `PATCH`	`/customer/{user_id}/special_accounts/{account_id}`	Один екземпляр
`POST`	`/customer/{user_id}/special_accounts/{account_id}/refill`	Поповнити
`POST`	`/customer/{user_id}/special_accounts/{account_id}/write_offs`	Списати
`POST`	`/customer/{user_id}/special_accounts/{account_id}/adjust`	Корекція
`GET`	`/customer/{user_id}/special_accounts/{account_id}/goods`	Доступні товари за цим спецрахунком
`GET` `PATCH`	`/business/special_account/{account_id}/loyalty/{loyalty_id}/customers`	Список Покупців спецрахунку / прив'язати спецрахунок до Покупця

Категорії карток лояльності (конфігурація card_category):

Метод	Шлях	Призначення
`GET` `POST`	`/loyalty/{loyalty_id}/card_categories`	Список / створити категорію
`GET` `PATCH`	`/loyalty/{loyalty_id}/card_categories/{category_id}`	Окрема категорія
`POST` `DELETE`	`/loyalty/{loyalty_id}/card_categories/{category_id}/image`	Зображення категорії
`GET` `POST` `PATCH`	`/loyalty/{loyalty_id}/card_categories_rules`	Правила переходу між категоріями
`GET` `PATCH`	`/loyalty/{loyalty_id}/card_categories_settings`	Загальні налаштування системи категорій

Існує близько п'ятнадцяти додаткових ендпоінтів виду /card_categories/{id}/currencies/.../price_options і /taxes — конфігурація знижок і податків на рівні категорії; до самої сутності Покупця не стосуються.

Зовнішні форми:

Метод	Шлях	Призначення
`GET`	`/customer/{user_id}/external_forms`	Зовнішні форми, заповнені Покупцем

Client API

Див. Swagger Client API (KNOW-008). Тут Покупець — сам актор. Усі ендпоінти неявно в контексті поточного авторизованого Покупця.

Власний гаманець і агрегати:

Метод	Шлях	Призначення
`GET`	`/wallet`	Гаманець Покупця (агрегат: купони + рахунки)
`GET`	`/loyalty/{loyalty_id}`	Дані конкретної програми лояльності (= конкретного запису Покупця в одному з Брендів)
`GET`	`/loyalty/{loyalty_id}/customers/add`	Доєднатися до програми лояльності
`GET` `POST`	`/loyalty/{loyalty_id}/customers/cards`	Картки лояльності Покупця
`GET`	`/loyalty/{loyalty_id}/customers/temporary_code/generate`	Тимчасовий код ідентифікації Покупця для каси

Купони у гаманці:

Метод	Шлях	Призначення
`GET`	`/coupons`	Список Купонів
`POST`	`/coupons`	Додати Купон у гаманець (момент, коли Купон стає власністю Покупця)
`GET`	`/coupon/{coupon_id}`	Один Купон
`GET`	`/coupon/{coupon_id}/redeem`	Активувати / використати Купон
`GET`	`/coupon/{coupon_id}/share`	Поділитися кодом
`DELETE`	`/coupon/{coupon_id}`	Видалити Купон з гаманця
`GET`	`/coupons/coupon/{code}`	Інформація про Купон до додавання

Перекази між Покупцями:

Метод	Шлях	Призначення
`POST`	`/loyalty/{loyalty_id}/customers/benefits/transfer/bonuses`	Переказати Кредити іншому Покупцю того ж Бренду
`POST`	`/loyalty/{loyalty_id}/customers/benefits/transfer/accounts`	Переказати кошти зі спецрахунку

Apple Wallet:

Метод	Шлях	Призначення
`GET`	`/pkpass/loyalty/{loyalty_id}/customers/card/{card_id}/generate`	Згенерувати `.pkpass` файл картки лояльності

Платіжний гаманець (/pmt/wallet/*) — окрема підсистема, накладена поверх Покупця:

Метод	Шлях	Призначення
`GET`	`/pmt/wallet`	Мобільний платіжний гаманець
`POST`	`/pmt/wallet/payment`	Оплата з гаманця
`POST`	`/pmt/wallet/payment/otp`	OTP-підтвердження
`POST`	`/pmt/wallet/payment/status`	Статус оплати
`POST`	`/pmt/wallet/cardpassword/{action}`	Керування паролем картки
`GET` `POST`	`/pmt/wallet/{wallet_type}`	Робота з конкретним типом платіжного гаманця

Зворотний звʼязок:

Метод	Шлях	Призначення
`GET` `POST`	`/customer_feedback/feedbacks`	Список / створити відгук Покупця
`GET` `PATCH` `DELETE`	`/customer_feedback/feedbacks/{feedback_id}`	Окремий відгук
`POST`	`/customer_feedback/feedbacks/{feedback_id}/complete`	Завершити відгук
`POST` `GET` `DELETE`	`/customer_feedback/feedbacks/{feedback_id}/attachments/...`	Файли (фото / відео / аудіо) до відгуку
`GET`	`/customer_feedback/feedback_sources/{source_id}`	Дані джерела відгуку

Відповідність «атрибут — ендпоінти»

Зведена таблиця для швидкого пошуку: який атрибут якими ендпоінтами читається/змінюється.

Атрибут з канону	Канонічне джерело (Terminal API, DOC-031)	Адмін-сторона (Business API)	Сторона Покупця (Client API)
`access_type`	`GET/PATCH /customers/access_type`	`PATCH /customer/access`	—
`card_category`	`GET/PATCH /customers/card_category`	`GET/POST/PATCH /loyalty/{id}/card_categories[…]` (схема)	—
анкета покупця	`GET/PATCH /questionnaire`, `GET /customer_fields`	`GET/POST/PATCH /customer/field[…]` (схема)	—
номер картки лояльності	через `POST /customers` (ідентифікація)	—	`GET/POST /loyalty/{id}/customers/cards`
картка для Apple Wallet	—	—	`GET /pkpass/loyalty/{id}/customers/card/{cid}/generate`

Джерела з Shared Drive

DOC-031 — REST API Термінала inCust (веб-документація): канонічне джерело визначень access_type, card_category, анкети покупця.

Сутність «Роздрібний Покупець» в системі inCust

On this page