Сутність «Точка продажу» в системі inCust

Синоніми: Point of Sale, POS, Sales Point (неканонічні англомовні відповідники; канонічний термін українською — «Точка продажу»). У KNOW-002 (Бізнес, v1.1) трапляється форма «Торгівельні точки» — це варіантне написання тієї самої сутності.

Що це таке

Точка продажу — операційна сутність Бренду в системі inCust, що виступає оболонкою для групи Терміналів і одиницею організації фізичних продажів, доставки чи онлайн-замовлень. Точка продажу не є самостійним тенантом і не є рівнем ізоляції даних: вона існує як атрибут належності, через який система фільтрує Термінали, Покупки, Транзакції, замовлення Online Store і правила лояльності, що застосовуються в її межах.

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

Точка продажу — третій рівень доменної ієрархії inCust:

Бізнес  →  Бренд  →  Точка продажу  →  Термінал

Один Бренд може володіти кількома Точками продажу; кожна Точка цілком належить рівно одному Бренду (через поле loyalty_id у схемі POS Business API). Бізнес отримує контроль над Точками продажу опосередковано, через володіння відповідним Брендом.

Точка продажу не є самостійним суб'єктом прав у рольовій моделі. Доступ Робітників регулюється на двох сусідніх рівнях: роль «Менеджер Бренду» дає управління всіма Точками продажу свого Бренду, а доступ касира до конкретної Точки виражається опосередковано — через список Терміналів, що належать цій Точці.

Модель володіння

Точка продажу володіє

• Терміналами — кожен Термінал має поле pos_id, що однозначно прив'язує його до конкретної Точки продажу. Зв'язок 1 : N: одна Точка продажу — багато Терміналів. Перенесення Термінала між Точками продажу здійснюється редагуванням pos_id.
• Налаштуваннями Online Store (для Точок типу online-store) — окрема структура PosOnlineStore, доступна через GET|PATCH /pos/{pos_id}/online_store. Містить термін життя кошика, типи замовлень і платежів, перелік адрес для повідомлень, Термінал за замовчуванням для обробки.
• Налаштуваннями зворотного зв'язку (PosCustomerFeedbackSettings) — доступні через GET|PATCH /customer_feedback/pos/{pos_id}/settings. На рівні Точки продажу можна або наслідувати налаштування Бренду, або задати індивідуальні (use_individual_settings).
• Переліком додаткових комісій та сервісів (AdditionalService[]) — позицій, які можуть бути нараховані або включені у чек у межах цієї Точки продажу. Перелік доступний на стороні Терміналу через Settings.pos.additional_services.
• Графом маршрутизації замовлень (ReferencedPosContainer.order_processing) — Точки продажу можуть бути з'єднані парами «батько-дитина» (parents, children) для пересилання обробки замовлень. Канонічний кейс: Точка типу online-store (батько) переадресовує замовлення на фізичну Точку (дитина), що відвантажує товар.

Точка продажу НЕ володіє

• Робітниками і ролями — належать Бізнесу, видаються на рівні Бізнесу, обмежуються Брендом (об'єктом ролі), а на рівні конкретних Терміналів — списком Терміналів Робітника.
• Програмою лояльності, Купонами, Товарами, Податками, Кредитами — усі ці сутності належать Бренду. Точка продажу може лише фігурувати у правилах лояльності як обмеження області застосування правила: поле LoyaltyRule.pos у Terminal API містить список Точок продажу, до яких правило застосовується.
• Покупцями — Роздрібні Покупці належать Бренду, не Точці продажу.

Типи Точки продажу

Поле type (PosType) приймає одне з трьох канонічних значень:

• pos — звичайна фізична Точка продажу: магазин, кафе, заклад послуг, АЗС, мийка. Найпоширеніший тип.
• road-tanker — мобільна паливна точка (бензовоз / автозаправник з доставкою на місце). У контексті Online Store відповідає сценарію з order_type: fuel-taxi.
• online-store — онлайн-магазин Бренду. Не має фізичної прив'язки; обробка замовлень може делегуватися на фізичну Точку через граф references.order_processing. Має додаткову конфігурацію через PosOnlineStore.

Атрибути

Канонічна схема Точки продажу у Business API (#/definitions/POS).

Ідентифікація і власність

• id (UUID) — глобальний ідентифікатор Точки продажу.
• loyalty_id — ідентифікатор Бренду-власника. Обов'язковий при створенні.
• title — внутрішня назва Точки (для Бізнес-Панелі, не публічна).
• type — тип Точки продажу (див. вище).
• active (0 | 1) — прапор активності.
• priority (integer, default 0) — порядок сортування в публічних і службових списках; враховується при sort_by_priority=true.

Публічна вітрина (мультимовні поля)

• public_title (MultiLanguageObject) — публічна назва Точки продажу, видима Покупцям у мобільному додатку та клієнтських інтерфейсах.
• public_description (MultiLanguageObject) — публічний опис.
• addresses (MultiLanguageObject) — адреса Точки продажу, мультимовно.
• photos (ImageObjectsList) — масив фотографій Точки. Окремо керується через POST|DELETE /pos/{pos_id}/photo.
• phones (PhoneNumbersList) — телефони Точки.
• links (LoyaltyLinks) — додаткові посилання.
• categories (LoyaltyCategory[]) — категорії Бренду, до яких належить Точка (для фільтрації Покупцями).

Геолокація і часова зона

• country (ISO-код країни).
• latitude, longitude (double) — GEO-координати.
• time_zone — IANA-назва часової зони (наприклад, Europe/Kyiv).
• maximum_service_distance (km, default 0 = без обмеження) — максимальна відстань обслуговування. Використовується для Точок з доставкою або мобільних типів (road-tanker).

Операційні параметри

• check_item_enter_mode (CheckItemEnterMode) — режим вводу позицій чека на Терміналах цієї Точки:
  • without-limits — будь-який ввід (вільний вибір касира);
  • presets-only — лише з преднастроєних товарів/послуг;
  • manually-only — лише ручний ввід.
• additional_services_required (0 | 1) — прапор обов'язковості додаткових комісій та сервісів цієї Точки. Сам перелік додаткових комісій та сервісів — позицій, які можуть бути нараховані або включені у чек у межах цієї Точки продажу, — конфігурується окремо і доступний на стороні Терміналу через Settings.pos.additional_services.

Публікація в каталозі

• catalog_publication_state (PosCatalogPublicationState): none | requested | rejected | allowed — стан публікації Точки в публічному каталозі inCust.
• catalog_publication_comment (string) — коментар модерації (наприклад, причина rejected).

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

Спеціалізована конфігурація

Online Store (PosOnlineStore)

Окрема структура, доступна через GET|PATCH /pos/{pos_id}/online_store. Релевантна перш за все для Точок типу online-store, але технічно може застосовуватися й до інших типів:

• pos_id — посилання на Точку продажу.
• terminal_id — Термінал за замовчуванням для обробки замовлень.
• cart_expire_days — термін життя кошика Покупця в днях.
• order_type: online-store | fuel-taxi — модель обробки замовлення.
• payment_type: none | bonuses | possible | required — політика оплати в магазині.
• transaction_type: sale | reserve | authorize-payment — тип транзакції, що породжується замовленням.
• notification_emails (string[]) — список електронних адрес для сповіщень про зміни статусу замовлень.

Зворотний зв'язок (PosCustomerFeedbackSettings)

Доступні через GET|PATCH /customer_feedback/pos/{pos_id}/settings. Дозволяють Точці продажу або наслідувати налаштування зворотного зв'язку з Бренду, або задати власні:

• use_individual_settings (0 | 1) — прапор використання індивідуальних налаштувань.
• active (0 | 1) — прапор активності системи зворотного зв'язку для цієї Точки.
• feedback_source_id, transaction_feedback_source_id — джерела зворотного зв'язку.
• transaction_feedback_message_send, _delay (хв), _text (мультимовно), _type — параметри запрошення на оцінку після завершення транзакції. Канали: push-chatbot-viber-sms, email, external-system та їхні комбінації.
• print_feedback_on_check, print_feedback_on_check_message_text — друк запрошення на чеку.

Додаткові комісії та сервіси (AdditionalService[])

Перелік позицій, що можуть бути нараховані або включені у чек у межах цієї Точки продажу: фіксовані комісії, додаткові послуги (обслуговування, упаковка, доставка тощо), які касир чи логіка Терміналу додають до чека окремими рядками. Прапор additional_services_required на схемі POS визначає, чи є ці позиції обов'язковими для нарахування. Доступ до самого переліку — на стороні Терміналу через Settings.pos.additional_services.

Маршрутизація замовлень (ReferencedPosContainer)

GET|PATCH /pos/{pos_id}/references повертає об'єкт із полем order_processing, що описує батьків і дітей цієї Точки в графі обробки замовлень. Типовий патерн: Точка типу online-store має одну або кілька дочірніх фізичних Точок, на які пересилаються її замовлення відповідно до правил Бренду.

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

Рольова модель

Згідно з обмеженнями ролей у Business API:

• Читання Точок продажу (GET /pos, GET /pos/{pos_id}, GET /embedded/pos, GET /loyalty/{loyalty_id}/pos):
  • Адміністратор Бізнесу;
  • Менеджер Бізнесу;
  • Менеджер Бізнесу / Тільки перегляд;
  • Менеджер Бренду;
  • Менеджер Бренду / Тільки перегляд.
• Створення і редагування (POST /pos, PATCH /pos/{pos_id}, PATCH /pos/{pos_id}/references, PATCH /pos/{pos_id}/online_store, керування фото):
  • Адміністратор Бізнесу;
  • Менеджер Бізнесу;
  • Менеджер Бренду.
  • Ролі з суфіксом «/ Тільки перегляд» прав на запис не мають.

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

Фільтрація та запити

• GET /pos приймає параметри pos_type (фільтр all | pos | road-tanker | online-store) і sort_by_priority (boolean).
• GET /loyalty/{loyalty_id}/pos повертає Точки продажу конкретного Бренду.
• GET /embedded/pos — полегшена версія для випадаючих списків (схема PosEmbedded, без важких полів типу catalog_publication_*); підтримує параметр only_active.
• GET /pos/{pos_id}/terminals повертає Термінали Точки продажу.

Створення Точки продажу

POST /pos приймає тіло схеми POS; loyalty_id у тілі визначає Бренд-власник. Перша Точка продажу автоматично створюється в межах флоу POST /business (одночасно з першим Брендом і першим Терміналом).

Точка продажу в Terminal API

Terminal API не керує життєвим циклом Точки продажу — лише читає її як частину контексту виконання операцій:

• GET /settings повертає Settings.pos зі схемою Pos. Terminal API має власну, дещо урізану версію #/definitions/Pos — без priority, time_zone, active, catalog_publication_* і public_*, але з phone_prefix, phone_prefix_local і повним списком additional_services: AdditionalService[].
• Check.pos (схема CheckPos) — інформація про Точку продажу на чеку.
• LoyaltyRule.pos (PosEmbeddedList) — список Точок продажу, на які поширюється правило лояльності; правило Бренду може бути обмежене підмножиною Точок.
• Transaction.pos_title — назва Точки продажу у відповіді про транзакцію.
• Order.pos_id, Shipping.pos — замовлення і доставка прив'язуються до конкретної Точки продажу.
• TourCardService.usage_limit_per_pos — туристичні картки мають обмеження використання per-POS.

Канонічне джерело — Swagger Terminal API (KNOW-009).

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

• Бізнес-Панель (https://business.incust.com/) — основний інтерфейс управління Точками продажу та їхніми Терміналами.
• Business API (KNOW-006) — програмний доступ для інтеграцій і автоматизації, теґ POS.
• Публічний каталог inCust — для Точок зі станом catalog_publication_state: allowed.

Пов'язана документація

• Сутність «Бізнес» (KNOW-002) — тенант, що володіє Брендом.
• Сутність «Бренд» (KNOW-003) — безпосередній власник Точок продажу.
• Сутність «Роздрібний Покупець» (KNOW-012) — суб'єкт обслуговування на Точках продажу.
• Словник доменних сутностей (KNOW-004) — короткі визначення.
• Swagger Business API (KNOW-006) — повна специфікація управління Точками продажу.
• Swagger Terminal API (KNOW-009) — використання Точки продажу на Терміналі.