Сутність «Бізнес» в системі inCust

Що це таке

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

Місце в архітектурі (DOC-008)

В архітектурі inCust (incust.v02) Бізнес фігурує як один з ключових акторів платформи разом з:

• Platform Administrator (адмін inCust, зовнішні Бізнесу)
• Business Administrator (адмін самого Бізнесу)
• Business Employee (Робітник Бізнесу)
• Customer / Commercial Customer (роздрібний/корпоративний покупець)
• External Integration

Бізнес взаємодіє з платформою через Business Dashboard (Бізнес Панель / БП) та REST API Бізнесу. У специфікації цього REST API (Business API, KNOW-006) Бізнес є кореневим контекстом тенанта: сутності прямого володіння доступні під /business, /staff, /corporate_customers, /transactions, а сутності Брендів — транзитивно через loyalty_id (див. розділ «Представлення в API»).

Модель володіння дочірніми сутностями

Безпосереднє володіння (Бізнес → сутність)

• Бренди — суб-юніти всередині Бізнесу
• Корпоративні Покупці (Commercial Customers / B2B) — прив'язані напряму до Бізнесу, поза контекстом конкретного Бренду
• Робітники з ролями
• Рахунок Бізнесу і Бонуси Бізнесу
• Налаштування Бізнесу (режим автоматизації, API KEY, рольова модель тощо)
• Налаштування B2E-кредитування (спеціальні рахунки типу «Кредитний з лімітом», розстрочки з фінансуванням роботодавцем)

Опосередковане володіння (Бізнес → Бренд → сутність)

Сутності, що належать безпосередньо Бренду; Бізнес отримує над ними контроль виключно через володіння відповідним Брендом:

• Покупці (роздрібні, Retail Customers)
• Точки продажу (Sales Points)
• Термінали (POS, Kiosk, Fuel Dispenser, Car Wash тощо)
• Товари
• Зовнішні форми
• Програма лояльності для клієнтів Бренду, що включає правила лояльності товарні/чекові/купонні, серії купонів та відповідні налаштування Бренду
• Податки та збори

Поліморфне володіння (Бізнес АБО Бренд — залежно від типу та контексту виконання)

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

Режими роботи (DOC-009)

Бізнес може працювати у двох режимах автоматизації:

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

Незалежно від режиму, Бізнес може згенерувати API KEY Бізнесу для прямої автоматизації в АПІ БП в обхід рольової моделі.

Фінансово-облікові аспекти

• Бізнес має власний рахунок Бізнесу для оплати послуг платформи та бонуси Бізнесу.
• Податки та збори (DOC-016) — налаштовуються на рівні Бренду, у межах налаштувань Бренду.
• На рівні Бренду (всередині Бізнесу) може бути налаштована програма лояльності для клієнтів Бренду (DOC-010).
• На рівні Бізнесу може бути налаштоване кредитування з фінансуванням роботодавцем (B2E) — спеціальні рахунки типу «Кредитний з лімітом» (DOC-033).

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

Бізнес взаємодіє з платформою через Бізнес-Панель і Business API (KNOW-006). У специфікації Бізнес є кореневим контекстом тенанта: ендпоінти прямого володіння згруповані під /business, /staff, /corporate_customers і /transactions, тоді як ресурси Брендів доступні транзитивно через loyalty_id (їх перелік — у KNOW-003). Робота Користувача поза контекстом тенанта (вибір ролі Бізнес або Покупець) виконується через User API (KNOW-007).

Сам Бізнес

• GET /business, PATCH /business, POST /business — читання, зміна, створення Бізнесу (одразу з першим Брендом, Точкою продажу і Терміналом).
• GET /business/dashboard, GET /business/general_status — зведена інформація та загальний стан.
• GET|PATCH /business/legal_info, GET /business/currencies — юридичні дані та валюти.
• GET|PATCH /business/settings і підресурси …/notifications, …/messages/providers/{message_type} (власні провайдери розсилок), …/photo; GET|POST|PATCH /business/custom/preferences — налаштування.

Автентифікація та рольова модель

• POST /business/auth/register[/pre], POST /business/auth/token[/pre], GET /business/auth/token/renew, POST /business/auth/social_login/google/token — реєстрація і вхід власника.
• POST /business/auth/staff/signin, …/signout — вхід/вихід Робітника.
• PATCH /business/role_based_model — стан рольової моделі (монопольний режим ↔ рольова модель).
• GET /business/api_key, DELETE /business/api_key — API KEY Бізнесу для прямої автоматизації в обхід рольової моделі.

Користувач Бізнесу

• GET|PATCH /business/user/profile, …/language, POST …/avatar, …/change_password.
• Зміна та верифікація логіну: …/email/{change|validate|verify}, …/phone/{change|validate|verify}, …/external_id/{change|validate|verify}, GET …/confirm_email/{email_token}.

Робітники (Staff)

• GET /staff, POST /staff, GET|PATCH /staff/{staff_id} — список і керування Робітниками та їхніми ролями.
• GET|POST|DELETE /terminal/{terminal_id}/staff — список доступу Робітників до конкретного Терміналу (доступ до Терміналів регулюється окремо від ролі).

Корпоративні Покупці (B2B)

• GET|POST /corporate_customers, GET|PATCH /corporate_customers/{customer_id} — список і картка Корпоративного Покупця.
• GET|POST /corporate_customers/categories[/{category_id}], …/categories/assign — категорії.
• GET|PATCH|POST|DELETE /corporate_customers/questionnaires/fields[/{field_id}] — поля анкети.
• GET|POST /corporate_customers/{customer_id}/special_accounts[/{account_id}] з операціями …/refill, …/write_offs, …/adjust; підресурси …/price_options, …/taxes[/items], …/goods — спеціальні рахунки покупця (зокрема B2E-кредитування), ціни, податки, доступні товари.

Рахунок Бізнесу, бонуси, тарифи, оплати

• POST /business/bonuses_redeem — погашення бонусів Бізнесу.
• GET /business/tariff_details[/billing/{billing_operation_id}], GET /business/tariffs_available, PATCH /business/tariff_set, …/tariff_change_to_base — тарифні плани й білінг.
• GET /business/sms_tariff, GET /business/viber_tariff — тарифи каналів розсилок.
• GET|POST /business/special_account[/{account_id}] — спеціальні рахунки Бізнес-рівня (модель B2E-кредитування «Кредитний з лімітом»); …/{account_id}/loyalty/{loyalty_id}/customers — прив'язка спецрахунку до Покупців у межах Бренду.
• Платіжні провайдери: POST /business/{stripe|liqpay|wayforpay|flutterwave|paypro}/create_payment_new, …/stripe/create_payment_by_saved, GET|DELETE /business/regular_payment, …/{liqpay|wayforpay}/regular_payment — оплата послуг платформи.

Транзакції (поліморфні)

• GET /transactions, GET /transactions/{transaction_id}/{check|order|receipt} — журнал і документи.
• POST /transactions/bonuses/{add|adjust|write_offs}, …/special_account/{refill|write_offs|adjust}, …/cancel, …/finalize — операції з рахунками/бонусами Покупця.
• GET /customer/{user_id}/bonuses, POST /customer/{user_id}/bonuses/{currency}/{refill|write_offs|adjust} — бонуси конкретного Покупця.

White Label

• GET /business/white_label/applications — застосунки White Label, доступні Бізнесу.

Ресурси Брендів (Точки продажу, Термінали, Товари, правила лояльності, серії купонів, податки та збори) у специфікації висять під loyalty_id і належать Бізнесу лише транзитивно — їх перелік наведено в KNOW-003.

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

Для будь-якого запиту звітності, аудиту чи фільтрації «за Бізнесом» необхідно враховувати обидва шляхи доступу:

1. Прямий — сутності, що належать Бізнесу безпосередньо. На рівні Business API це ендпоінти під /business, /staff, /corporate_customers і /transactions.
2. Транзитивний — сутності, що належать будь-якому Бренду цього Бізнесу. На рівні Business API це ендпоінти під loyalty_id.

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

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

• Бізнес-Панель (адмін): https://business.incust.com/
• Кабінет бізнесу / інструкції: https://incust.com/ua/knowledgebase/business-user-manual/instruction-business/

Джерела з Shared Drive

• DOC-008 incust.v02.pdf — Загальна архітектура inCust: https://drive.google.com/file/d/1etBcLVrYA0NfTqElUSt4Od1VixmKJUW3/view
• DOC-009 Ролёва модель inCust: https://drive.google.com/file/d/1-N9UDIETI3e9odPWNgZ2O9efBGG9fp3PncrRmpyQAAM/view
• DOC-010 inCust Правила 20: https://drive.google.com/file/d/1FLkaIDp2LQdiRJG0_GmBUQ2Rtd37LVEOM3k8XWNJJaI/view
• DOC-011 Business customers import: https://drive.google.com/file/d/1TdnoUWu4eG3Tb3J8OnbSsf4D2CGoQwCx2biPmDxnrcs/view
• DOC-016 Налоги и сборы: https://drive.google.com/file/d/1GhlBeOPjn-wNBRHTE-AFrA2UPzHVgZBLJPJuuxgnnEE/view
• DOC-033 Оплата частинами (B2E): https://drive.google.com/file/d/1428wZgD0Yuw9ua9FSU4FzgJf1rOU_Kla7NzVTWwHHmg/view