# Налаштування — WIKI Helomi

> Поля, воронки й етапи, люди й доступи, бренди й юрособи, довідники, автоматизація.


---

# Налаштування: огляд

«Налаштування» — одне меню на весь Helomi, де людина сама, без розробника, налаштовує поля, воронки, доступи, склад, фінанси, документи й автоматизацію. Пункти згруповані за тим, що ви шукаєте (людина, продажі, склад, гроші, система), а зміни одразу видно в розділах, на телефоні й у тому, що бачать ШІ-співробітники.

## Можливості
- Одне ліве меню з групами, що згортаються, і пошуком «Знайти налаштування».
- Особисті налаштування («Мій акаунт») і налаштування компанії — в одному місці.
- Кожен розділ має «⋮ → Налаштувати поля» — перехід саме до його полів.
- На телефоні — список груп на весь екран і «‹ Налаштування» над сторінкою.

## 1. Налаштування
Відкрийте «Налаштування» в меню. Ліворуч — групи, праворуч — сторінка вибраного пункту. Відкрита та група, де ви зараз; інші розгортаються кліком. Пункти зі стрілочкою відкриваються поза «Налаштуваннями» (наприклад, «API-документація» — у новій вкладці).

## 2. Знайти потрібний пункт
Пишіть у поле «Знайти налаштування» — меню покаже лише пункти, у назві яких або в назві групи є ці слова. Нічого не знайшлося — «Нічого не знайдено».

На телефоні корінь «Налаштувань» — список груп і пунктів на весь екран; на сторінці пункту зверху «‹ Налаштування» повертає до списку з тією самою відкритою групою. Таблиці на телефоні стають картками.

## 3. Групи меню і що в них
| Група | Пункти | Стаття |
| --- | --- | --- |
| «Мій акаунт» | «Мій профіль», «Мої організації», «Швидкий доступ», «Вигляд», «Робочий стіл», «Push-сповіщення», «Гарячі клавіші», «Вимкнення непотрібних блоків», «Паролі та замітки» | «Швидкий доступ і меню телефона» |
| «Команда» | «Користувачі», «ШІ-співробітники», «Каталог ШІ», «Відділи», «Філії», «Команди», «Компанії та реквізити», «Бренди та юрособи» | «Люди, ролі, доступи», «ШІ-співробітники», «Бренди і юрособи» |
| «Доступи» | «Розділи меню», «Ролі», «Доступи» | «Люди, ролі, доступи» |
| «Продажі» | «Воронки й етапи», «Угоди: загальні», «Переходи по етапах», «Валідація», «Терміни по замовленнях в етапах», «Джерела», «Теги» | «Воронки, етапи, переходи», «Довідники» |
| «Типи даних» | «Клієнти», «Угоди», «Товари», «Завдання», «Дод. контакти», «Власні розділи», «Розширення», «Користувацькі фільтри» | «Типи даних і поля», «Власні розділи», «Розширення» |
| «Склад і товари» | «Загальні налаштування», «Одиниці виміру», «Категорії складу», «YML генератор», «Синхронізація товарів через XML» | «Склад і товари» |
| «Фінанси» | «Гаманці», «Валюти і курс», «Сегменти», «Категорії фінансів», «Каси», «Система лояльності» | «Довідники», «Фінанси», «Каса» |
| «Документи» | «Шаблони і статуси» | «Документи» |
| «Інтеграції» | «Усі інтеграції» (маркетплейси, сайти, перевізники, оплати, повідомлення, ШІ), «Вхідні вебхуки» | «Інтеграції», статті «int-…», «Вебхуки» |
| «Автоматизація» | «Тригери (Webhook)», «Правила передачі» | «Тригери», «Правила передачі» |
| «Компанія» | «Тариф і оплата», «Консоль платформи» | «Консоль платформи» |
| «Система» | «Сервер» (лише без режиму платформи; з ним — у консолі платформи), «Загальні параметри», «Імпорт із KeepinCRM», «Очистка інформації», «Видалена інформація», «API-документація», «З чого почати?», «Підтримка» | — |

«Мої організації» і «Тариф і оплата» видно, коли сервер працює в режимі кількох організацій; «Консоль платформи» — лише адміністратору платформи. «Підтримка» — одна для всіх (власник 16.10): у режимі платформи звернення йдуть команді Helomi (теми, «Питання вирішено?», фільтри, «Доступ підтримки» — стаття «Платформа», §5); в окремій установці — служба підтримки всередині компанії, як була.

## 4. Валідація: свої заборони з текстом помилки
Валідація — ваші власні заборони без розробника: «не відправляти угоду без ТТН», «не закривати без оплати». Коли умова справджується, дію зупинено, і людина бачить ваш текст помилки.

«Налаштування → Продажі → Валідація» → «+ Додати»: «Таблиця» (угоди, клієнти, завдання), «Назва», «Умова» і «Текст помилки». Коли умова справджується, дію заборонено, і людина бачить ваш текст. Приклад умови: `stage.name == 'Відправлено' and deliveries_count <= 0` — «Не можна відправити без ТТН». Нова валідація створюється вимкненою: перевірте її кнопкою «Перевірити умову» на номері запису й увімкніть галочкою. Колонка «Спрацювань» показує, скільки разів вона зупинила дію. Під формою — підказка з операторами (`==`, `and`, `or`, `not`) і функціями (`any`, `len`, `changed`).

## 5. Видалена інформація й очистка
Видалене в Helomi не зникає одразу: угоди, клієнти, завдання й товари 30 днів лежать у «Видаленій інформації» й повертаються з тими самими номерами. «Очистка інформації» масово переносить дані розділів туди ж — наприклад, після тестового періоду.

- «Система → Видалена інформація» — кошик на 30 днів: видалені угоди, клієнти (разом з угодами), завдання, товари. Відновлення повертає все з тими самими номерами; оплати повертаються в баланс гаманця, товари — без резерву і списання.
- «Система → Очистка інформації» — масово перенести дані в кошик (лише адміністратор, треба ввести слово ВИДАЛИТИ).

## 5а. Мова інтерфейсу
«Мій акаунт → Вигляд → Мова інтерфейсу»: українська, русский, English. Це особисте налаштування: кожен обирає свою мову, у колег інтерфейс лишається своїм. Після вибору підписи меню, кнопок, полів, підказок і повідомлень змінюються одразу (з російської на англійську й назад на українську сторінка один раз перезавантажується).
- Перекладаються підписи самого Helomi. Те, що написали люди, лишається як є: назви угод, товарів, клієнтів, етапів і
  власних полів, нотатки, повідомлення, тексти тригерів і шаблонів.
- Нове слово в інтерфейсі, якого ще нема в словнику, якийсь час показується українською — словники доповнюються з кожним оновленням.
- Мова зберігається в налаштуваннях людини (`view.lang`: `uk`, `ru`, `en`) і діє на всіх пристроях після входу.

## 5б. Вставка файлів і фото з буфера (Ctrl+V)
На комп'ютері файли й фото можна не шукати кнопкою «+ файл», а вставити: скопіюйте файл у провіднику (Ctrl+C), зробіть скріншот (Print Screen, «Ножиці») або «Копіювати зображення» в браузері → клацніть по блоку, куди треба (угода — «Файли», завдання, платіж, фото позиції прайс-листа чи товару, лого, вікно імпорту) → Ctrl+V. Файл потрапляє в найближче до місця кліку поле файлів, яке приймає такий тип (фото — у поле фото, .xlsx — в імпорт), і далі все як після вибору кнопкою.
- Можна вставляти й стоячи в полі коментаря поруч з файлами. Текст (зокрема клітинки з Excel) вставляється як текст, як завжди.
- У редакторі документа картинка вставляється в сам текст. Поле, що приймає один файл, бере перший.
- Якщо поруч кілька різних полів файлів і незрозуміло, куди, — клацніть ближче до потрібного блоку й повторіть Ctrl+V.

## 6. Хто що бачить
- Сторінку «Налаштування» відкриває адміністратор організації; адміністратор бачить і змінює все.
- Особисті пункти («Мій профіль», «Вигляд», «Push-сповіщення», «Гарячі клавіші»…) стосуються лише вас.
- Деякі сторінки показують дані всім, а змінювати дають лише адміністратору — наприклад, «Доступи» і «Переходи по етапах» («Розставити як у KeepinCRM»).
- ШІ-співробітникам «Налаштування CRM» закриті завжди.

## 7. Мій акаунт: особисті налаштування
Пункти групи «Мій акаунт» стосуються лише вас: колеги їх не бачать і не змінюють, а ваш вибір пам'ятається на всіх ваших пристроях.

### Мій профіль
Ваші дані, які бачать колеги в «Структурі», чатах і журналах: ім'я, фото, контакти й анкета «Про мене». Заповніть їх, щоб колеги й ШІ-співробітники знали, хто ви, що вмієте і як до вас звертатися.

Угорі — ім'я, телефон і фото; нижче — блок «Про мене» з полями з «Типи даних → Люди» (про себе, освіта, стаж, де працювали, навички, мови й свої поля компанії) і пігулкою «заповнено N з M». Поля з позначкою «лише вам» колеги не бачать. «Зберегти» вгорі записує все разом; обов'язкове порожнє поле не пропуститься. Докладно — стаття [Люди: картки й анкети](people.md).

### Вигляд
Як Helomi виглядає саме для вас: мова інтерфейсу, як відкривати угоди (список чи дошка), щільність таблиць і фон. Тут же «Пояснення на сторінках» — повернути картки «Для чого …», які ви згорнули або сховали (розділ 9).

### Робочий стіл
Стан роботи в реальному часі в межах ваших доступів: які показники видно, у якому порядку і за який період.

### Push-сповіщення
Сповіщення браузера про події, де ви відповідальний. Працюють, поки вкладка Helomi відкрита (навіть неактивна чи згорнута); кожну подію можна вимкнути окремо.

### Гарячі клавіші
Поєднання клавіш, щоб швидко створювати дані й переходити до блоків картки без миші. Тут видно весь список і вимикач.

### Вимкнення непотрібних блоків
Які блоки показувати в картках угоди, клієнта й товару. Вибір особистий: колеги бачать свої блоки, як і раніше; зміни видно одразу.

## 8. Система, компанія й інше
Пункти для адміністратора: параметри всієї компанії, стан сервера, з чого почати, підтримка й тариф, а також окремі перемикачі розділів.

### Загальні параметри
Назва акаунта, часовий пояс і ключ API — те, що стосується всієї компанії. Реквізити кожної компанії — нижче на цій сторінці й у «Бренди та юрособи».

### Сервер
Стан сервера простими словами: що треба зробити, ресурси, сервіси, база, резервні копії й безпека. Пункт є лише в окремій установці; на платформі за сервер відповідає консоль платформи.

### З чого почати?
Першочергові налаштування CRM із поточним станом кожного: що вже зроблено, а що ще ні — щоб нова компанія запрацювала без пропусків.

### Підтримка
Питання, помилки й пропозиції щодо роботи Helomi — зверненням: на кожну тему окреме, зі скриншотом. Відповідь приходить сюди ж.

### Тариф і оплата
Підписка Helomi вашої компанії: тариф, рахунки й оплати. Пункт видно в режимі кількох організацій.

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

### Користувацькі фільтри
Додаткові поля, за якими можна фільтрувати списки: рядок, текст, список, мультивибір, дата, число, прапорець.

### Система лояльності
Правило бонусів для кожної компанії. Поки що воно лише зберігається як налаштування — нарахування в угодах з'явиться пізніше.

## 9. Підказки й пояснення на сторінках
Helomi пояснює себе сам, але не заважає: у щоденних розділах підказки тихі, у налаштуваннях — помітні, і з кожної сторінки є дорога в цю WIKI.

- **Налаштування, інтеграції, пульти агентів** — угорі сторінки картка «Для чого …»: абзац зі статті WIKI, кроки й «Як це працює — інструкція у WIKI». «Згорнути» лишає пігулку «? Для чого …», «Більше не показувати» прибирає картку на всіх ваших пристроях. Під кожним перемикачем — рядок, що станеться, якщо його ввімкнути; перед небезпечним — жовта пастельна картка.
- **Угоди, клієнти, завдання, склад, фінанси** — нічого зайвого на екрані: кружечок «?» біля назви розділу чи блоку відкриває кілька речень і «Докладніше у WIKI» (стаття відкривається шторкою на потрібному розділі); під курсором кнопка показує білу пігулку з назвою дії й клавішею; рядок під полем у формі з'являється, коли поле у фокусі.
- **Підказка поля** — те, що ви пишете в «Типи даних → Підказка» (стаття «Типи даних і поля»). Її бачать усі, хто заповнює форму, і ШІ-співробітники в описі розділу.
- **«⋮» кожного розділу** — «Інструкція (WIKI)», «Вхід для ШІ», а коли пояснення сховане — «Показати пояснення». Усі сховані пояснення одразу повертає «Мій акаунт → Вигляд → Пояснення на сторінках».
- **На телефоні** наведення нема: підказки під полями видно завжди, картка «Для чого …» згорнута в пігулку, а «?» відкривають шторку знизу.
- **Ломі** бачить ті самі підказки відкритої сторінки: на «що робить ця галочка?» вона відповідає їхнім текстом.

## 10. Журнал змін
«Система → Журнал змін» показує, хто, коли і що змінив у налаштуваннях: етапи й воронки, поля «Типів даних», доступи людей, картки інтеграцій і служб доставки, налаштування складу, загальні параметри, ШІ-співробітників. Запис з'являється сам при кожному збереженні, його не можна виправити чи стерти. Де відомо «було → стало» (етап, воронка, поле, доступи, картка каналу чи перевізника, склад, загальні), видно саме різницю; де ні — що надіслали при збереженні. Ключі, токени й паролі в журнал не потрапляють.

1. Фільтри: «Розділ» (воронки й етапи, поля, доступи, довідники, фінанси, склад, інтеграції, служби доставки, ШІ…), «Хто» (люди й ШІ, які щось зберігали), пошук за назвою етапу, поля, картки чи людини.
2. У колонці «Зміни» для відомих «було → стало» старе закреслено, нове виділено. Для решти збережень — тіло запиту без таємниць (довгі тексти й фото замінено довжиною).
3. Автор — людина з токена або ШІ-співробітник; записи серверних заявок підписано «сервер (заявка …)».
4. Для ШІ: той самий `GET /api/crm/settings/changes` (параметри `area`, `actor_id`, `q`, `page`), але «Налаштування CRM» для ШІ закриті (ПРАВИЛА §5) — читати журнал може лише людина з доступом «Налаштування CRM».
5. Зміни самих записів (угоди, клієнти, товари) — у журналі кожного запису, а не тут.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Немає доступу до розділу «Налаштування CRM»» | Немає прав на налаштування | Попросіть адміністратора |
| «Змінювати доступи може лише адміністратор.» | Сторінка доступів лише для адміністратора | Попросіть адміністратора |
| Пункту нема в меню | Пункт для режиму кількох організацій або адміністратора платформи | Перевірте, чи ввімкнено цей режим |
| Частина підписів українською при іншій мові | Це дані, які написали люди (назви, етапи, поля), або новий підпис, якого ще нема в словнику | Свої назви змініть у налаштуваннях; про пропущений підпис напишіть у підтримку |
| Власний текст валідації під час дії | Спрацювала ваша умова в «Валідації» | Виправте те, про що каже текст, або вимкніть валідацію |

## Для ШІ-співробітників
- Читати налаштування можна через `describe_section("<key>")`: поля з обов'язковістю, етапи, довідники.
- Змінювати налаштування організації ШІ не може — для цього нема інструментів і не буде. Свої розділи, агентів і розширення ШІ налаштовує лише з правами творця (стаття «ШІ-творець»).
- Помилку валідації чи заборони переходу переказуйте людині одним реченням — це її налаштування.
- Мова інтерфейсу людини — `GET /api/crm/me/prefs` → `view.lang`; відповідайте людині її мовою. Дані й API лишаються українськими.

## Додаткова інформація
- Пов'язані статті: [Типи даних і поля](settings-fields.md), [Воронки, етапи, переходи](settings-funnels.md), [Люди, ролі, доступи](settings-access.md), [Тригери](settings-triggers.md), [Вебхуки](settings-webhooks.md), [Бренди і юрособи](settings-brands.md), [Довідники](settings-references.md), [Консоль платформи](platform.md).


---

# Типи даних і поля

«Типи даних» — місце, де ви самі вирішуєте, з яких полів складаються клієнт, угода, товар, завдання, додатковий контакт і операція «Фінансів»: які поля є, які обов'язкові, що видно в списку, у формі створення й у картці, і в якому порядку. Змінили тут — і одразу бачите це в розділі, на телефоні, в імпорті та в тому, що читає ШІ, без жодної правки коду.

## Можливості
- Одна таблиця на тип: вбудовані поля (ID, назва, телефон, етап…) разом із вашими власними.
- Власні поля восьми типів: «Рядок», «Цифри», «Дата», «Час», «Так/Ні», «Список», «Гіперпосилання», «Текст»; для «Рядка» і «Списку» — мультивибір.
- «Текст» — для довгих записів (умови, інструкції, коментарі): у картці показується з абзацами й «Розгорнути», редагується шторкою збоку з підказкою поля; у формах поле росте разом із текстом.
- «Обов'язкове поле» діє насправді: без значення запис не збережеться ні вручну, ні через API, ні у ШІ.
- «Вивести в списку», «Вивести при створенні», для угод — «Вивести в угоді», для товарів — «Вивести в угоді» і «Вивести в накладних».
- Порядок перетягуванням, блоки картки з перейменуванням.
- Поле угоди лише для вибраних воронок.
- Поле клієнта також у картці угоди й у завданні.
- Контроль унікальності, показ дублів, поле у фільтрі списку.

## 1. Налаштування
Дорога: «Налаштування → Типи даних» і тип: «Клієнти», «Угоди», «Товари», «Завдання», «Дод. контакти», «Фінанси» (поля операції: «Вивести при створенні» — шторка «Новий платіж», «Вивести в списку» — колонка журналу; стаття «Фінанси», розділ 1б). Поля власних розділів — «Налаштування → Типи даних → Власні розділи» (стаття «Власні розділи»).

Швидкий шлях із самого розділу: «⋮ → Налаштувати поля» у «Клієнтах», «Угодах», «Завданнях», «Товарах» і у власних розділах; у картці угоди — «⋮ → Налаштувати поля угоди». Пункт видно адміністратору.

На сторінці типу — пошук полів, таблиця з колонками «Увімкнено», «Назва», «Тип поля», «Обов'язкове поле», «Вивести в списку», «Вивести при створенні», «Блок», «ID» і «⋮» поля, внизу — сторінки, «Рядків на сторінці» (25 / 50 / 100) і «Всього». У «Завданнях» над полями ще таблиця «Типи завдань» (стаття «Довідники»).

Змінювати поля може людина з доступом до налаштувань (адміністратор або з галочкою «Налаштування CRM»).

## 2. Додати своє поле
1. Натисніть «Додати» під таблицею або «⋮ → Додати поле» вгорі.
2. У шторці «Користувацьке поле» заповніть «Назва *», «Тип поля *», «Блок *» (або «+ Новий блок…»).
3. Для «Списку» введіть «Варіанти списку *» по одному, кожен — клавішею Enter.
4. За потреби задайте «Значення за замовчуванням» — воно підставиться в новий запис.
5. Для полів клієнта є «Також відображати у розділах»: «Угоди» (внизу «Даних угоди» блоком «Поля клієнта» і колонкою в списку угод) і «Завдання» (у шторці завдання, у блоці про клієнта).
6. Поставте потрібні прапорці (розділ 3) і натисніть «Зберегти».

Ключ поля (латиницею) створюється з назви сам і видно в колонці «ID»; нове поле угоди одразу стоїть у картці.

## 3. Прапорці: обов'язкове, у списку, при створенні, в угоді
| Прапорець | Що робить |
| --- | --- |
| «Обов'язкове поле» | Без значення запис не створиться; наявне значення не можна стерти |
| «Вивести в списку» | Колонка в таблиці розділу |
| «Вивести при створенні» | Поле у шторці нового запису («Нова угода», «Новий клієнт»…) |
| «Вивести в угоді» (угоди) | Рядок у «Даних угоди» картки, на місці за порядком таблиці |
| «Вивести в угоді» (товари) | Колонка у вікні «Додати товар зі складу» |
| «Вивести в накладних» (товари) | Зберігається для шаблонів документів |
| «Видно колегам» (люди) | Поле в картці людини в «Структурі»; без галочки — лише сама людина й адміністратор (стаття [Люди: картки й анкети](people.md)) |
| «Додати у фільтр» | Фільтр за цим полем у списку розділу |
| «Дозволити мультивибір» | Кілька значень для «Рядка» або кілька варіантів для «Списку» |

Прапорці в рядку таблиці зберігаються одразу після кліку. Якщо поле приховане при створенні, обов'язковість при створенні не вимагається.

## 3а. Підказка поля
Підказка — одне речення під полем у формі створення: що станеться або звідки значення («Без клієнта угоду не збережуть. Новий створиться сам.»). Її бачать усі, хто заповнює форму, і ШІ-співробітники в описі розділу, тому людина й ШІ заповнюють поле однаково.

- Колонка «Підказка (бачать люди і ШІ)» — клацніть по тексту в рядку поля, напишіть і натисніть Enter (Esc — скасувати). До 300 знаків.
- У вбудованих полів (ID, Назва, Телефон, Клієнт…) уже є типова підказка; її можна змінити або стерти, а кнопка «Типова» повертає її.
- У шторці власного поля — поле «Підказка» під назвою.
- У формах розділів (угода, клієнт, контакт, завдання, товар, платіж, запис власного розділу) підказка з'являється під полем, коли воно у фокусі або під курсором; на телефоні — завжди. Порожня підказка — рядка нема.
- Пишіть наслідок, а не повтор назви: не «Телефон клієнта», а «За номером шукаються клієнт, дублі й переписки».

## 4. Порядок і блоки
- Тягніть рядок за «↕» — порядок спільний для вбудованих і власних полів і однаковий у списку, формі створення й картці. Під час пошуку перетягування вимкнене.
- «⋮ → Перейменувати блок…» вгорі сторінки змінює назву блоку картки для всіх його полів.

## 5. Системні поля із замком
Вбудовані поля мають позначку «системне». Їх не можна видалити чи змінити тип; прапорці, без яких запис не існує (наприклад «Увімкнено» в ID, назви, клієнта, етапу, воронки угоди), заблоковані й сірі. Прочерк «—» означає, що для цього поля прояву нема (наприклад, колонки в шторці). Решту прапорців вбудованих полів можна вмикати й вимикати, а рядки — переставляти.

## 6. Поле лише для окремих воронок
Для угоди, коли воронок більше однієї, у шторці поля є «Воронки продажів»: «Усі воронки» (і ті, що з'являться згодом) або «Лише вибрані». Картка й «Нова угода» показують поле тільки у вибраних воронках; у таблиці це видно в колонці «Воронка продажів». Імпорт і ШІ можуть записати таке поле в будь-яку угоду.

## 7. Унікальність і дублі
- «Контроль унікальності» — те саме значення в іншого запису не збережеться. Якщо дублі вже є, система попередить і запропонує ввімкнути все одно.
- «Відобразити дублі» — у «⋮» поля з'явиться «Показати дублі»: список повторюваних значень із номерами записів.

## 8. Вимкнути або видалити поле
- Зніміть «Увімкнено» — поле зникне з карток, списків і фільтрів, значення збережуться.
- «⋮ → Видалити» прибирає поле разом з усіма значеннями після підтвердження; дані не відновити. Поля, що прийшли з імпорту KeepinCRM, лише вимикаються.
- Зміна типу не перетворює старі значення: вони лишаються текстом і можуть показуватися некоректно.

На телефоні рядок таблиці стає карткою: назва з «↕» і «⋮», під нею тип, блок і ID, далі пігулки прапорців.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Потрібна назва поля» | Порожня «Назва» | Впишіть назву |
| «Для списку потрібні варіанти: введіть варіант і натисніть Enter» | Тип «Список» без варіантів | Додайте хоча б один варіант |
| «Поле «…» у цій сутності вже є» | Така назва вже зайнята | Дайте іншу назву |
| «Увімкнути унікальність не можна: є N повторюваних значень…» | Дублі вже є | «Показати дублі», виправте або підтвердіть примусово |
| «Системне поле (з імпорту) не видаляється — лише архівується» | Поле прийшло з KeepinCRM | Зніміть «Увімкнено» |
| «Виберіть хоча б одну воронку або «Усі воронки»» | «Лише вибрані» без жодної воронки | Позначте воронку |
| «Заповніть обов'язкове поле «…»» (у розділі) | Поле позначено обов'язковим | Заповніть його або зніміть прапорець тут |

## Для ШІ-співробітників
- Поля кожного розділу з прапорцями й варіантами — `describe_section("<key>")` (`deals`, `clients`, `tasks`, `products`, slug власного розділу). Обов'язкові поля діють для ШІ так само, як для людини: запис без них повертає помилку з назвою поля.
- Власні поля в запитах передаються в об'єкті `custom` за ключем поля.
- У кожного поля в `describe_section` є `hint` — та сама підказка, що людина бачить під полем: заповнюйте поле так, як вона каже.
- Змінювати поля вбудованих розділів і розділів людей ШІ не може: «Налаштування CRM» для ШІ закриті завжди. З правом творця «Свої розділи» ШІ читає поля будь-якого розділу (`fields_list`) і змінює лише поля своїх розділів (`fields_create`, `fields_update`, `fields_builtin_update`, `fields_delete` — видалення чекає підтвердження людини). Докладно — стаття «ШІ-творець».

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Клієнти](clients.md), [Завдання](tasks.md), [Склад і товари](products.md), [Воронки, етапи, переходи](settings-funnels.md), [Власні розділи](custom-sections.md), [Налаштування: огляд](settings.md).
- Тип «Формула» є в коді для полів товарів (варіант Prom), але в шторці його вибрати не можна.


---

# Воронки, етапи, переходи

Воронка — шлях угоди від створення до закриття, розбитий на етапи: «Створено», «Відправлено», «Виграно» тощо. Тут ви самі задаєте воронки, етапи з кольорами й ролями, що робити зі складом і оплатою, коли угода приходить на етап, хто бачить воронку і між якими етапами можна переходити.

## Можливості
- Кілька воронок, у кожній свої етапи з кольором, роллю і порядком перетягуванням.
- Склад за етапом: «списати зі складу» або «повернути на склад» товари угоди.
- «Автоплатіж»: несплачена сума угоди проводиться доходом у вибраний гаманець.
- Завдання, що створюється само, коли угода приходить на етап.
- Автодії: змінити відповідального, перенести або скопіювати угоду в іншу воронку, перенести в архів.
- Причини виграшу й програшу для закриття угоди.
- Доступ до воронки: усі користувачі або лише вибрані.
- Матриця дозволених переходів між етапами і терміни перебування на етапі.

## 1. Налаштування
Усе — у «Налаштування → Продажі»:
- «Воронки й етапи» — воронки, етапи, причини, доступ, автодії;
- «Переходи по етапах» — які переходи дозволені;
- «Терміни по замовленнях в етапах» — скільки угода може стояти на етапі.

Поля угоди, які видно лише в певних воронках, налаштовуються в «Типи даних → Угоди» (стаття «Типи даних і поля»).

## 2. Створити воронку
1. «Налаштування → Продажі → Воронки й етапи» → «+ Воронка».
2. Введіть назву. Воронка з'явиться одразу з чотирма етапами: «Створено», «Відправлено», «Виграно», «Скасована».
3. Перейменуйте, додайте чи переставте етапи під свій процес.

Біля назви воронки видно «N угод · M етапів». Якщо в воронці бракує етапу з роллю «Створено», «Відправлено», «Виграно» або «Скасована», під назвою з'явиться підказка: за цими ролями працюють ШІ-агенти (наприклад, ставлять «Відправлено» після ТТН). Галочка «архівні» вгорі показує архівні воронки й етапи.

## 3. Етапи: колір, роль, склад, автоплатіж
Кожен етап — рядок із колонками:
- «⋮⋮» — перетягніть, щоб змінити порядок;
- «Колір» — кольоровий кружечок; «Назва» — олівець перейменовує;
- «Роль» — що етап означає для системи: «Створено», «Прийнято», «Передали на збірку», «Зібрано», «Відправлено», «Виграно», «Скасована», «Допомога», «Повернення»;
- «Склад» — «нічого», «списати зі складу» або «повернути на склад». Поки не вибрали вручну, діє роль: «Відправлено» і «Виграно» списують, «Скасована» і «Повернення» повертають. Якщо повернені посилки перевіряє склад («Склад → Повернення»), поставте етапу «Повернення» «нічого»: товар повернеться кнопкою «Повернути на склад» після перевірки, а не тоді, коли служба написала «відмова» і посилка ще їде назад (23.10: так налаштовано в Helomi);
- «Автоплатіж» — «нічого» або гаманець: коли угода потрапляє на етап, несплачена сума проводиться доходом у цей гаманець;
- «Початковий» — етап, на який стає нова угода (один у воронці);
- «Угод» — скільки угод зараз на етапі.

Новий етап: внизу воронки — «Новий етап», «роль…», колір → «+ Етап».

## 4. Завдання й автодії етапу
- «завдання» в рядку етапу — завдання створюється само, коли угода приходить на етап: тип, «Назва завдання», «термін через N год», відповідальний («відповідальний угоди» або «хто перевів угоду»), коментар → «Зберегти». «вимкнути» прибирає цю дію.
- «автодії» — «Коли угода потрапляє на етап «…»»: «Змінити відповідального на», «Перенести або скопіювати» (воронка → етап), «Перенести в архів» → «Зберегти автодії». Біля назви етапу з'явиться короткий підсумок «↪ …».

Автодії діють для будь-якої зміни етапу: картка, канбан, масові дії, ШІ. Ланцюжок автопереходів не довший за 3 кроки. Копія угоди — нова угода з тим самим клієнтом, товарами й додатковими полями; оплати, ТТН, нотатки й задачі не копіюються.

## 5. Причини виграшу й програшу, доступ до воронки
Натисніть «причини й доступ» біля назви воронки:
- «Причини виграшу» і «Причини програшу» — «Нова причина» → «Додати», стрілки ↑ ↓, перейменувати, × видалити; зберігається одразу. Ці списки бачить людина у вікні «Виграно» / «Програно» в угоді. Без причин угоду можна закрити й так.
- «Хто має доступ» — «Усі користувачі CRM» або «Лише вибрані» з галочками людей. Без доступу воронки нема в перемикачі, фільтрах, канбані й «Новій угоді», а угода з неї не відкривається. Адміністратор бачить усе.

## 6. Переходи по етапах
Переходи по етапах — правила, з якого етапу на який можна перевести угоду, на яких етапах її можна створити й закрити. Так угода не перескочить збірку чи оплату — ні в людини, ні в ШІ-співробітника.

1. «Налаштування → Продажі → Переходи по етапах», угорі — вкладки воронок.
2. Таблиця: рядок — з якого етапу, стовпчик — на який. Галочка — перехід дозволено. Кожен клік зберігається одразу.
3. Окремі рядки під матрицею:
   - «Результат: Виграно» і «Результат: Програно» — з яких етапів угоду можна закрити з цим результатом;
   - «При створенні» — на яких етапах можна створити угоду;
   - «Заблокувати, якщо товар не списано» — перейти на етап лише після списання товарів угоди;
   - «Заблокувати, якщо товару нема в наявності» — лише коли всі товари є на складі.

Правила діють на зміну етапу людиною і ШІ-співробітником (картка, канбан, масові дії, інструменти ШІ — вони йдуть тим самим маршрутом); дзеркало KeepinCRM та імпорт їх не зупиняють. Підказку на сторінці виправлено 18.10 (SG_HINTS_V1).

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

## 7. Терміни на етапах
Скільки угода може стояти на етапі. Довше — вона виділяється червоним у списку й канбані, потрапляє у фільтр «Протерміновані», а відповідальному приходить push.

«Налаштування → Продажі → Терміни по замовленнях в етапах»: для кожного етапу — «Ліміт часу» й одиниця, далі «Зберегти». Угода, що стоїть довше, виділяється червоним у списку й канбані, потрапляє у фільтр «Протерміновані», а відповідальному приходить push.

## 8. Видалити або архівувати
- Воронку з угодами видалити не можна — система запропонує архівувати. Порожню — «видалити» разом з етапами.
- Етап з угодами: «видалити» запитає номер етапу, куди перенести угоди (перенесення пишеться в журнал кожної угоди); порожня відповідь — етап лише архівується.
- «архівувати» / «повернути» ховає й повертає воронку чи етап.

На телефоні рядки етапів стають картками з підписами полів.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Потрібна назва воронки» / «Потрібна назва етапу» | Порожня назва | Впишіть назву |
| «У воронці N угод — архівуйте її або перенесіть угоди в іншу воронку» | Спроба видалити воронку з угодами | Архівуйте воронку |
| «На етапі N угод — архівуйте етап або перенесіть угоди на інший» | Спроба видалити етап з угодами | Перенесіть угоди при видаленні або архівуйте |
| «Автодія: етап призначення збігається з цим етапом» | Автодія веде на той самий етап | Виберіть інший етап |
| «Перехід з етапу «…» на «…» заборонено налаштуваннями» (в угоді) | Немає галочки в «Переходах по етапах» | Поставте галочку або перейдіть через дозволений етап |
| «На етап «…» можна лише після списання товару зі складу» (в угоді) | Рядок «Заблокувати, якщо товар не списано» | Спишіть товар або зніміть галочку |

## Для ШІ-співробітників
- Воронки з етапами, ролями й причинами — `deals_refs`; перевести угоду — `deals_change_stage` (перевіряє дозволені переходи й «лише після списання»), закрити — `deals_close` з причиною зі списку воронки.
- Не вигадувати id воронок і етапів — брати з `deals_refs`. Помилку переходу переказати людині одним реченням.
- Змінювати воронки, етапи, переходи й автодії ШІ не може: «Налаштування CRM» для ШІ закриті. Етапи своїх власних розділів ШІ з правом творця задає інструментами `sections_create` / `sections_update` (стаття «ШІ-творець»).

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Типи даних і поля](settings-fields.md), [Склад і товари](products.md), [Тригери](settings-triggers.md), [Налаштування: огляд](settings.md).


---

# Люди, ролі, доступи

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

## Можливості
- Підтвердження нових людей, посада, відділ, керівник, права адміністратора.
- Розділи меню галочками — у картці людини або однією матрицею на всіх.
- Готові ролі: «Власник», «Менеджер», «Комірник», «Бухгалтер».
- Доступи CRM: «Бачить тільки своє», блокування видалення, редагування лише своїх угод, приховані телефони й email.
- Доступ до брендів (компаній), воронок, фінансів, завдань.
- Філії й команди, масова передача клієнтів, угод і завдань.

## 1. Налаштування
Усе — у «Налаштування»:
- «Команда → Користувачі» — люди, підтвердження, картка людини;
- «Доступи → Розділи меню» — матриця «розділ × людина»;
- «Доступи → Ролі» — готові набори розділів;
- «Доступи → Доступи» — права всередині CRM;
- «Команда → Філії», «Команда → Команди», «Команда → Відділи».

Адміністратор завжди бачить і може все — щоб не заблокувати себе. Змінювати доступи може лише адміністратор.

## 2. Підтвердити нову людину
1. Нова людина реєструється сама на сторінці входу.
2. Адміністратор відкриває «Команда → Користувачі»: угорі блок «Чекають підтвердження · N».
3. «Підтвердити» — людина зможе входити й працювати; «змінити» — відкрити картку; «видалити» — прибрати заявку.

Поки людину не підтверджено, їй не відкрито жодного розділу. Запрошення поштою поки нема.

## 3. Картка людини
«змінити» в рядку відкриває шторку: «Прізвище», «Ім'я», «Телефон», «Пошта», «Новий пароль» (порожньо — без змін), «Посада», «Відділ», «Керівник» (для «Структури»), галочки «Підтверджений», «Адміністратор» (останнього адміністратора зняти не можна), «Усі компанії» або вибрані компанії, і нижче — «Розділи меню» групами «Helomi», «ШІ-агенти», «Склад», «CRM». Галочки розділів зберігаються одразу, решта — «Зберегти». «Видалити користувача» — повідомлення людини лишаються, автор знеособлюється.

Під основними полями шторки — блок «Анкета» з полями з «Типи даних → Люди»: «Зберегти» записує лише змінені поля анкети, тож незаповнене людиною обов'язкове поле не заважає змінити посаду. Колонка «Анкета» в таблиці показує, скільки людина заповнила; поля з «Вивести в списку» — окремими колонками; пошук шукає й по анкеті («польська», «Excel»). «Налаштувати поля» вгорі веде в «Типи даних → Люди». Докладно — стаття [Люди: картки й анкети](people.md).

Колонка «Користувач KeepinCRM» прив'язує людину до користувача зі старої CRM, щоб імпортовані угоди мали правильного відповідального.

## 4. Розділи меню галочками
Які розділи меню відкриті кожній людині — однією таблицею для всіх: рядок — розділ, стовпчик — людина. Закритого розділу людина не бачить у меню, а сервер не віддає його даних ні їй, ні ШІ з її правами.

«Доступи → Розділи меню» — та сама галочка, що в картці, але для всіх одразу: рядок — розділ, стовпчик — людина. Частина розділів відкрита типово (Угоди, Клієнти, Завдання, Документи, Склад, Доставки…), частина закрита, поки її не відкрити:
- «Інтеграції», «Налаштування CRM», «Фінанси» (журнал операцій, гаманці, звіти, банки), «Дашборд фінансів» (аналітика й звіти Марії Йосипівни), «Дашборд директора», «Каса» — з 20.10 «Фінанси» і «Дашборд фінансів» відкриваються окремими галочками; хто мав старий доступ «Фінанси» до 20.10, отримав обидві, доки адміністратор не змінить їх окремо;
- «Склад: закриття накладних», «Склад: завершення інвентаризацій», «Склад: накладні переміщення», «Склад: Ревізії».

Окремими галочками налаштовуються «Документи: редагування створених», «Фінанси: проводити й змінювати платежі», «Завдання: усі, не лише свої», «Завдання: масові дії». Кожен власний розділ має свою галочку з його назвою.

Галочка закриває розділ людині повністю: пункту немає в меню, і сторінка не відкривається за адресою. Галочки є для кожного пункту лівого меню, крім «Профіль», «Швидкий доступ», «Моє меню» (вони потрібні всім) і «Налаштування» (лише адміністратор). «Склад: Товари (пункт меню)» прибирає пункт «Товари». Саму сторінку товарів відкриває галочка «Склад». «Доставка» (усі ТТН з угод) відкрита типово.

Сховати зайве лише зі свого меню кожен може сам, без адміністратора: «Налаштування» → «Моє меню» (стаття [Моє меню](my-menu.md)).

## 5. Ролі — готові набори розділів
Роль — готовий набір розділів для типової посади, щоб не ставити галочки по одній: «Застосувати» вмикає людині розділи ролі, а її інші галочки лишаються.

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

## 6. Доступи всередині CRM: своє / чуже, видалення, телефони
Що людина може всередині відкритих їй розділів: бачити всі угоди й клієнтів чи лише свої, видаляти, бачити телефони, проводити платежі. Адміністратор завжди бачить і може все; ШІ-співробітник отримує права свого профілю.

«Доступи → Доступи» — матриця прав для всіх, крім адміністраторів:
| Доступ | Що робить |
| --- | --- |
| «Філія» | людина бачить лише свою філію |
| «Бачить тільки своє» | угоди, клієнти й завдання — лише ті, де людина відповідальна (або її команда) |
| «Блокування видалення» | не може видаляти те, де вона не головний відповідальний |
| «Повне блокування видалення» | не може видаляти нічого |
| «Показати дані всіх філій» | без галочки людина з філією бачить лише свою (головний офіс бачить усе) |
| «Редагування тільки своїх угод» | чужі угоди — лише перегляд, нотатки й завдання |
| «Дозволити видалення проведених платежів» | у фінансах і в угоді (типово дозволено) |
| «Показати телефони клієнтів», «Показати email клієнтів» | без галочки вони приховані в списку й картці (типово показано) |

## 7. Бренди, воронки, фінанси, завдання
- **Бренди (компанії):** у картці людини — «Усі компанії» або вибрані. Щоб людина бачила угоди лише своїх брендів, увімкніть «Налаштування → Продажі → Угоди: загальні → Доступ до угод за брендами людини» (типово вимкнено).
- **Воронки:** «Воронки й етапи → причини й доступ → Хто має доступ» (стаття «Воронки, етапи, переходи»).
- **Фінанси:** розділ «Фінанси» відкриває перегляд; без «Фінанси: проводити й змінювати платежі» нові платежі, зміни, перекази й імпорт заборонені.
- **Завдання:** без «Завдання: усі, не лише свої» у розділі видно лише свої (де людина відповідальна або автор).

## 8. Філії й команди
Філія — офіс, магазин чи склад: людина з філією бачить лише свою, головний офіс — усе. Команда — група людей, у якій «всі бачать усе» або «керівник бачить усе, команда — своє».

- «Команда → Філії» — офіси, магазини, склади: назва, адреса, «головний офіс». Людині філію ставлять у «Доступах».
- «Команда → Команди» — «+ Команда»: учасники, керівники й режим «усі бачать усе» або «керівник бачить усе, команда — своє». Працює разом із «Бачить тільки своє».
- «Команда → Відділи» — структура компанії для сторінки «Структура».

## 9. Передати справи іншій людині
Внизу «Команда → Користувачі» — «Масова передача даних»: від кого, кому → «Порахувати» → «Передати». Клієнти, угоди й завдання переходять іншій людині (звільнення, відпустка).

## 10. Кілька організацій
Якщо ви працюєте в кількох компаніях з однією поштою, «Налаштування → Мій акаунт → Мої організації» показує їх із роллю й станом; перехід відкриває Helomi уже в іншій організації. Дані, налаштування, ключі й ШІ-співробітники в кожної свої. Пункт видно, коли сервер працює в режимі кількох організацій.

На телефоні матриці гортаються вбік, картка людини відкривається на весь екран.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Немає доступу до розділу «…»» | Галочку розділу не поставлено | Адміністратор відкриває розділ у «Розділах меню» |
| «Змінювати доступи може лише адміністратор.» | Ви не адміністратор | Попросіть адміністратора |
| «Видаляти … заборонено вашими доступами» | «Повне блокування видалення» | Попросіть адміністратора або видалить відповідальний |
| «Видаляти …, де ви не головний відповідальний, заборонено вашими доступами» | «Блокування видалення» | Передайте запис відповідальному |
| «Видаляти проведені платежі заборонено вашими доступами» | Знято «Дозволити видалення проведених платежів» | Попросіть адміністратора |
| «Тариф «…» дозволяє до N …» | Ліміт тарифу платформи | Зверніться до адміністратора платформи |

## Для ШІ-співробітників
- ШІ-співробітник — такий самий користувач: його розділи, бренди, «спочатку запитати» і ліміти задаються в пульті, вкладка «Доступи» (стаття «ШІ-співробітники»). «Налаштування CRM» для ШІ закриті завжди, навіть якщо галочку поставити.
- Інструменти ШІ бачать лише розділи, відкриті йому. Якщо інструмента нема — скажіть людині, що розділ треба відкрити в «Доступах» співробітника.
- Інструментів для керування людьми, ролями й доступами нема і не буде: це архітектура, її змінює лише людина.

## Додаткова інформація
- Пов'язані статті: [ШІ-співробітники](ai-employees.md), [Бренди і юрособи](settings-brands.md), [Воронки, етапи, переходи](settings-funnels.md), [Налаштування: огляд](settings.md), [Структура](structure.md).


---

# Бренди і юрособи

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

## Можливості
- Бренди з лого й папкою складу; юрособи з реквізитами, ПДВ, підписантом, лого, підписом і печаткою.
- Зв'язок «бренд ↔ юрособа» з типовою юрособою бренду.
- Правила «звідки угода → яка юрособа»: канал, джерело, бренд, воронка, папка складу, гаманець.
- Документи беруть реквізити з юрособи угоди й запам'ятовують їх.
- Гаманці й каси належать юрособі; профіль касира Checkbox — від юрособи.
- Доступ до угод за брендами людини; юрособа обов'язкова при закритті — за бажанням.
- Податки юрособи: які податки, ставка чи сума, період, день сплати — CRM сама ставить їх плановими операціями у «Фінансах».

## 1. Налаштування
- «Налаштування → Команда → Компанії та реквізити» — бренди («компанія тут — це бренд»).
- «Налаштування → Команда → Бренди та юрособи» — вкладки «Юрособи», «Бренди», «Правила».
- «Налаштування → Продажі → Угоди: загальні» — прапорці «Юрособа обов'язкова при закритті угоди» і «Доступ до угод за брендами людини».

## 2. Додати бренд
1. «Налаштування → Команда → Компанії та реквізити» → «+ Компанія».
2. Назва, «Завантажити лого», папка складу бренду → «Зберегти».

Реквізити, які раніше заповнювали тут, переносяться в юрособи самі: юрособа повторює зміни профілю, доки її не відредагували в «Бренди та юрособи».

## 3. Додати юрособу
1. «Бренди та юрособи» → вкладка «Юрособи» → «+ Юрособа».
2. Заповніть «Назва для документів *» (ФОП Прізвище Ім'я По батькові / ТОВ «Назва»), «Коротка назва», «Форма» (ФОП, ТОВ, Інше), «Платник ПДВ», «ІПН», «ЄДРПОУ», «IBAN» (UA і 27 цифр), «Банк», «Адреса», «Місто (для документів)», «Підписант (ПІБ)», «Телефон», «Email», «Профіль касира Checkbox».
3. Відмітьте бренди, гаманці й каси цієї юрособи; за потреби — «Типова юрособа організації» (коли ні правило, ні бренд юрособу не дали).
4. «Зберегти». Після збереження в блоці «Для документів» можна завантажити «Лого», «Підпис керівника» і «Печатка».

Таблиця юросіб: «Юрособа», «Форма», «Код», «IBAN», «Бренди», «Рахунки». Непотрібну — «В архів»; «Показати архівні» повертає її в список.

## 4. Які юрособи в бренду
Вкладка «Бренди» → бренд → шторка: галочки юросіб і перемикач «типова» — для угод без правила. Збережіть. Якщо в бренду юросіб нема, у таблиці написано «типова організації або за правилом».

У тій самій шторці — прапорець **«Не рахувати у звітах»**: бренд не наш бізнес (наприклад, чужий товар на нашому складі) — його продажі не показуються в «Бізнесах» Марії й звітах бізнесів. Бренд — це й **бізнес** у «Фінансах»: операції угод з товарами його кореневої папки складу отримують цей бізнес самі (стаття «Фінанси», розділ 1а).

## 5. Правила вибору юрособи
Вкладка «Правила» → «+ Правило»:
1. «Назва» (наприклад, «Сайт PocoPrint → ФОП Іваненко»).
2. «Якщо угода»: «Канал (картка «Інтеграцій»)», «Джерело», «Бренд», «Воронка», «Папка складу товару», «Гаманець платежу» — кожне «— будь-який —» або значення. Мають збігтися всі вибрані умови.
3. «То юрособа» → «Юрособа *», «Увімкнено» → «Зберегти».

Як угода отримує юрособу — по черзі: юрособа, обрана в картці угоди → перше правило згори, усі умови якого збіглися (порядок — перетягуванням) → типова юрособа бренду угоди → типова юрособа організації, або єдина, якщо вона одна.

Внизу — «Перевірити угоду»: введіть Id угоди → «Перевірити» покаже, яку юрособу вона отримає і чому.

## 6. Бренд і юрособа в угоді, документах, фінансах
- **Угода:** рядки «Бренд» і «Юрособа» в «Даних угоди» (поруч — як визначено, наприклад «за правилом»); юрособу можна змінити вручну. Бренд береться з картки каналу, філії або єдиного бренду. У списку угод — колонка й фільтр «Бренд».
- **Документи:** реквізити постачальника — з юрособи угоди, і документ запам'ятовує її, щоб реквізити не змінювались заднім числом. У шаблонах — `{{brand.name}}`, `{{brand.logo}}`, `{{company.vat}}`. Без юросіб усе працює, як раніше.
- **Фінанси:** гаманці належать юрособі; у «Новому платежі» гаманець підписано юрособою; є звіт «бренд × юрособа».
- **Каса:** каса належить юрособі; профіль касира Checkbox береться з юрособи, якщо в каси свого нема.

Прив'язати акаунт інтеграції (окремий Prom, касу, відправника Нової Пошти) до бренду чи юрособи в налаштуваннях поки не можна; канал можна вказати умовою правила.

## 7. Доступ за брендами і обов'язкова юрособа
- «Доступ до угод за брендами людини» — людина бачить угоди лише брендів своїх компаній («Користувачі → компанії») і угоди без бренду; адміністратори й люди «в усіх компаніях» бачать усе. Типово вимкнено.
- «Юрособа обов'язкова при закритті угоди» — «Виграно» не ставиться, доки угода не отримала юрособу (обрану, за правилом або типову). Типово вимкнено.

На телефоні таблиці стають картками, шторки відкриваються на весь екран.

## 8. Партнери бізнесу
«Налаштування → Бренди та юрособи → Бренди» → бренд → блок «Партнери бізнесу» (зміни зберігаються одразу):
1. «Ім'я нового партнера», частка прибутку в % → «+ Партнер». Сума часток активних партнерів — не більше 100 %.
2. «повертати собівартість» — партнер друкує чи купує товар зі своїх матеріалів: у виплату йде ще й собівартість його позицій.
3. «створити кишеню» — особистий гаманець «Кишеня · <ім'я>»: витрата з нього на бізнес рахується внеском партнера.
4. «Початок обліку бізнесу» — з цієї дати рахуються капітал і гроші бізнесу.
5. На товарі можна задати іншу частку, повернення собівартості чи «не у виплату»: картка товару → блок «Партнери».
Капітал і виплати — «Фінанси → Партнери» (стаття «Фінанси», розділ 7в) і пульт ШІ Свєти (стаття «ШІ Свєта»).

## 9. Податки юрособи
«Налаштування → Бренди та юрособи → Юрособи» → юрособа → блок «Податки» (з'являється після першого збереження юрособи):
1. «Вести податки» — увімкнути.
2. «Планувати з місяця», «Гаманець сплати» (порожньо — перший гаманець юрособи), «Що входить у базу» (класи доходів).
3. «+ Податок»: назва, «Відсоток від бази» зі ставкою або «Фіксована сума», місяць чи квартал, «до … числа», наступного місяця /
   через місяць / через два після періоду, категорія, «діє». «Зберегти податки» — нижче видно суми за минулий і поточний
   період і стан («планова», «сплачено»).
4. Планові податки з'являються у «Фінанси → Планові» (група «Податки») і щоночі перераховуються з доходів, поки їх не підтвердили.
Звіт і підтвердження — стаття «Фінанси», розділ 7ґ. Ставки беріть зі своєї системи оподаткування: CRM їх не підставляє.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «сума часток партнерів бізнесу — … %, більше 100 %» | Частки разом перевищують 100 % | Зменште частку когось із партнерів |
| «вкажіть ім'я партнера» | Порожнє ім'я | Впишіть ім'я |
| ««…»: відсоток має бути від 0 до 100» / «вкажіть суму» / «вкажіть назву» | Неповний рядок податку | Заповніть рядок або «прибрати» |
| «Податки можна налаштувати після збереження юрособи» | Нова юрособа ще не збережена | «Зберегти», потім відкрийте знову |
| «Потрібна назва юрособи («ФОП …» / «ТОВ …»)» | Порожня назва | Впишіть назву для документів |
| «IBAN: UA і 27 цифр» | Неповний або зайвий символ | Перевірте IBAN |
| «Правилу потрібна хоча б одна умова» | Усі умови «будь-який» | Виберіть хоча б одну умову |
| «Оберіть юрособу угоди: без неї угоду не можна закрити як «Виграно»…» | Увімкнено «Юрособа обов'язкова при закритті угоди» | Виберіть юрособу в картці або додайте правило |
| «Юрособу не визначено: додайте правило або типову юрособу» (у «Перевірити угоду») | Жодна ланка не дала юрособу | Додайте правило або типову |
| «Немає доступу до угод цього бренду» | Увімкнено доступ за брендами | Адміністратор додає людині компанію |

## Для ШІ-співробітників
- Бренд і юрособа угоди — звичайні поля `brand_id` і `legal_id`; варіанти — у `deals_refs` (бренди). Без явної юрособи угода отримає її за правилом.
- ШІ працює з брендами, відміченими в його «Доступах» (або з усіма, якщо там увімкнено «Працює з усіма компаніями й брендами»).
- Змінювати бренди, юрособи й правила ШІ не може — це налаштування компанії; податки юрособи теж налаштовує людина.
- Читати податки: `finance_taxes`, `finance_taxes_planned` (стаття «Фінанси»).

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Документи](documents.md), [Фінанси](finance.md), [Каса](cashbox.md), [Checkbox](int-checkbox.md), [Люди, ролі, доступи](settings-access.md).


---

# Довідники

Довідники — короткі списки, з яких люди вибирають значення в картках: джерела клієнтів і угод, теги, типи завдань, гаманці, категорії фінансів, валюти, сегменти, філії, одиниці виміру. Ви ведете їх самі в «Налаштуваннях»; перейменування одразу змінює назву в усіх записах, а значення, яке вже десь стоїть, не зникає безслідно — його лише архівують.

## Можливості
- Однакові таблиці: додати рядком унизу («+ Додати»), змінити кліком по значенню, порядок — перетягуванням «⋮⋮».
- Вжите значення лише архівується або вимикається, невжите — видаляється.
- Теги й філії, що вже є в картках, але не в довіднику, заносяться одним натиском.

## 1. Налаштування
| Довідник | Де |
| --- | --- |
| Джерела, Теги | «Налаштування → Продажі → Джерела», «… → Теги» |
| Типи завдань | «Налаштування → Типи даних → Завдання» (над полями завдань) |
| Гаманці, Валюти і курс, Сегменти, Категорії фінансів, Каси | «Налаштування → Фінанси → …» |
| Філії | «Налаштування → Команда → Філії» |
| Одиниці виміру, Категорії складу | «Налаштування → Склад і товари → …» |
| Статуси документів | «Налаштування → Документи → Шаблони і статуси» |

Змінювати довідники може людина з доступом до налаштувань (адміністратор або «Налаштування CRM»).

## 2. Джерела
Джерело — звідки прийшов клієнт чи угода: Prom, сайт, Instagram, дзвінок. За ним фільтрують списки й будують тригери, а колір стає бейджем у списках.

Колонки «Назва» і «Колір»: колір — бейдж джерела в списках клієнтів і угод. Натисніть кружечок кольору — відкриється палітра: шість тонів (сірий, червоний, бурштин, зелений, синій, фіолетовий), у кожного дев'ять відтінків від найсвітлішого до найтемнішого; підказка на кружечку називає колір («Синій, основний»), «Без кольору» прибирає його (22.10). Джерело, що вже стоїть у записах, лише архівується. Нижче — «Заборона зміни джерела»: для кожного джерела з його ID (потрібен для API й тригерів) галочки «Заборонити зміну в угоді з маркетплейсу» і «Заборонити зміну в угоді через API (сайт)».

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

«Новий тег» → «Додати». Колонки «Тег», «Колір», «Клієнтів», «Угод». «перейменувати» і «видалити» діють одразу в усіх записах (видалення прибирає тег з клієнтів і угод після підтвердження). Якщо в картках є теги, яких нема в довіднику, з'являється кнопка «Занести в довідник теги з карток (N)». Ставиться тег у картці клієнта чи угоди або масовою дією.

## 4. Типи завдань
Таблиця «Типи завдань»: назва й іконка (з фірмового набору або «Без іконки»). Тип підставляє назву нової задачі, а іконку видно на дошці, у списку й архіві. Тип, що стоїть у задачах, лише архівується. Нижче на тій самій сторінці — «Поля завдань» (стаття «Типи даних і поля»).

## 5. Гаманці, валюти, категорії, сегменти
Гаманці, валюти, категорії й сегменти — довідники «Фінансів»: куди лягають гроші, у якій валюті й за якою статтею.

- **«Гаманці»** — «Назва», «Валюта» (UAH, USD, EUR, PLN, GBP), «Увімкнено», «Баланс». Гаманець з операціями не видаляється — лише вимикається. Юрособу гаманця задають у «Бренди та юрособи».
- **«Валюти і курс»** — скільки гривень за 1 одиницю валюти; потрібен для переміщень між гаманцями різних валют і підсумку «разом у гривні».
- **«Категорії фінансів»** — дерево окремо для доходів і витрат: «Назва» і «Батьківська» («— корінь —»); підкатегорія успадковує вид батька. Категорію з операціями чи підкатегоріями не видалити.
- **«Сегменти»** — «+ Додати»: назва і гаманці, для яких сегмент підставляється в платіж сам. Перейменування сегмента змінює його в усіх операціях; фільтр «Сегмент» — у звітах «Фінансів».

### Валюти і курс
Курс — скільки гривень коштує 1 одиниця валюти. Він потрібен для переказів між гаманцями різних валют і для сум «разом у гривні».

### Сегменти
Сегмент — додатковий розріз фінансової статистики (напрям, магазин, проєкт). Він підставляється в платіж сам за вибраним гаманцем.

## 6. Каси
«Налаштування → Фінанси → Каси» → «+ Нова каса»: назва, «Філія», «Касир Checkbox» (необов'язково), «Касири». Касиру розділ «Каса» відкривається сам. У списку видно, чи підключено Checkbox. Як працювати з касою — стаття «Каса».

## 7. Філії, одиниці виміру, статуси документів
Одиниця виміру — у чому рахуються товар і його залишок (шт, кг, м, уп). Нову одиницю вводять просто в картці товару, і вона з'являється в цьому списку.

- **«Філії»** — офіси, магазини, склади: назва, адреса, головний офіс; «Занести філії з записів (N)». Людину до філії прив'язують у «Доступи → Доступи».
- **«Одиниці виміру»** — список у коді плюс ті, що вже є в товарах; нова одиниця вводиться в картці товару.
- **«Категорії складу»** — посилання на папки «Складу»: ведуться в самому розділі.
- **Статуси документів** — у «Шаблони і статуси» (стаття «Документи»).
- **«Система лояльності»** — правило бонусів для кожної компанії; поки лише зберігається як налаштування, нарахування в угодах з'явиться пізніше.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Потрібна назва типу» | Порожня назва типу завдання | Впишіть назву |
| Видалення не дозволено, пропонують архів або вимкнути | Значення вже стоїть у записах | Архівуйте чи вимкніть — історія збережеться |
| Кнопка «Додати» сіра | Порожня назва | Впишіть назву |

## Для ШІ-співробітників
- Значення довідників приходять у `deals_refs`, `clients_refs`, `tasks_refs` (джерела, теги, типи, відповідальні). Не вигадуйте id — беріть звідти.
- Змінювати довідники ШІ не може: це налаштування компанії.

## Додаткова інформація
- Пов'язані статті: [Налаштування: огляд](settings.md), [Фінанси](finance.md), [Каса](cashbox.md), [Завдання](tasks.md), [Документи](documents.md), [Бренди і юрособи](settings-brands.md).


---

# Правила передачі між розділами

Правила передачі роблять те, що інакше довелося б зашивати в код: поле одного розділу само потрапляє в поле іншого. Склад передає назву товару в «Назву Checkbox» прайс-листа, клієнт передає сегмент у свої угоди, угода дає назву своїм завданням. Налаштовує людина в «Налаштування → Автоматизація → Правила передачі», код тут не потрібен (ПРАВИЛА §2).

## З чого складається правило

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

Назву правила можна не писати, вона складеться сама: «Склад: Назва → Прайс-лист: Назва Checkbox».

## Як користуватися

1. «+ Нове правило» → оберіть джерело, призначення, зв'язок, коли й режим → «Додати правило». Правило одразу ввімкнене.
2. «Перевірити» у формі показує на конкретному записі джерела (ID або останній), які записи призначення зачепить і що в них стане.
3. «До наявних» у рядку правила проходить усі записи джерела один раз, щоб заповнити вже наявні довідники (наприклад, позиції прайсу, зв'язані зі складом раніше).
4. Перемикач у рядку вимикає правило без видалення. Лічильник «Разів» і остання помилка показують, чи воно працює.

Кожен запис, змінений правилом, отримує позначку в журналі картки від імені «правило передачі». Імпорт і дзеркало KeepinCRM правил не запускають, як і зміни, зроблені самим механізмом.

## Типове правило

При першому запуску створюється «Склад: Назва → Прайс-лист: Назва Checkbox» (режим «за джерелом», при зв'язці й при зміні): назва в фіскальному чеку одна на артикул, хоч би скільки оголошень із різними назвами було в прайсі. Його можна змінити або вимкнути, як будь-яке інше.

## Для ШІ-співробітників

Інструменти `transfer_rules_meta` (розділи, поля, зв'язки, режими), `transfer_rules_list`, `transfer_rules_create`, `transfer_rules_update`, `transfer_rules_delete`, `transfer_rules_check` (перевірка на записі), `transfer_rules_apply_all` (підтвердження). Ключі полів — як у `meta`: вбудовані — `title`, `comment`…, додаткові — `cf:<ключ>`.


---

# Тригери

Тригер — правило «коли в CRM сталося X, зробити Y»: замовлення з «Пром-оплатою» → заповнити «Тип оплати checkbox», угода «Отримано» → фіскальний чек, угода «Відправлено» → SMS клієнту, нова угода → завдання менеджеру. Тригери виконує сервер сам, без людини й без ШІ, а кожне спрацювання видно в журналі. Дії — як у KeepinCRM (розділ 3а).

## Можливості
- Сім таблиць даних: «Угоди», «Контрагенти», «Завдання», «Журнал операцій» (рух товару), «Фінанси», «Нотатки», «Доставка».
- Умова мовою KeepinCRM: `stage.name == 'Відправлено'`, `created_at`, `result == 'successful'`, `AND` / `OR`.
- Запуск відразу, через N хвилин або за датою з поля (до чи після неї).
- 22 дії як у KeepinCRM: заповнити й копіювати поля, перемістити етап чи між воронками, завершити угоду, головний відповідальний, авторозподілення, архів контрагента, створити платіж, фіскалізувати чек і повернути його, згенерувати документи, створити завдання, угоду чи ліда, запис у нотатку, SMS, Email, теги угоди й контрагента, сповіщення, Webhook.
- Webhook: URL, метод, заголовки, параметри, тіло зі змінними запису, у тому числі списком товарів.
- Відповідь сервісу можна записати в поле запису; відповідь і помилки — у журнал картки.
- 12 готових шаблонів: Viber через TurboSMS, SMS Club, AlphaSMS, Telegram, Хорошоп, Kasta та інші.
- Журнал спрацювань з повтором і скасуванням.

## 1. Налаштування
«Налаштування → Автоматизація → Тригери». Угорі — «З шаблону…» і «+ Новий тригер», нижче — один рядок фільтрів: пошук (назва, коментар, умова), таблиці з кількістю (лише ті, де є тригери), «Дія» і «Стан» (увімкнені, вимкнені, з помилкою останнього запуску) — випадними списками; «+ Новий тригер» бере дію з вибраного фільтра. Під назвою тригера — його коментар. У списку: перемикач «Увімкнено», «Назва», «Таблиця», «Умова», «Запуск», «Останнє спрацювання», «Разів», дії «Копія» і «Видалити».

Потрібен доступ «Налаштування CRM» (адміністратор). Ключі сторонніх сервісів не пишіть у тригер відкрито: їх тримають на сервері як `CRM_SECRET_<НАЗВА>` і вставляють змінною `{{secrets.НАЗВА}}` — у журналі вони приховані.

## 2. Створити тригер з шаблону
1. «З шаблону…» → виберіть, наприклад, «Сповіщення в Telegram: нова угода» або «Viber через TurboSMS».
2. Тригер створиться і відкриється шторка з уже заповненими URL, тілом і умовою; угорі — підказка шаблону й посилання на статтю.
3. Підставте свої дані (токен бота, номер чату, ключ) і натисніть «Зберегти».

Шаблони: «Viber через TurboSMS», «SMS через SMS Club», «SMS через AlphaSMS», «Сповіщення в Telegram: нова угода», «…: нове завдання», «…: новий лід/клієнт», «…: завдання прострочене», «Залишки на Хорошоп», «Синхронізація залишків з Kasta», «Інформація при русі товару», «Інформація з угод», «Інформація з розділу Фінанси».

**Тригери «Отримано» і «Скасовано» (15.10).** Готові, для всіх воронок: «Отримано» → фіскальний чек і «Завершити угоду: Виграно»; етап скасування (роль «lost») → «Завершити угоду: Програно» і повернення чека. Докладно — стаття «Фіскальні чеки», розділ «Автоматичний чек (тригер)». Один тригер на дію: умова за назвою чи роллю етапу діє в усіх воронках, тож окремий тригер на кожну воронку не потрібен.

## 3. Створити тригер вручну
1. «+ Новий тригер». У шторці «Новий тригер · Webhook»: «Назва», «Таблиця з даними», «Дія» — Webhook.
2. «URL», «Метод відправки» (GET, POST, PUT, PATCH, DELETE), «Успішний статус запиту» (порожньо — будь-який 2xx), «Content-Type».
3. «Заголовки запиту (Headers)», «Параметри запиту (Params)», «Тіло запиту (Body)». Змінні запису — у блоці «Змінні запису» під дією: клік по змінній вставляє її туди, де стоїть курсор. Список товарів угоди — `{{#jobs}}…{{^_last}},{{/_last}}{{/jobs}}`.
4. «Успішна відповідь (Response)» — `$.змінна відповіді` → поле запису («+ Додати»); наприклад, номер повідомлення з відповіді SMS-сервісу в поле угоди.
5. Галочка «Записувати відповідь у журнал картки (помилки записуються завжди)».
6. «Зберегти». Тригер з'явиться в списку; вмикається й вимикається перемикачем.

## 3а. Дії тригера
«Дія» в шторці тригера; поля дії — під нею. Тексти в полях дії — шаблони: `{{title}}`, `{{client.company}}`, `{{client.phone}}`, `{{credit_amount}}`, `{{custom_fields.<ключ>}}` (клік по змінній під умовою вставляє її, де курсор).

| Дія | Що робить | Поля |
| --- | --- | --- |
| Заповнити поля | записує значення в поля запису | «Поле запису ← значення», «Лише якщо поле порожнє» |
| Копіювати поля | переносить значення змінної в поле | «Звідки (змінна) → у поле» |
| Заповнити головного відповідального | ставить відповідального | працівник |
| Авторозподілення | відповідальний — той з обраних, у кого найменше угод у роботі | працівники |
| Перемістити етап | переводить угоду на етап (склад і автодії етапу — як за звичайної зміни) | воронка / етап |
| Перемістити між воронками | переносить або копіює угоду в іншу воронку | воронка / етап, «Перенести» чи «Скопіювати» |
| Завершити угоду | «Виграно» / «Програно» з причиною, угода в архів | результат, причина |
| Архів контрагента | контрагент запису — в архів | — |
| Створити платіж | платіж по угоді у гаманець | дохід / витрата, сума (типово `{{credit_amount}}`), гаманець, категорія, коментар |
| Фіскалізувати чек | фіскальний чек Checkbox по угоді (один на угоду) | каса, касир, зміна |
| Повернути фіскалізований чек | чек повернення по проведеному чеку продажу | — |
| Згенерувати документи | документи угоди / клієнта за шаблонами | шаблони, статус |
| Створити завдання | завдання по угоді чи клієнту | назва, опис, виконавець (типово відповідальний), термін через N хвилин, тип |
| Створити угоду | нова угода клієнта запису | воронка / етап, назва, коментар, «Скопіювати товари» |
| Створити ліда | новий лід | назва / ПІБ, телефон, коментар |
| Запис в нотатку | нотатка в картці | текст |
| Відправити SMS | SMS через інтеграцію «SMS (TurboSMS)» на телефон угоди | акаунт TurboSMS (коли кілька), SMS-шаблон з картки або свій текст, підпис відправника, телефон (порожньо — з доставки чи клієнта) |
| Відправити Email | лист з підключеної поштової скриньки | скринька, кому (типово `{{client.email}}`), тема, текст |
| Тегування / Тегування контрагента | додає або прибирає теги | «Додати», «Прибрати» (через кому) |
| Сповіщення | сповіщення працівникам у Helomi і пуш | кому, «та відповідальному», заголовок, текст |
| Webhook | запит в інший сервіс | розділ 3 |

Приклад як у KeepinCRM: «Заповнити поля», умова `custom_fields.prom_payment_type == 'Пром-оплата'`, поле «Тип оплати checkbox» ← `Rozetkapay`, «Лише якщо поле порожнє». Так налаштовано всі правила «Тип оплати checkbox» (Prom, Rozetka, OLX, Kasta, Епіцентр, сайти, «Спосіб оплати») — їх можна змінювати тут, у тригерах.

Результат дії пишеться в «Журнал спрацювань» і нотаткою в картку (помилка — завжди). Зміни, зроблені тригером, інших тригерів не запускають.

## 4. Умова виконання
Угорі шторки — «Назва» і **«Коментар»**: для чого цей тригер (наприклад «накладений OLX — у чек як UAPay»); його видно під назвою в списку, за ним шукає пошук. Далі кожен крок — окрема картка; внизу — «Додатково» (записувати результат у картку), «Змінні запису» і «Перевірити на записі». Шторка тригера — три кроки: **1 Коли** (таблиця і запуск), **2 Якщо** (умова), **3 Що зробити** (дія та її поля). У кроці «Якщо» умова складається рядками «поле · як · значення» без формул:
- поле — зі списку (етап, воронка, сума, відповідальний, клієнт, додаткові поля запису…);
- як — «дорівнює», «не дорівнює», «містить», «більше», «менше», «не менше», «не більше», «порожнє», «заповнене»;
- значення — текст або число; для етапу, воронки, відповідального й результату є підказки зі списку;
- «Лише для нового запису (щойно створеного)» — тригер діє лише при створенні;
- кілька рядків — «Усі умови» (і) або «Будь-яка з умов» (або); «+ Умова» додає рядок, «×» прибирає.

Приклад власника: «Дод. поле: Тип оплати OLX» · «містить» · «доставк» → «Заповнити поля»: «Тип оплати checkbox» ← UAPay. Кнопка «Формулою» праворуч показує ту саму умову мовою KeepinCRM; складні умови (`any(…)`, дужки, змішані «і» та «або») пишуться лише формулою — шторка відкриває їх одразу у формулі, «Простими умовами» повертає рядки, коли це можливо. Змінні запису для текстів дій — у згорнутому блоці «Змінні запису» під дією.

Тригер спрацьовує, коли умова **стала** істинною після зміни запису; для нового запису — коли вона істинна одразу. Приклади формул:
- `created_at` — лише при створенні;
- `stage.name == 'Відправлено'` — угода перейшла на етап «Відправлено»;
- `result == 'successful'` — угоду закрито «Виграно»;
- `any(jobs, job, job.sku == '1')` — в угоді є товар з артикулом 1;
- `is_overdue == true` — завдання прострочене.

Угоди, що вже стоять на етапі, тригер не зачіпає — лише нові дії. Тригер спрацьовує на зміни людей, ШІ-співробітників, вхідних замовлень і вебхуків; імпорт і дзеркало KeepinCRM тригерів не запускають, як і зміни, зроблені самим тригером.

## 5. Коли запускати: відразу, із затримкою, за датою
«Метод запуску»:
- «Відразу» — одразу після дії;
- «З затримкою» — «Затримка, хвилин» (2 дні = 2880, 1 год 30 хв = 90);
- «На основі поля з типом дата» — «Поле з типом дата», «Метод виконання» («До дати» / «Після дати»), «Днів», «Годин», «Хвилин». Для дат без часу (власні поля, день народження) години й хвилини означають «о котрій».

## 6. Перевірити перед увімкненням
Унизу шторки — згорнутий блок «Перевірити на записі»: впишіть «ID запису» (порожньо — останній) → «Перевірити». Побачите, чи умова зараз істинна і чи була б при створенні, помилки в тілі чи шаблоні й готовий запит. Для збереженого тригера є «Виконати на записі» — справжня відправка на вибраному записі (у журналі позначено «перевірка»).

## 7. Журнал спрацювань
Відкрийте тригер → вкладка «Журнал спрацювань»: «Коли», «Стан» («успішно», «помилка», «пропущено», «у черзі», «виконується»), «Запис», «Відповідь» з «запит / відповідь». «Повторити» — для помилки, «Скасувати» — для відкладеного запуску в черзі. Показано останні 100 спрацювань, ключі в запитах приховано. Відповідь також записується нотаткою в картку угоди, клієнта чи товару.

Автодії етапу (відповідальний, перенести, в архів) налаштовуються й у «Воронки й етапи» — для простих правил «потрапила на етап». Тригер потрібен, коли є умова по полях («Пром-оплата», служба доставки) або затримка.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Вкажіть назву тригера» | Порожня назва | Впишіть назву |
| «URL має починатися з http:// або https://» | Неповна адреса | Вставте повну адресу сервісу |
| «Умова виконання: …» (наприклад, «незрозумілий символ…») | Помилка в умові | Виправте за прикладами з розділу 4 |
| «Затримка: вкажіть кількість хвилин (напр. 2 дні = 2880)» | «З затримкою» без числа | Вкажіть хвилини |
| «Оберіть поле з типом дата» | Запуск за датою без поля | Виберіть поле |
| «секцію {{#…}} не закрито» / «зайвий або невідповідний {{/…}}» | Помилка в шаблоні тіла | Закрийте секцію |
| «тіло запиту — не коректний JSON…» | Зайва кома чи лапка в тілі | Виправте JSON |
| У журналі «помилка» з HTTP-кодом | Сервіс відхилив запит | Перевірте ключ, адресу й тіло, потім «Повторити» |

## Для ШІ-співробітників
- Інструментів для тригерів нема: створює й змінює їх людина в «Налаштуваннях». Тригери спрацьовують і на ваші зміни — наприклад, угода, яку ви перевели на «Відправлено», може надіслати клієнту Viber.
- Не повторюйте дію лише для того, щоб «ще раз спрацював тригер»: попросіть людину скористатися «Повторити» в журналі.

## Додаткова інформація
- Пов'язані статті: [Вебхуки](settings-webhooks.md), [Воронки, етапи, переходи](settings-funnels.md), [SMS (TurboSMS)](int-sms.md), [Telegram](int-telegram.md), [Webhook](int-webhook.md).


---

# Вебхуки

Вхідний вебхук — адреса, на яку сторонній сервіс (сайт на WooCommerce, форма Contact Form 7, Weblium, WIX, Facebook Leads) надсилає заявку чи замовлення, а Helomi сам створює з неї контрагента, угоду й завдання за вашим мапінгом полів. Вихідні вебхуки — навпаки, Helomi шле дані в інший сервіс; вони налаштовуються тригерами.

## Можливості
- Шаблони: «Webhook без налаштувань», «WooCommerce (кошик)», «WordPress (Contact Form 7)», «Weblium (форми)», «Weblium (кошик)», «Facebook Leads (Apix-Drive)», «WIX (форми)».
- Свій URL на кожен вебхук; ключ — токен в адресі.
- Мапінг змінних запиту в поля контрагента, угоди (з товарами) і завдання, у тому числі в додаткові поля.
- Захист від дубля угоди за ID замовлення.
- «Історія запитів»: що прийшло, що створено, чому не створено; повторна обробка після виправлення мапінгу.

## 1. Налаштування
«Налаштування → Автоматизація → Вхідні вебхуки» — відкриває «Інтеграції → Webhook». Бачить сторінку людина з доступом «Інтеграції»; створює й змінює вебхуки адміністратор або людина з «Налаштування CRM».

Сайти, підключені як окремі акаунти в «Інтеграції → Сайти», мають власну адресу «Вебхук url» і вкладку «Поля» в картці сайту — стаття «Сайти». Вхідні вебхуки тут — для будь-якого іншого сервісу.

## 2. Створити вхідний вебхук
1. «+ Новий вебхук» → виберіть шаблон сервісу або «Webhook без налаштувань».
2. Відкриється картка вебхука: назва, «шаблон: …», перемикач «Приймає запити», рядок «URL вебхука:» з кнопкою копіювання.
3. Скопіюйте URL і вставте його в налаштуваннях сервісу (у WooCommerce — Webhooks, у формі — адреса відправки).
4. Перевірте блоки мапінгу (розділ 3) і натисніть «Зберегти».
5. Надішліть тестову заявку з сервісу (заповніть форму як клієнт) — вона з'явиться в «Історії запитів».

Якщо в налаштуваннях вебхука чогось бракує, над блоками з'являться попередження червоною крапкою.

## 3. Мапінг: контрагент, угода, товари, завдання
Кожен блок — таблиця «Змінна запиту» → «Поле CRM». Змінні пишуться як `a.b`, `a[].b`, `a[1].b`, `$.x`, сталий текст — `/текст/`, кілька змінних разом — `{{a}} {{b}}`.
- **«Контрагент»** — створюється завжди; обов'язково заповнити «Назва компанії» або «Контактна особа». Тут же — тип (лід чи клієнт), відповідальний, джерело, статус, теги.
- **«Створювати угоду»** — галочка; обов'язково «Назва угоди». Воронка й етап, «ID замовлення» (не дасть створити дубль), додаткові поля угоди.
- **«Товари»** — масив товарів у запиті і чотири змінні елемента: назва, кількість, ціна, артикул. Артикул шукається на складі.
- **«Створювати завдання»** — галочка; обов'язково «Назва завдання». Чітка назва для всіх — `/Передзвонити/`.

Унизу — «Зберегти», «Скасувати зміни» і «є незбережені зміни», якщо ви ще не зберегли.

## 4. Перевірити на справжньому запиті
Блок «Історія запитів» — «Дата», «Результат», «Що сталось», «Тіло». У рядку запиту:
- «Змінні» — показує всі змінні з прикладами значень; клік по змінній вставляє її в рядок мапінгу;
- «Перевірити мапінг» — що вийде з цього запиту за поточним мапінгом, нічого не створюючи;
- «Обробити ще раз» — створити записи з цього запиту після виправлення мапінгу.

Якщо запит не пройшов, нічого не створюється, а причина видно в «Що сталось». Сервісу Helomi відповідає успіхом навіть на помилку мапінгу, щоб WooCommerce не вимкнув вебхук.

## 5. Нова адреса, вимкнути, видалити
- «Нова адреса» — новий токен; стара адреса перестає працювати.
- Перемикач «Приймає запити» / «Вимкнено».
- «Видалити вебхук» прибирає профіль; створені ним клієнти, угоди й завдання лишаються.

## 6. Вихідні вебхуки
Щоб Helomi сам надсилав дані назовні (нова угода → Telegram, етап → SMS, рух товару → сайт), створіть тригер: «Налаштування → Автоматизація → Тригери (Webhook)» — стаття «Тригери».

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Контрагент: не налаштовано поле «Назва компанії» або «Контактна особа» — без нього нічого не створиться» | Немає рядка для назви чи особи | Додайте змінну для одного з полів |
| «Угода: не налаштовано поле «Назва угоди»» / «Завдання: не налаштовано поле «Назва завдання»» | Увімкнено блок без назви | Додайте змінну або сталий текст `/…/` |
| «не заповнено «Назва компанії / Контактна особа» — перевірте змінні контрагента» | У запиті нема даних за вказаною змінною | «Змінні» → виберіть правильну |
| «поле «…» — цифрове, а прийшло …» / «— Так/Ні…» / «— дата…» | Значення не того типу | Змініть мапінг або тип поля |
| «external_uid «…» вже зайнятий — угода #… уже створена раніше» | Повторне замовлення з тим самим ID | Нічого: дубль не створено |
| «додаткового поля «…» нема — оновіть мапінг» | Поле видалили | Виберіть інше поле |
| «етапу «…» нема» / «етапу #… нема — оновіть налаштування угоди» | Етап видалено чи змінено | Виберіть етап знову |
| «Змінювати вебхуки може адміністратор або хто має «Налаштування CRM»» | Немає прав | Попросіть адміністратора |

## Для ШІ-співробітників
Інструментів для вебхуків нема — їх налаштовує людина. Угоди й клієнти, створені вебхуком, ви бачите й змінюєте звичайними `deals_*` і `clients_*`; джерело в такій угоді може бути заборонено змінювати («Налаштування → Продажі → Джерела»).

## Додаткова інформація
- Пов'язані статті: [Тригери](settings-triggers.md), [Сайти](int-sites.md), [Webhook](int-webhook.md), [Угоди](deals.md), [Клієнти](clients.md).