# Продажі й клієнти — WIKI Helomi

> Угоди від замовлення до «Виграно», клієнти, завдання, черга продажу, переписки й дзвінки.


---

# Угоди

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

## Можливості
- Список угод з пошуком за назвою, номером, ТТН, телефоном і клієнтом; фільтри за воронкою, етапом, джерелом, брендом, відповідальним, періодом, протермінуванням і додатковими полями.
- Два вигляди: «Таблиця» і «Канбан» з перетягуванням; останній вибір запам'ятовується. Номер і назва угоди — справжні посилання: клік відкриває картку тут, Ctrl/⌘-клік, середня кнопка миші або «Відкрити в новій вкладці» з правого меню — у новій вкладці (20.10).
- Картка угоди: дані угоди й клієнта, товари з групами, доставка й ТТН, завдання, фінанси, документи, файли, нотатки, журнал активності.
- Воронки й етапи з кольорами, дозволеними переходами, автодіями етапу і доступом за людьми.
- Склад за етапом: резерв, списання і повернення товарів — автоматично етапом або вручну з «⋮» позиції.
- Закриття «Виграно» / «Програно» з причиною зі списку воронки.
- Масові зміни, SMS клієнтам вибраних угод, видалення; збережені фільтри; імпорт і експорт XLSX у форматі KeepinCRM.

## 1. Налаштування
Усе налаштовує людина з правом на «Налаштування», без розробника.

- **Поля угоди** — «Налаштування → Типи даних → Угоди» (з розділу — «⋮ → Налаштувати поля», з картки — «⋮ → Налаштувати поля угоди»; пункт видно адміністратору). Тут вбудовані поля (назва, клієнт, воронка, етап, джерело, відповідальний, коментар, дата завершення, бренд і юрособа) і власні поля будь-якого типу. Для кожного поля: «обов'язкове» (без значення угода не збережеться ні вручну, ні через API), «при створенні» (поле є в шторці «Нова угода»), «у списку» (колонка), порядок — перетягуванням. Системні поля позначені замком: їх не можна вимкнути чи змінити тип. Поле можна прив'язати до окремих воронок («Воронки продажів: усі / лише вибрані») — тоді картка й шторка показують його лише в цих воронках. Поля клієнта з позначкою «Також відображати у розділах → Угоди» видно внизу «Даних угоди» блоком «Поля клієнта».
- **Воронки й етапи** — «Налаштування → Воронки й етапи»: «+ Воронка», «+ Етап», назва, колір, роль етапу, колонка «Склад» (нічого / списати / повернути), автодії етапу (змінити відповідального, перенести або скопіювати в іншу воронку, перенести в архів), «Причини виграшу» і «Причини програшу», «Хто має доступ» («Усі користувачі CRM» або «Лише вибрані»).
- **Правила** — «Налаштування → Переходи по етапах» (заборонені переходи), «Валідація» (умова → текст помилки), «Терміни по замовленнях в етапах» (ліміт часу на етапі → угода «Протермінована»).
- **Угоди: загальні** — «Налаштування → Угоди: загальні»: «Групи товарів», «Юрособа обов'язкова при закритті угоди», «Доступ до угод за брендами людини» (людина бачить угоди лише брендів своїх компаній з картки в «Користувачі» і угоди без бренду).
- **Довідники** — «Налаштування → Джерела», «Теги».
- **Доступ** — галочка «Угоди» у «Налаштування → Розділи меню» (ті самі галочки є в картці людини в «Користувачі»).

## 2. Знайти угоду: пошук, фільтри, збережені фільтри
Пошук знаходить угоду за назвою, номером, ТТН, телефоном, клієнтом чи email; фільтри звужують список за воронкою, етапом, джерелом, відповідальним і датами, а вдалий набір фільтрів зберігається під назвою.

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

На телефоні фільтри сховані за кнопкою «Фільтри», а рядки списку стають картками.

## 3. Створити угоду
Нову угоду створюють кнопкою «+ Нова угода»: клієнт, товари, оплата й доставка в одній шторці. Які поля в ній є, які обов'язкові й що підказано під кожним — вирішуєте ви в «Типи даних → Угоди».

1. Натисніть «+ Нова угода».
2. Знайдіть клієнта за телефоном або назвою, або заповніть «Новий клієнт: назва / ПІБ» і «Телефон».
3. Виберіть воронку й етап, заповніть поля (обов'язкові позначені).
4. Додайте товари: відкриється вікно складу з папками, пошуком і «лише в наявності»; «+» додає позицію і лишає вікно відкритим. Позицію поза складом додайте як вільну («Назва товару чи послуги»). Галочка «резерв» резервує товар.
5. За потреби вкажіть «Оплата (сума)», ТТН і адресу доставки. Поле «Коментар» і поля типу «Текст» ростуть разом із текстом; кнопка-рамка в куті поля відкриває його шторкою збоку, «Готово» переносить текст назад у форму.
6. Збережіть. Номер «№…» угода отримує сама.

## 4. Картка угоди
Картка угоди збирає все про одне замовлення: дані, товари, оплати, доставку, документи, файли, задачі й журнал. Непотрібні вам блоки можна вимкнути для себе в «Мій акаунт → Вимкнення непотрібних блоків».

Ліворуч — «Дані угоди» (значення змінюються кліком по ньому, Enter зберігає), панель маркетплейсу (лише коли замовлення прийшло з API площадки — Prom, Rozetka, Kasta, Епіцентр, OLX: в угоді є номер замовлення площадки; угоді, яку створили вручну чи ШІ з таким джерелом, панель не показується; ID замовлення й назва панелі відкривають замовлення в кабінеті Prom, Rozetka чи Епіцентру, рядок «ТТН» — з кнопкою «Скопіювати», «?» — статтю WIKI цієї інтеграції у шторці; статус замовлення й оплати — кольоровою пігулкою людською мовою, напр. «Оплачено», а не код площадки), «Товари», «Доставка», «Завдання», «Фінанси», «Документи», «Файли» (кожен файл — квадратик-прев'ю, як у KeepinCRM: мініатюра першої сторінки PDF чи фото, для інших — тип файлу; під ним назва, розмір і дата; натиск відкриває файл, «✕» у куті — «Відкріпити»; додати можна й з буфера — клацнути по блоку «Файли» і Ctrl+V, див. «Налаштування» §5б). Праворуч — «Всього», «Сплачено», «Очікується», вкладки «Нотатки», «Чати», «Email» і «Журнал активності», де видно, хто й коли що змінив.

**Довгий текст** — «Коментар» і власні поля типу «Текст» (напр. «Коментар для ШІ ЛЮДИ»). У картці текст показується так, як його написали: з абзацами й переносами рядків; довгий згорнуто до шести рядків, «Розгорнути» показує весь, «Згорнути» — знову коротко. Натиск по полю відкриває шторку збоку (на телефоні — знизу на весь екран): велике поле з курсором у кінці тексту, під ним підказка поля з «Типи даних → Підказка» і лічильник знаків. «Зберегти» (або Ctrl+Enter) зберігає і закриває шторку, угорі праворуч з'являється повідомлення про збереження. Якщо сервер не прийняв текст, причина з'являється над кнопками, а шторка лишається відкритою з вашим текстом. «Скасувати», «×», Esc чи натиск поза шторкою закривають її; якщо текст змінено, спершу спитають «Закрити без збереження?». Enter у шторці — новий рядок.

У «⋮» шапки картки: «Виграно», «Програно», «Змінити воронку», «Надіслати SMS», «Перевірити в BlackBox», «Додати в BlackBox», «В архів» або «Розархівувати», «Налаштувати поля угоди», «Видалити». Пункт з'являється лише тоді, коли дія можлива.

У картці клієнта в угоді «Інші угоди: N» — скільки ще угод у клієнта, крім цієї (лише ця угода — 0); натиск відкриває угоди клієнта. Статус клієнта «Постійний», коли інші угоди є, інакше «Новий».

Під етапами — смуга «Склад»: зелена «Склад: зібрано 21.10 17:49 (хто)», де «хто» — збирач; червона «зібрано ПОВТОРНО — N рази», коли угоду збирали кілька разів (перевірте, чи нема на складі зайвої посилки); жовта «Склад: повернуто менеджеру … — не зібрано» з причиною, коли збирач повернув замовлення (кнопка «Повернути менеджеру» в «Складі»). Зібраною вважається лише угода, яку збирач позначив «Зібрано» в «Складі». Якщо ви самі перевели угоду на етап «Зібрано» кнопкою чи кружечком етапу, смуги не буде, і збирач не отримає попередження «вже збирали». Повернення теж збіркою не вважається.

Під етапами — смуга BlackBox (коли інтеграцію підключено): кожна угода перевіряється сама, смуга показує «покупця в базі нема», «знайдено в базі несумлінних», «перевірка в черзі» чи «не вдалося перевірити», а кнопка «Перевірити ще раз» перевіряє заново. Детально — [BlackBox](int-blackbox.md).

На телефоні картка йде в одну колонку, етапи — смугою «Етап N з M», товари — картками позицій. На телефоні й у вузькому вікні (до 1100 px) ряд етапів гортається пальцем, стрілками ‹ › по краях ряду або перетягуванням мишею; стрілку видно, лише коли в той бік є ще етапи.

Адреса угоди — `/crm/deals/<id>`. Угоду замовлення маркетплейсу можна відкрити і за номером: `/crm/deals/order/<канал>/<номер>` (канал — `prom`, `rozetka`, `kasta`, `epicentr`, `olx`). Сторінка сама знаходить угоду (за полем «№ замовлення», інакше за назвою серед угод джерела каналу) і відкриває картку; не знайшла — пише чому і пропонує перейти до списку. Такі посилання стоять на номерах замовлень Prom і Rozetka в «Переписках» і відкриваються в новій вкладці (див. [Переписки](chats.md#8-номер-замовлення-відкриває-угоду)).

## 5. Перевести на етап, змінити воронку
Етап показує, де зараз замовлення. Зміна етапу може списати товар, провести оплату чи створити завдання — так налаштовано у воронці.

1. У шапці картки натисніть кнопку з назвою наступного етапу («→ …») або виберіть етап у списку поруч.
2. Якщо перехід заборонено налаштуваннями, з'явиться пояснення, і етап не зміниться.
3. Після переходу спрацюють налаштування етапу: склад (списати / повернути) і автодії. Запис з'явиться в журналі.
   Поки етап зберігається, обраний крок притишений, біля лічильника — «Зберігаю етап «…»…», а повторні натискання не діють (раніше
   кожен натиск ішов окремим запитом, і угода «не реагувала»). Результат приходить повідомленням поверх сторінки — праворуч угорі на
   комп'ютері, над нижнім меню на телефоні: «Етап змінено на «…»», «Етап не змінено: угода вже на етапі «…»» чи «Автодія етапу «…»
   перевела угоду на «…»» (зникає саме за кілька секунд). Якщо етап змінити не вдалося (наприклад, «списання в мінус заблоковано»),
   повідомлення з червоною крапкою висить, поки ви його не закриєте або не натиснете «Повторити»; усередині картки банерів нема.
   Так само приходять результати всіх дій в угоді: списання, резерв, ТТН, SMS, документи, чеки, «В архів» (зі «Скасувати» на 8 секунд).
4. Щоб перенести угоду в іншу воронку: «⋮ → Змінити воронку» → воронка й етап (типово — початковий).

## 6. Товари і склад
Товари угоди — позиції зі складу, прайс-листа або вільні рядки. З них рахується сума угоди, а склад резервує й списує товар за етапами воронки.

- «+» у блоці «Товари» відкриває вікно складу. Колонка «Склад» показує стан позиції: резерв, списано, на складі.
- У вікні «Додати товар» біля назви товару, який уже є в угоді, — «у угоді ×N» (скільки його в угоді). Зайве додали — **«Відняти»** в кінці
  рядка: кількість останньої позиції цього товару зменшується на число з поля «Кількість», а позиція з меншою кількістю прибирається.
  Коли в «Налаштування → Товари» увімкнено «Заборонити додавати товар, якого немає в наявності», «+» у рядку без вільного залишку вимкнений.
- **Списану позицію не видаляють і не зменшують** (власник 21.10): інакше товар зник би зі складу без продажу. Спершу «⋮ → Повернути
  на склад» (залишок повертається), тоді «Видалити позицію», «Відняти» чи нова кількість. Збільшити кількість і змінити ціну можна.
- **У мінус не списується**, коли в «Налаштування → Товари» увімкнено «Заблокувати списання товару, якщо наявність 0». Людина, яка
  переводить угоду на етап, що списує товар, побачить «Етап «…» не змінено: «артикул»: в наявності 0, а списується 1 …», і етап лишиться
  старим. Автоматичний перехід (трекінг доставки, приймання замовлень, автодії) етап змінює — посилка вже поїхала, — але позицію без
  залишку не списує: у журналі угоди «не списано: товару нема в наявності …», а в дзвіночку «Сповіщення складу» (над вкладками складу) — «Не списано: нема в наявності»
  з посиланням на угоду. Оприбуткуйте товар і спишіть позицію: «⋮ → Списати зі складу».
- Назву позиції видно повністю. Назва позиції з прайс-листа — посилання: натиск відкриває шторку цієї позиції (усі фото, артикул, ціни, канал, папка, наявність, опис) з кнопкою «Відкрити в прайс-листі». Фото в колонці «Фото» — з товару складу, а якщо його нема — з позиції прайс-листа.
- «⋮» позиції: «Зарезервувати», «Зняти резерв», «Списати зі складу», «Списати частково…», «Повернути на склад», «Прив'язати до товару складу…», «Перемістити в групу…», «Видалити позицію».
- «⋮» блоку: «Списати все зі складу», «Повернути все на склад».
- **Позиція «не пов'язано зі складом»** (так підписано під назвою) — прийшла з площадки чи сайту з артикулом, якого нема на складі, або додана вільною. Списати її все одно можна:
  1. «⋮ → Списати зі складу» спершу шукає за артикулом товар складу, а якщо його нема — позицію прайс-листа з тим самим артикулом, пов'язану зі складом. Позиція, додана з прайс-листа, списує свої пов'язані товари складу; без зв'язки — товар складу з її артикулом (20.10), а без такого товару — послуга, складу не чіпає. Набір «ПА0001-N3» (3 рулони ПА0001) списується як 3 × ПА0001 на кожну штуку позиції. Регістр і кирилиця/латиниця в артикулі (А000044 і A000044) не важать, коли такий товар один. Якщо на складі дві різні картки, що відрізняються лише літерою (К000028 кирилицею і K000028 латиницею), береться та, де артикул збігається точно. Без точного збігу позиція лишається не пов'язаною — прив'яжіть її вручну (23.10). Якщо в «артикулі» позиції — id оголошення з площадки (старі замовлення Prom: 9242016), береться позиція прайс-листа цього оголошення, коли вона пов'язана зі складом.
  2. Якщо за артикулом нічого не знайшлося — «⋮ → Прив'язати до товару складу…», знайдіть товар за назвою чи артикулом і клацніть його. Ціна й назва позиції лишаються, собівартість береться з товару, якщо її не було. Набір прив'язуйте через прайс-лист: у позиції прайс-листа вкажіть товари складу й кількість — тоді позиції угод з цим артикулом зв'яжуться самі.
  3. Нові замовлення з площадок і сайтів пов'язуються так само одразу, ще при створенні угоди.
  4. Етап, що списує товар, пропускає позиції без зв'язку і пише в журнал угоди «не списано: …» з їх артикулами. Позиції без артикула (доставка, пакування) складу не стосуються, їх не згадано.
- Зв'язок зі складом пишеться в журнал угоди («зв'язок зі складом: товар складу … / прайс-лист …»). Списану чи зарезервовану позицію не перев'язують: спершу «Повернути на склад».
- Якщо групи товарів увімкнено, «+ Група» додає блок; сума угоди від груп не змінюється.

## 7. Оплати, доставка, документи
Оплати лягають у «Фінанси» й зменшують «Несплачено»; доставка створює ТТН і переводить угоду на етап за статусом посилки; документи збираються з шаблонів за даними угоди.

- **Оплата**: «+» у блоці «Фінанси» → напрямок (дохід чи витрата), гаманець, категорія, сума, дата, коментар. Платіж одразу стає операцією у «Фінансах», а «Сплачено» і «Очікується» перераховуються. Бізнес операції — за товарами угоди; поля угоди чи клієнта можна передавати в поля операції правилом «Угода → її оплати й операції» («Налаштування → Правила передачі»).
- **Блок «Фінанси»**: угорі «Всього», «Сплачено», «Очікується», «Витрати», «Прибуток» і «Маржа», у шапці блоку — статус оплати («Сплачено», «Частково сплачено», «Не сплачено»), під ними смужка: скільки суми угоди вже сплачено. «Витрати» — додаткові витрати по угоді (доставка за наш рахунок, комісії), вони віднімаються від прибутку; клік по сумі — змінити.
- **Платежі угоди** — рядками під зведенням: сума (зелена — дохід, червона — витрата), пігулки «банк» (прийшов з виписки) і «план» (гроші ще не прийшли), іконка скріпки з кількістю квитанцій, дата; нижче — гаманець, категорія, клас, бізнес і хто провів, окремим рядком — коментар. Натиск на суму відкриває саму операцію «Фінансів» тут же, поверх угоди: змінити, додати квитанцію, видалити; після збереження угода перераховується. Натиск на гаманець відкриває «Фінанси → Операції» з фільтром цього гаманця (Ctrl-клік — у новій вкладці).
- **Посилання на оплату** видно в блоці, лише коли підключено LiqPay чи MonoPay або в угоди вже є посилання; підключають їх в «Інтеграціях», окремої підказки в угоді нема.
- **Доставка**: «+» у блоці «Доставка» або «Додати місце» під таблицею відкриває шторку «Створити ТТН»; «вручну» — запис наявного номера (і для Kasta та «Магазинів Rozetka» на Prom: у шторці «Створити в кабінеті / Додати ТТН»; якщо в угоді вже є рядок тієї служби без номера, номер лягає в нього). Поки ТТН нема, дані замовлення (з Prom, Rozetka, сайтів…) — у полях блоку: «Адреса доставки», «Одержувач», «Телефон одержувача» і «Спосіб доставки»; з них бере дані шторка «Створити ТТН». «Адреса доставки» — як у KeepinCRM: місто, вулиця, будинок і точка з номером («Київ, вул. Якуба Коласа, 15, Відділення №88»; з описом служби — «Київ, Відділення №88 (до 30 кг): вул. Якуба Коласа, 15»), номер відділення чи поштомата не клеїться у вулицю. Рядок у таблиці з'являється лише з номером ТТН; біля номера — кнопка «Скопіювати». «⋮» рядка ТТН (є на початку й у кінці рядка — таблиця ширша за картку): «Передати ТТН на Prom/Rozetka/Kasta/Епіцентр» (угода з маркетплейсу), «Роздрукувати стікер», «Оновити статус», «Відкрити на сайті служби», «Скопіювати номер ТТН», «Видалити ТТН» (у перевізника і з угоди). У клітинці ТТН угоди з маркетплейсу — постійна кнопка «На Prom/Rozetka/Kasta/Епіцентр» (передати ТТН; коли ТТН уже на площадці — значок площадки з галочкою; площадка приймає ТТН лише на певному статусі замовлення, Helomi спершу переводить замовлення туди, етап угоди не змінюється). Докладно — стаття «Доставки і ТТН».
- **Документи**: «+» у блоці «Документи» → шаблон; документ створюється одразу з даними угоди. «+» → «Завантажити свій документ…» —
  файл (Word, Excel, PDF, фото) стає документом угоди в нашому форматі. «Редагувати» — правка прямо на аркуші, лише цей документ;
  номер міняється олівцем у вікні документа. Докладно — стаття «Документи».

## 8. Закрити, в архів, видалити
1. «⋮ → Виграно» або «⋮ → Програно» → причина зі списку воронки (або без причини) і коментар. Угода переходить на етап з відповідною роллю (якщо він є) і йде в архів; причина з коментарем потрапляє в нотатки й журнал.
2. «⋮ → В архів» прибирає угоду в архів без результату; «Розархівувати» повертає.
3. Угода, посилку з якої отримано, іде в архів сама: трекінг перевізника оновлює статус ТТН кожні N хвилин, і «отримано» переводить угоду у «Виграно» й архів (налаштування перевізника: «Оновлювати статуси ТТН автоматично», «Посилку отримано → угода «Виграно» в архів»).
3. «⋮ → Видалити» після підтвердження видаляє угоду: резерв знімається, списані товари повертаються на склад, платежі видаляються з відкатом балансу гаманця, документи лишаються без угоди.

У списку ті самі дії є в «⋮» рядка: «Відкрити», «В архів» / «Розархівувати», «Видалити».

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

## 10. Масові дії і SMS
1. Позначте угоди галочками або «Вибрати всі на сторінці»; щоб узяти всі за фільтром — «Вибрати всі за фільтром (N)».
2. Унизу з'явиться панель «Вибрано: N»: «Масові зміни», «SMS», «Видалити», «Скасувати вибір» (в архіві — лише «SMS» і «Видалити»).
3. «Масові зміни»: головний відповідальний, воронка й етап, результат і причина, джерело, філія, додаткове поле (встановити або очистити), «Створити завдання для всіх угод». Понад 200 угод обробляються у фоні зі смужкою прогресу; у підсумку — скільки оновлено, без змін і з помилками.
4. «SMS» надсилає шаблон або свій текст на основний телефон клієнта кожної угоди через TurboSMS (кабінет, підпис і шаблони — з картки «Інтеграції → SMS (TurboSMS)»); у тексті — змінні `{{.client.name}}`, `{{.agreement.title}}`, `{{.agreement.total}}`, `{{.last_delivery.ttn}}` (старі `{client.name}`, `{deal.title}`, `{deal.total}` теж працюють). Без токена чи підпису кнопка сіра з підказкою. Деталі — [SMS (TurboSMS)](int-sms.md).

Окремої галочки доступу на масові дії з угодами нема — їх може робити кожен, кому відкрито «Угоди».

## 11. Імпорт і експорт
«⋮» у шапці списку → «Імпорт» або «Експорт». Файли сумісні з шаблонами KeepinCRM. Покроково — стаття «Імпорт і експорт».

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Заповніть обов'язкові поля: …» | Поле позначено обов'язковим у «Типах даних → Угоди» | Заповніть поле або зніміть позначку в налаштуваннях |
| «Обов'язкове поле не можна очистити: …» | Спроба стерти значення обов'язкового поля | Впишіть нове значення замість старого |
| «Перехід з етапу «…» на «…» заборонено налаштуваннями» | Заборонений перехід у «Переходи по етапах» | Перейдіть через дозволений етап або змініть налаштування |
| «Валідація «…» не пройдена» або власний текст | Спрацювала умова в «Налаштування → Валідація» | Виправте те, про що пише текст помилки |
| «Немає доступу до воронки «…»» | Воронка відкрита лише вибраним людям | Попросіть адміністратора додати вас у «Хто має доступ» |
| «Немає доступу до угод цього бренду» | Увімкнено «Доступ до угод за брендами людини», а бренд угоди не серед ваших компаній | Попросіть адміністратора додати компанію у вашій картці в «Користувачі» |
| «Товару «…» немає в наявності — додавати в угоду заборонено» | Так налаштовано в «Склад і товари → Загальні налаштування» | Оприбуткуйте товар або змініть налаштування |
| «Ручне списання заборонено — товар списується етапом угоди» | Ручне списання вимкнено в налаштуваннях складу | Переведіть угоду на етап, що списує товар |
| «…: позиція не пов'язана зі складом — за артикулом нема ні товару складу, ні позиції прайс-листа зі зв'язкою зі складом» | Артикула позиції нема ні на складі, ні в прайс-листі зі зв'язкою | «⋮ → Прив'язати до товару складу…» або пов'яжіть позицію прайс-листа з цим артикулом зі складом |
| «Нічого не списано: позиції не пов'язані зі складом (…)» | «Списати все» не знайшло, з чого списувати | Прив'яжіть названі позиції, як вище |
| ««…» у прайс-листі не пов'язана зі складом — спершу додайте їй товари складу» | Обрана позиція прайс-листа — послуга без товарів складу | Додайте їй товари складу в прайс-листі або прив'яжіть товар складу напряму |
| «…: позицію вже списано або зарезервовано — спершу поверніть її на склад» | Перев'язати можна лише позицію без руху складу | «⋮ → Повернути на склад», потім прив'язуйте |
| «…» списано зі складу — спершу поверніть позицію на склад …, тоді видаляйте (віднімайте, зменшуйте кількість)» | Позицію вже списано: без повернення товар зник би зі складу | «⋮ → Повернути на склад», потім видаляйте чи змінюйте кількість |
| «Етап «…» не змінено: «…»: в наявності …, а списується … — списання в мінус заблоковано …» | Увімкнено «Заблокувати списання товару, якщо наявність 0», а товару менше, ніж у позиції | Оприбуткуйте товар (Склад → Прихід) або перевірте кількість, тоді змініть етап |
| «Етапу №… не існує — оновіть сторінку й оберіть етап зі списку» | Етап видалили або перейменували в налаштуваннях, поки картка була відкрита | Оновіть сторінку і виберіть етап зі списку |
| «Товару №… на складі не існує — оновіть сторінку й оберіть товар зі списку», «Позиції прайс-листа №… не існує — …» | Товар чи позицію видалили, поки ви їх вибирали | Оновіть сторінку й оберіть зі списку ще раз |
| «Сервер не відповів — спробуйте ще раз» | Мережа, таймаут або збій сервера (не помилка даних) | Натисніть «Повторити» в повідомленні або повторіть дію за хвилину |
| «Оновлено … помилок …» з кнопкою «Показати» | Масова дія виконалась частково | «Показати» відкриває список угод із причинами; виправте їх і повторіть для цих угод |
| «Позиція «…» уже у фіскальному чеку — спершу зробіть повернення чека» | По позиції пробито чек Checkbox | Зробіть повернення чека, потім міняйте позицію |
| «Забагато угод за раз: не більше …» | Ліміт масової дії | Звузьте фільтр і повторіть частинами |
| «Видаляти угоди заборонено вашими доступами» (або «…, де ви не головний відповідальний, …») | Заборону видалення задано в «Налаштування → Доступи» | Попросіть адміністратора або перенесіть угоду в архів |

## Для ШІ-співробітників
Ключ розділу — `deals` (`describe_section("deals")` повертає поля з налаштувань з типами, обов'язковістю і воронками, довідники й дії). Потрібен доступ «Угоди».

| Інструмент | Що робить |
| --- | --- |
| `deals_list` | Список угод з `q` (назва, номер, ТТН, телефон, клієнт) і фільтрами `funnel_id`, `stage_id`, `source_id`, `responsible_id`, `client_id`, `archived`, `result`, `date_from`, `date_to`, `overdue`, `brand_id` |
| `deals_get` | Картка: поля, позиції, оплати, доставки, нотатки, задачі |
| `deals_refs` | Воронки з етапами, джерела, відповідальні, поля, бренди |
| `deals_create` | Нова угода: `values` з `client` або `client_id`, `title`, `funnel_id`, `stage_id`, `items`, власні поля в `custom`; передавайте `idempotency_key` |
| `deals_update` | Змінити поля (обов'язкові не очищаються) |
| `deals_change_stage` | Перевести на етап `stage_id` (перевіряє дозволені переходи) |
| `deals_close` | Закрити: `result` = `won` або `lost`, причина, коментар |
| `deals_add_item` | Додати позицію за `product_id` або `sku`, або вільну |
| `deals_item_link` | Прив'язати позицію до складу: `values` `{product_id}` або `{price_item_id}` (позиція прайс-листа зі зв'язкою — набір); `{}` — за артикулом позиції |
| `deals_item_writeoff` | Списати позицію зі складу (вільну з артикулом спершу прив'язує за артикулом); `values` `{}` — уся кількість, `{qty}` — частково |
| `deals_writeoff_all` | Списати всі несписані позиції угоди |
| `deals_add_note`, `deals_add_task` | Нотатка, задача по угоді |
| `deals_add_payment` | Оплата → операція у фінансах. **Спочатку запитати** (вид `payments`) |
| `deals_delete` | Видалити угоду. **Спочатку запитати** (вид `delete`) |

Угоду за номером замовлення шукайте `deals_list` з `q=<номер>`; програми й посилання — `GET /api/crm/deals/by-order?channel=<канал>&number=<номер>` (відповідь `{id, title, archived}`, 404 — не знайдено, 403 — нема доступу до воронки, бренду чи угоди).

«Спочатку запитати» типово ввімкнено для всіх видів; людина може змінити це в пульті ШІ-співробітника. Інструментів для ТТН, масових дій, імпорту й експорту поки нема — це робить людина.

Чого не робити:
- Не вигадувати id етапів, джерел, людей — брати з `deals_refs`.
- Не повторювати дію, що повернула `pending_id`: вона чекає підтвердження людини.
- Не видаляти угоди без прямого прохання людини.
- Перед створенням шукати клієнта за телефоном, щоб не створити дубль.
- Результат угоди (`result`) API віддає нашим словником: `won` — «Виграно», `lost` — «Програно», порожньо — без результату. Старі угоди з KeepinCRM (id < 50 000 000) зберігають у базі `successful` / `failed` / `archived` — фільтр `result=won|lost` знаходить і їх; в умовах правил і тригерів результат — словником KeepinCRM: `result == 'successful'` / `'failed'`.

## Додаткова інформація
- Пов'язані статті: [Клієнти](clients.md), [Завдання](tasks.md), [Склад і товари](products.md), [Документи](documents.md), [Доставки і ТТН](shipping.md), [Фінанси](finance.md), [Імпорт і експорт](import-export.md).


---

# Клієнти

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

## Можливості
- Список з пошуком за назвою, контактною особою, телефоном у будь-якому форматі, email і додатковими полями (наприклад, ЄДРПОУ); сортування за будь-якою колонкою, зокрема за виручкою, прибутком, кількістю замовлень і датою останнього замовлення. Назва клієнта — справжнє посилання: Ctrl/⌘-клік, середня кнопка або «Відкрити в новій вкладці» з правого меню відкривають картку в новій вкладці (20.10).
- Фільтри: джерело, відповідальний, теги, філія, лід, архів, сегмент, додаткові поля.
- Картка з кількома телефонами й email, додатковими полями по блоках, показниками «Виручка», «Прибуток», «Сплачено», «Очікується», «Замовлень», «Середній чек», «Частота», «Повернення».
- «Покупки»: що бере клієнт, виручка за 12 місяців, джерела й служби доставки; «Ризики»: повернення з причинами, неоплачені угоди, BlackBox.
- Сегменти клієнтів з порогами, які налаштовує адміністратор.
- Нотатки з @згадкою, журнал змін «було → стало», угоди в роботі й в архіві, задачі, файли.
- Додаткові контакти зі своїми полями: їх бачать угоди, задачі, ТТН і документи.
- Договори з контрагентом: рахунки за договором — гілкою під ним, «Договір:» у рахунку — сам договір.
- Адреси доставки Нової пошти (кілька на клієнта): компанія й ЄДРПОУ, ПІБ, телефон, місто й відділення окремо; основна сама йде у форму ТТН, іншу вибирають пігулкою.
- Пошук і об'єднання дублів за телефоном або email з відновленням протягом 30 днів.
- Імпорт і експорт XLSX у форматі KeepinCRM.

## 1. Налаштування
- **Поля клієнта** — «Налаштування → Типи даних → Клієнти» (з розділу — «⋮ → Налаштувати поля»). Для кожного поля: «обов'язкове», «при створенні», «у списку», порядок перетягуванням, фільтр, унікальність. Системні поля з замком не вимикаються. Позначка «Також відображати у розділах» показує поле клієнта в картці угоди й задачі.
- **Поля додаткових контактів** — «Налаштування → Типи даних → Дод. контакти».
- **Довідники** — «Налаштування → Джерела», «Теги»; філії — «Налаштування → Філії».
- **Сегменти клієнтів** — у списку «⋮ → Сегменти клієнтів»: пороги «Постійний», «VIP», «Згасає», «Втрачений» і звідки брати собівартість для прибутку (див. [10. Сегменти клієнтів](#10-сегменти-клієнтів)).
- **Колонки показників** — блок «Показники» в «Типи даних → Клієнти»: «Сегмент», «Замовлень», «Виручка», «Прибуток», «Останнє замовлення». Вони лише для списку (рахуються самі); увімкніть «Вивести в списку», щоб бачити й сортувати.
- **Доступ** — галочка «Клієнти» у «Налаштування → Розділи меню» (або в картці людини в «Користувачі»).

## 2. Знайти клієнта
1. Відкрийте «Клієнти».
2. Пишіть у пошук назву, ПІБ, телефон (у будь-якому форматі) або email. Пошук бачить і телефони додаткових контактів.
3. Звужуйте фільтрами: джерело, відповідальний, теги, філія, лід («лише ліди» / «не ліди»), «активні» / «архів», сегмент. «Скинути фільтри» прибирає все.
4. «Колонки» — які колонки бачити; клік по заголовку колонки сортує. «Виручка» за спаданням — найбільші клієнти зверху; «Сегмент» сортується від VIP до втрачених.

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

## 3. Створити клієнта
1. Натисніть «+ Новий клієнт».
2. Заповніть «Назва компанії / ПІБ», «Телефон» і потрібні поля: «Контактна особа», «Посада», «Джерело», «Відповідальний», «Теги (через кому)», «Філія», «Знижка», «Націнка», «День народження», «Коментар», прапорець «Лід» та обов'язкові додаткові поля.
3. Натисніть «Створити».
4. Якщо такий телефон уже є в іншого клієнта, Helomi попередить про це. Відкрийте наявну картку або натисніть «Створити все одно».

## 4. Картка клієнта
- У шапці: «+ Нова угода» (шторка угоди з цим клієнтом), «Редагувати», «В архів» / «Розархівувати», «Видалити». Бейдж «Дублі: N» веде до дублів саме цього клієнта.
- Ліворуч — основні поля, «Додаткові поля», «Додаткові контакти», «Договори», «Службове» (кількість угод, ID, коли й ким створено).
- **Договори**: «+» — договір з клієнтом за шаблоном виду «Договір з контрагентом»; кружечок «+» у рядку договору — «Рахунок за
  договором» (з угоди клієнта). Під договором гілкою — рахунки, виписані на його основі, і накладні на основі рахунків. Блок
  ховається в «Налаштування → Блоки». Докладно — [Документи](documents.md), «Договори з контрагентом».
- Значення змінюються на місці; кожна зміна потрапляє в журнал.
- **Довгий текст** — «Коментар» і власні поля типу «Текст»: показуються з абзацами, як їх написали; довгий текст згорнуто, «Розгорнути» показує весь. У «Редагувати» поле росте разом із текстом, кнопка-рамка в куті відкриває його шторкою збоку з підказкою поля й лічильником знаків; «Готово» переносить текст у форму, зберігає — «Зберегти» блоку. На телефоні таке поле стоїть під назвою на всю ширину.
- **Показники** — бейдж сегмента і плитки:
  - «Виручка» — сума виграних угод без повернень за весь час;
  - «Прибуток» — виручка мінус собівартість товарів і витрати угод; примітка «не для всіх товарів задана собівартість» означає, що в частині позицій собівартості нема і прибуток завищений;
  - «Сплачено», «Очікується» (несплачене по відкритих угодах), «Замовлень» (усі угоди, крім програних), «Середній чек», «Частота» (раз на скільки днів замовляє), «Повернення».
- **Покупки** — «Виручка за 12 місяців» (стовпчик на місяць), «Що бере» (товари виграних і активних угод: кількість, сума, у скількох замовленнях, коли востаннє), «За джерелом» і «Доставка» (якими службами відправляли).
- **Ризики** — повернення (скільки, на яку суму, відсоток і причини зі слів клієнта з «Дашборду продажів»), неоплачені угоди, BlackBox (останній результат перевірки телефонів клієнта; перевіряють в угоді).
- Показники рахуються з угод клієнта: собівартість — з товару складу або позиції прайс-листа (як у звітах Марії). Повернення — угода на етапі ролі «Повернення» або посилка, яка в «Доставках» стоїть як повернення.
- Вкладки: «Нотатки» (з @згадкою колеги), «Журнал», «Угоди» (в роботі й архів), «Задачі», «Файли».
- **Файли** — у кожного файлу мініатюра (перша сторінка PDF або фото). Можна додати кілька файлів одразу. Нижче — файли угод клієнта з номером угоди; їх видаляють у картці угоди.

## 5. Додаткові контакти
1. У блоці «Додаткові контакти» натисніть «+».
2. Заповніть ПІБ (обов'язково), посаду, кілька телефонів і email, коментар, додаткові поля контакту.
3. «⋮» контакту: «Редагувати», «Видалити». Під рядком видно, скільки в контакту угод і задач.
4. У картці угоди в рядку «Контакт» можна вибрати додатковий контакт замість основного; ТТН тоді типово йде на нього, а задача з угоди — теж на нього. Після видалення контакту його угоди й задачі повертаються на основний контакт.

## 5а. Адреси доставки
Кілька адрес Нової пошти на клієнта: склад, офіс, інше місто — і в кожної окремо одержувач, телефон, місто й відділення. Основна сама потрапляє у форму ТТН угоди, іншу вибирають там однією пігулкою.

1. Картка клієнта → блок **«Адреси доставки»** → «+». Шторка відкривається **вже заповненою з картки контрагента**: «Назва
   компанії», «ЄДРПОУ» (з поля «Код ЄДРПОУ»; є код — одержувач «Організація»), ПІБ контактної особи й основний телефон; місто й
   відділення — з останньої ТТН Нової пошти цього клієнта (якщо такої адреси ще нема). Над полями видно, що звідки підставлено:
   «Підставлено з картки контрагента: назва, ЄДРПОУ, ПІБ, телефон; з останньої ТТН Нової пошти: місто, відділення». Перевірте й
   змініть, що треба.
2. **Одержувач:** «Приватна особа» або «Організація». Для організації — «Назва компанії» і «ЄДРПОУ» (8 цифр): Нова пошта оформить
   ТТН на компанію, а ПІБ — це той, хто забере посилку.
3. **Прізвище, Ім'я** (обов'язково), «По батькові», **Телефон** (будь-який запис: «096 641 22 63» стане `+380966412263`).
4. **Місто** — почніть вводити й виберіть зі списку Нової пошти; **«Відділення / поштомат»** — натисніть і виберіть зі списку
   (пошук за номером або вулицею). Вибране зі списку ТТН більше не перепитує. Довідник недоступний — впишіть місто й номер
   відділення вручну, форма ТТН знайде їх сама.
5. «Назва адреси» (необов'язково) — як адресу видно у формі ТТН («Склад у Буковелі»); «Коментар» — для себе, у ТТН не йде.
6. Перша адреса стає **основною**; «⋮» → «Зробити основною», «Редагувати», «Видалити» (основною стає наступна). Кожна зміна — у
   «Журналі» клієнта.
7. Було записано текстом у полі «Адреса доставки» — під блоком «Записано текстом: …» і **«Розкласти на поля»**: ЄДРПОУ, телефон, ПІБ
   (після «Довірена особа:») і номер відділення Helomi витягне сам, решту — з картки, місто виберіть зі списку. Старий текст
   лишається як був.
8. У наявній адресі («⋮» → «Редагувати») кнопка **«Заповнити з картки»** дописує з картки контрагента лише порожні поля — заповнене
   вами не змінюється.

> [!NOTE]
> Старе поле «Адреса доставки» (окремий блок «Доставка» в картці) з 23.10 сховане в архів «Налаштування → Типи даних → Клієнти»:
> його замінили «Адреси доставки». Записане там не зникло — з нього працює «Розкласти на поля». Повернути поле — у тому ж архіві.

**У формі ТТН угоди** (блок «Доставка» → «+»), у «Дані одержувача» — рядок **«Адреса клієнта»**: пігулки адрес. Якщо в угоді своєї адреси нема (або там той самий старий текст клієнта), основна адреса вже підставлена — одержувач, телефон, організація з ЄДРПОУ, місто й відділення. Клік по іншій пігулці — форма заповнюється нею; «З угоди» — повертає адресу із замовлення маркетплейсу. Адресу з замовлення Prom чи Rozetka Helomi сам не перекриває. Так само ТТН без форми (ШІ, авто-ТТН на етапі) бере основну адресу клієнта, коли в угоді адреси нема.

## 6. Масові дії
1. Позначте клієнтів галочками.
2. На панелі «Вибрано: N»: вибрати відповідального → «Призначити»; вписати теги через кому → «+ Теги» або «− Теги»; «В архів» (в архіві — «Розархівувати»); для двох і більше — «Об'єднати дублі»; «зняти вибір».

## 7. Пошук і об'єднання дублів
1. «⋮ → Пошук дублів» → «Розпочати пошук». Групи складаються з карток з тим самим телефоном або email.
2. У групі основною типово стоїть найраніше створена картка («Основна»); галочка «Брати в об'єднання» визначає, які картки увіллються.
3. «Переглянути» показує, що лишиться і що переїде; далі «Об'єднати». У «⋮» групи — «Об'єднати без перегляду», «Відкрити основну картку». У шапці — «Об'єднати всі» і «Експорт CSV».
4. Угоди, задачі, нотатки, файли, документи, платежі й ТТН переходять в основну; порожні поля основної дозаповнюються, заповнені не змінюються.
5. Об'єднана картка 30 днів лежить у блоці «Видалені (30 днів)»; «Відновити» повертає її (перенесене лишається в основній).

## 8. Імпорт і експорт
«⋮ → Імпорт» і «⋮ → Експорт». Шаблон, пошук наявних за назвою, контактною особою чи телефоном, «Перевірити», файл помилок — у статті «Імпорт і експорт».

## 9. Архів і видалення
- «В архів» ховає клієнта зі списку активних; «Розархівувати» повертає.
- «Видалити» видаляє клієнта разом з його угодами. 30 днів їх можна відновити в «Налаштування → Видалена інформація».

## 10. Сегменти клієнтів
Сегмент рахується сам за порогами, які задає адміністратор у «⋮ → Сегменти клієнтів» (зміна діє одразу, кожна потрапляє в журнал):

| Сегмент | Коли |
| --- | --- |
| «—» | Замовлень ще нема |
| «Втрачений» | Від останнього замовлення минуло не менше днів, ніж «Втрачений — днів без замовлень» (типово 180) |
| «Згасає» | Від останнього замовлення минуло не менше днів, ніж «Згасає — днів без замовлень» (типово 90) |
| «VIP» | Виручка не менша за «Поріг VIP»; 0 — поріг рахується сам: 5 × середній чек усіх виграних угод |
| «Постійний» | Виграних замовлень не менше, ніж «Постійний — від виграних замовлень» (типово 2) |
| «Новий» | Решта клієнтів із замовленнями |

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

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

## Для ШІ-співробітників
Ключ розділу — `clients` (`describe_section("clients")`). Потрібен доступ «Клієнти».

| Інструмент | Що робить |
| --- | --- |
| `clients_list` | Пошук `q` (назва, особа, телефон, email) і фільтри `source_id`, `responsible_id`, `tags`, `archived`, `segment` (new, regular, vip, fading, lost, none); `sort=revenue_amount` / `profit_amount` / `orders_count` / `last_order_at` / `segment` |
| `clients_get` | Картка клієнта |
| `clients_refs` | Джерела, відповідальні, поля, теги |
| `clients_create` | Новий клієнт: `values` з назвою компанії або ім'ям особи, телефонами, джерелом, обов'язковими полями; передавайте `idempotency_key` |
| `clients_update` | Змінити поля (кожна зміна — у журнал) |
| `clients_add_note` | Нотатка до клієнта |
| `clients_deals` | Угоди клієнта (в роботі й архів) |
| `clients_stats` | Показники: `segment`, `revenue`, `profit` (`profit_partial` — не для всіх позицій є собівартість), `orders`, `avg_check`, `every_days`, `returns`, `payment`, `blackbox`, `by_month` (12 місяців), `by_source`, `by_service` |
| `clients_purchases` | Що бере клієнт: товари виграних і активних угод за сумою (`limit`) |
| `clients_files` | Файли клієнта з мініатюрами; `deals=true` — ще й файли його угод (у рядку `deal`) |
| `clients_stats_settings` | Пороги сегментів і авто-поріг VIP (`vip_auto`); змінює адміністратор у «Сегментах клієнтів» |
| `clients_delete` | Видалити разом з угодами. **Спочатку запитати** (вид `delete`) |
| `clients_addresses` | Адреси доставки клієнта (Нова пошта): `recipient_type`, `company`, `edrpou`, ПІБ, `phone`, `city`, `warehouse`, `is_main`; основна першою |
| `clients_address_suggest` | Заготовка нової адреси з картки контрагента: старий текст «Адреса доставки», назва, ЄДРПОУ, контактна особа, телефон; місто й відділення з останньої ТТН Нової пошти. `from` — звідки кожне поле (`card`, `ttn`, `legacy`) |
| `clients_address_create` | Нова адреса: `values` з `recipient_type` (`private` / `organization`), для організації `company` і `edrpou` (8 цифр), `last_name`, `first_name`, `middle_name`, `phone`, `city` (+ `city_ref` з довідника НП), `warehouse` (номер) або `warehouse_ref`, `label`, `comment`, `is_main`. Перша — основна |
| `clients_address_update` | Змінити адресу (лише змінене); `is_main=true` — зробити основною |
| `clients_address_delete` | Видалити адресу (основною стає наступна). **Спочатку запитати** (вид `delete`) |

ТТН на адресу клієнта: `shipping_create_ttn` з `values.address_id` (без нього — основна адреса, коли в угоді своєї нема); `shipping_prefill` показує `addresses` і яку підставлено (`address_id`).

Інструментів для додаткових контактів, дублів, масових дій, імпорту й експорту поки нема — це робить людина.

Чого не робити:
- Не створювати дубль: спершу шукати за телефоном через `clients_list`.
- Не видаляти клієнта без прямого прохання людини — разом з ним зникають його угоди.
- Не вигадувати id джерел і відповідальних — брати з `clients_refs`.
- Не рахувати виручку й прибуток самому з угод — брати `clients_stats` (там ті самі правила, що бачить людина).

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Завдання](tasks.md), [Документи](documents.md), [Імпорт і експорт](import-export.md).


---

# Завдання

Завдання (задача) — дія з терміном і відповідальним: подзвонити, надіслати рахунок, перевірити оплату. Задачу можна прив'язати до угоди або клієнта, дати їй тип, пріоритет, чек-лист, нотатки й файли; усі задачі з карток угод і клієнтів збираються в одному розділі «Завдання».

## Можливості
- Один список усіх задач з угод, клієнтів і вільних; блок «Завдання» в картці угоди й вкладка «Задачі» в картці клієнта.
- Три вигляди: «Дошка» (по днях або по статусах, з перетягуванням), «Список», «Архів»; вид за замовчуванням обираєте ви.
- Типи завдань з іконками; тип підставляє назву задачі.
- Статуси «У роботі», «Відкладено», «Виконано»; пріоритети «Терміновий», «Високий», «Звичайний», «Низький».
- Червона цифра біля пункту меню «Завдання»: ваші задачі на сьогодні й прострочені.
- Швидке створення з будь-якої сторінки — Alt+Shift+T.
- Масові дії з вікном прогресу; доступ «лише свої / усі».
- Задача автоматично, коли угода приходить на етап.
- Імпорт і експорт XLSX у форматі KeepinCRM.

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

## 2. Створити завдання
1. У розділі «Завдання» натисніть «+» (або Alt+Shift+T на будь-якій сторінці). У картці угоди — «+» у блоці «Завдання», у картці клієнта — на вкладці «Задачі».
2. Заповніть назву (або виберіть тип — назва підставиться), головного відповідального (типово ви), дату й час завершення, статус, за потреби пріоритет, контакт, коментар і додаткові поля.
3. У розділі «Завдання» в полі «Угода або клієнт» знайдіть, до чого прив'язати задачу, або залиште її вільною.
4. Збережіть. Задача з'явиться в списку, у картці угоди чи клієнта і в журналі.

## 3. Знайти свої задачі: список, фільтри, лічильник
1. Відкрийте «Завдання» → «Список».
2. Швидкі фільтри: «Усі активні», «Прострочені», «На сьогодні». Кнопка «Прострочено: N» у шапці теж відкриває прострочені.
3. Пошук: назва, опис, клієнт, угода, телефон.
4. «Фільтри»: статус, відповідальний, «Лише мої», тип, пріоритет, дата завершення від і до, додаткові поля.
5. У «⋮» шапки: «Налаштування колонок», «Імпорт», «Експорт», «Налаштувати поля», «Зробити «…» видом за замовчуванням».
6. У «⋮» рядка: «Редагувати», «Відкрити», «Завершити», «Видалити».

Прострочена задача позначена червоною смужкою; термін — червоним.

## 4. Дошка
- «Дошка» → «По днях»: колонки «Прострочені», «Сьогодні», «Завтра», наступні дні, «Пізніше», «Без терміну». Перетягніть картку в іншу колонку — дата завершення зміниться.
- «По статусах»: перетягування міняє статус.
- Сортування карток — за терміном або за відповідальними.

## 5. Сторінка завдання
«⋮ → Відкрити» або «Відкрити сторінку завдання →» веде на окрему сторінку: усі поля (значення змінюються на місці), прив'язка до угоди чи клієнта (змінити або «Прибрати угоду» / «Прибрати клієнта»), чек-лист (новий пункт і Enter, порядок перетягуванням), нотатки, файли (квадратики-прев'ю, як в угоді), «Історія» всіх змін.

## 6. Завершити і повернути в роботу
- Галочка в рядку, «⋮ → Завершити» або кнопка «Завершити» з галочкою на сторінці задачі ставить статус «Виконано», і задача переходить в «Архів».
- В «Архіві» — «⋮ → Відновити» або «Відновити» на сторінці задачі повертає її в роботу.

## 7. Масові дії
1. У «Списку» позначте задачі галочками.
2. На панелі: «Завершити», «Статус», «Відповідальний», «Дод. поле» (встановити або очистити), «Видалити». В «Архіві» — лише «Видалити».
3. Вікно прогресу показує «Опрацьовано N з M» і підсумок; задачі з помилками — посиланнями.

Без доступу «Завдання: масові дії» галочок нема, а замість панелі — пояснення.

## 8. Завдання автоматично на етапі угоди
1. «Налаштування → Воронки й етапи» → у рядку етапу кнопка «завдання».
2. Вкажіть тип або назву завдання, термін «через N годин», відповідального (відповідальний угоди, хто перевів угоду, або конкретна людина) і коментар.
3. Щойно угода приходить на цей етап, по ній створюється задача.

## 9. Імпорт і експорт
«⋮ → Імпорт» (потрібен доступ до масових дій) і «⋮ → Експорт». Дублі при імпорті шукаються за назвою завдання. Покроково — стаття «Імпорт і експорт».

Нагадувань і push-сповіщень про задачі поки нема: поле нагадування API приймає і зберігає, але воно ніде не спрацьовує.

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

## Для ШІ-співробітників
Ключ розділу — `tasks` (`describe_section("tasks")`). Потрібен доступ «Завдання».

| Інструмент | Що робить |
| --- | --- |
| `tasks_list` | Список з `q` і фільтрами `status` (`open`, `overdue`, `today`, `done`, `in_work`, `postponed`, `all`), `responsible_id`, `mine`, `overdue`, `due_from`, `due_to`, `deal_id`, `client_id` |
| `tasks_get` | Одна задача |
| `tasks_refs` | Відповідальні, статуси, типи, поля |
| `tasks_create` | Нова задача: `values` з `title`, `due_at`, `assignee_id`, за потреби `deal_id` чи `client_id`, `type_id`, `priority`; передавайте `idempotency_key` |
| `tasks_update` | Змінити або закрити задачу: `status` = `done` завершує, новий `due_at` переносить термін |
| `tasks_delete` | Видалити задачу. **Спочатку запитати** (вид `delete`) |

Задачу по угоді можна створити й інструментом `deals_add_task`. Інструментів для чек-листа, нотаток задачі, масових дій, імпорту й експорту поки нема.

Чого не робити:
- Не ставити задачу людині, якої нема в `tasks_refs`.
- Не видаляти чужі задачі без прохання людини.
- Не повторювати дію з `pending_id` — вона чекає підтвердження.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Клієнти](clients.md), [Імпорт і експорт](import-export.md).


---

# Дашборд продажів

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

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

## 1. Налаштування
Доступ дає адміністратор: «Налаштування» → «Розділи» → «Дашборд продажів». Людина бачить лише те, що й у рідних розділах: переписки своїх каналів, свої скриньки пошти, угоди тих воронок, які їй відкриті.

Пороги черги налаштовує адміністратор (або людина з доступом «Налаштування CRM»): «⋮» у шапці → «Налаштувати дашборд».
- «Угоди»: етапи яких ролей вважати «до збірки» (типово `new, accepted`), через скільки хвилин угода без руху потрапляє в смугу (типово 180), за скільки днів брати угоди (21), коли угода на «Допомозі» стає тривогою (180 хв).
- «Посилки»: з якого дня на відділенні дзвонити клієнту (4), коли посилка «застрягла» (5 днів без сканування), з якої години нагадувати «обіцяв забрати» ввечері передостаннього дня (17).
- «Переписки й пошта»: коли клієнт «довго чекає» (120 хв), листи за скільки днів (30).
- «Вигляд»: скільки карток максимум у смузі (40).
- «Повернення»: причини повернення — по одній у рядку.
Змінили — дашборд рахує так з наступного оновлення, без перезапуску. Кожна зміна записується в журнал з автором.

Дні безкоштовного зберігання, комісія за повернення й «ТТН створена, посилку не віддали службі» — це налаштування ШІ Ростіка («Налаштування» → «Інтеграції» → «ШІ» → «Ростік»), їх використовують і «Доставки», і дашборд.

## 2. Що на екрані
1. Головне меню → «Відділ Продажу» → «Дашборд продажів» (адреса `/crm/sales`; стара `/sales` відкриває цю ж сторінку).
2. Під назвою — пігулки смуг з числами; червона крапка — у смузі є прострочене. Натисніть пігулку — сторінка прокрутиться до смуги.
3. Порожні смуги згортаються в рядок «Чисто:» унизу; натисніть назву — смуга відкриється.
4. «Показати ще» розгортає смугу повністю (у ній до 40 карток, решта — у рідному розділі за посиланням угорі смуги).

На телефоні все в один стовпець: пігулки смуг гортаються пальцем, кружечки дій стоять під текстом рядка праворуч.

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

Кружечок «Відкрити угоду» відкриває картку угоди. Роль етапу задають у «Налаштування» → «Воронки й етапи».

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

Відмітки не змінюють етапів угод і статусів посилок — лише кажуть, що відділ продажу з цим закінчив.

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

## Можливі помилки
| що видно | чому | що зробити |
| --- | --- | --- |
| «Немає доступу до розділу «Дашборд продажів»» | розділ не відкрито | попросіть адміністратора: «Налаштування» → «Розділи» |
| Угоди на «Допомозі» не з'являються | етапу не задано роль «Допомога» | «Налаштування» → «Воронки й етапи» → роль етапу |
| «Невідома причина повернення» | причину прибрали з налаштувань, поки був відкритий дашборд | оновіть сторінку й виберіть причину зі списку |
| «Налаштування дашборда змінює адміністратор…» | у вас нема доступу «Налаштування CRM» | налаштування видно для читання; змінює адміністратор |
| «Канал не синхронізується: Доставки» | крок Ростіка давно не звіряв статуси | пульт Ростіка → «Запустити крок» або перевірте, чи він увімкнений |

## Для ШІ-співробітників
Розділ у каталозі — `sales` (доступ — галочка «Дашборд продажів» у «Доступах»). Інструменти:
- `sales_counts` — лічильники смуг і «треба зробити»;
- `sales_lane` — картки однієї смуги з лімітом (`kind`: reply, mail, help, unsent, call, returns, stuck, missed; `include_seen=yes` — разом із переглянутими);
- `sales_summary` — увесь дашборд одним запитом (важкий; для однієї смуги — `sales_lane`);
- `sales_mark` — «Переглянуто» (`state=seen`) або «Розібрав» (`state=done`) з коментарем і причиною повернення; беріть `mark_kind` і `mark_ref` з картки, не вигадуйте; `clear=true` — зняти відмітку;
- `sales_settings` — налаштування дашборда (лише читання: налаштування компанії змінює людина).
Відмітка ШІ підписана його іменем у журналі; коментар стає нотаткою в угоді. Не ставте «Розібрав» на те, що не зроблено насправді.

## Додаткова інформація
- [Угоди](deals.md), [Доставка](deliveries.md), [ШІ Ростік](ai-rostik.md).


---

# Переписки

Переписки — один список усіх чатів з клієнтами з різних каналів: OLX, Telegram, Prom, Rozetka, Viber і чатів на сайтах. Менеджер бачить, де клієнт чекає відповіді, відповідає звідси ж у той самий канал, розкладає чати по папках і користується збереженими шаблонами відповідей.

## Можливості
- Канали: OLX, Telegram, Prom, Rozetka, Viber, сайти; лічильники по кожному джерелу.
- Два режими: по джерелах або всі підряд — за часом останнього повідомлення.
- Будь-який чат відкривається в новій вкладці (Ctrl-клік, середня кнопка, правий клік) — у кожного своя адреса.
- «Непрочитано» — остання репліка від клієнта без відповіді і без позначки «Оброблено».
- Відповідь клієнту в той самий канал.
- Особисті папки з можливістю поділитися.
- Збережені шаблони відповідей.
- Доступ людей до окремих каналів.
- Стан підключення кожного каналу (живий чи з помилкою).

## 1. Налаштування
- **Канали** підключаються в «Інтеграціях» (Telegram, Viber, OLX, Prom, Rozetka, сайти) — див. статті цих інтеграцій. Для Rozetka чати «запитання до продавця» вмикаються в «Налаштування продажів» картки Rozetka.
- **Доступ до розділу** — галочка «Переписки» у «Налаштування → Розділи меню».
- **Доступ до каналів по людях** — там само, у «Розділах меню» (канали «Переписок»). Поки адміністратор не обмежив людину, вона бачить усі канали; адміністратор бачить усі завжди.
- Розділ працює на ключах сервера й даних першої організації: в інших організаціях платформи він поки закритий навіть адміністратору.

## 2. Знайти чат, що чекає відповіді
1. Відкрийте «Переписки».
2. Виберіть джерело або всі підряд. Чати, що чекають відповіді, позначено як непрочитані.
3. Пошук — за іменем, телефоном або текстом.
4. Щоб відкрити чат у новій вкладці, натисніть рядок із затиснутим Ctrl (на Mac — ⌘), середньою кнопкою миші або правою
   кнопкою → «Відкрити посилання в новій вкладці». Кожен чат має свою адресу (`/inbox/<номер чату>`), тож вкладку можна
   оновити чи надіслати колезі. Звичайний клік відкриває чат праворуч, як і раніше. Кнопка «✓» у рядку лише знімає позначку
   «без відповіді» і чат не відкриває.

## 3. Відповісти клієнту
1. Відкрийте чат.
2. Напишіть текст у полі внизу і натисніть «Надіслати». Повідомлення піде в той самий канал (Telegram, Viber, Prom, Rozetka, OLX чи сайт).
3. Для OLX і Viber відповідь іде через чергу зовнішнього сервісу каналу — вона з'явиться в клієнта після наступного прогону сервісу.

На телефоні поле відповіді — скляна смуга внизу з чорною «Надіслати»; при відкритій клавіатурі нижнє меню й кнопка ШІ ховаються.

## 4. Оброблено, заглушити
- «Оброблено» — чат більше не рахується непрочитаним, хоча відповіді в канал не було.
- «Заглушити» — чат не турбує сповіщеннями; повторна дія розглушує.

## 5. Папки
Створіть особисту папку, додавайте в неї чати, перейменовуйте, видаляйте. Папкою можна поділитися з колегами.

## 6. Шаблони відповідей
Збережіть типову відповідь шаблоном і вставляйте її в поле відповіді. Шаблони можна змінювати й видаляти.

## 7. Переписки з картки угоди
У картці угоди вкладка «Чати» відкриває «Переписки» з пошуком за телефоном клієнта угоди.

## 8. Номер замовлення відкриває угоду
У чатах Prom і Rozetka номер замовлення — посилання. Він є в трьох місцях: у панелі «Про клієнта» (рядок «Номер»), у шапці чату і в рядку списку чатів. Натисніть номер — у новій вкладці відкриється угода цього замовлення в розділі «Угоди». Клік по номеру в списку не відкриває сам чат.

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

Доручити чат ШІ-співробітнику прямо зі сторінки «Переписок» поки не можна.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| Каналу нема в списку | Канал не підключено або вам закрито доступ до нього | Підключіть канал в «Інтеграціях» або попросіть доступ |
| Канал позначено помилкою | Сервіс каналу давно не надсилав пульс | Перевірте підключення в «Інтеграціях» |
| Відповідь не дійшла в OLX чи Viber | Черга зовнішнього сервісу ще не оброблена або повернула помилку | Зачекайте прогону сервісу; перевірте його стан |
| Номер замовлення відкрив «Угоди із замовленням … не знайдено» | Замовлення ще не прийшло з майданчика, або угоду створено вручну з іншою назвою без поля «№ замовлення» | Зачекайте кілька хвилин; знайдіть угоду пошуком в «Угодах» і впишіть номер у її назву або поле «№ замовлення» |
| Номер відкрив «Немає доступу до воронки» | Угода в воронці, яку вам не відкрито | Попросіть адміністратора відкрити воронку в «Налаштуваннях → Воронки» |
| Розділу нема в меню | Розділ закритий у вашій організації або не відкрито доступ | Зверніться до адміністратора |

## Для ШІ-співробітників
5`. Надсилання клієнтам належить до дій, що **спочатку запитують** людину (вид `outbound`), коли такі інструменти з'являться.

Зовнішні сервіси каналів передають чати через `POST /api/inbox/ingest` з ключем `X-Inbox-Key` — це шлях для програм-полерів, а не для ШІ-співробітників.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Клієнти](clients.md); інтеграції Telegram, Viber, OLX, сайти — статті `int-*`.


---

# Телефонія

«Телефонія» — дзвінки з робочого телефона компанії без платної АТС: застосунок Helomi на телефоні зливає сюди журнал дзвінків робочої SIM і записи розмов, а розділ показує їх списком зі статистикою, порадами й телефонною книгою. Кожен дзвінок зіставляється з клієнтом нашої CRM і його останньою угодою, а в картку угоди (або клієнта) лягає нотатка про дзвінок.

## Можливості
- Журнал дзвінків робочої SIM з телефона: вхідні, вихідні, пропущені, з записами розмов; стан передзвону для пропущених.
- Ім'я клієнта, його картка й остання угода в нашій CRM — за номером телефону (телефони клієнта, додаткових контактів, одержувача посилки).
- Нотатка про кожен дзвінок у картці угоди клієнта, а без угоди — у картці клієнта; видно в «Нотатках» і в журналі картки.
- Вкладка «Контакти»: телефонна книга з клієнтів нашої CRM плюс свої записи й зірочки.
- Статистика по днях, годинах, лініях і клієнтах; поради за правилами (не передзвонили, пік дзвінків, короткі розмови).
- Кнопка «Набрати» з комп'ютера — телефон сам починає дзвінок з робочої SIM.
- Дзвінок у клік по всій CRM: номер у картці угоди, клієнта, контакту, у завданнях, «Дашборді продажів», картці колеги в «Структурі» й у «Користувачах» — клік, і ваш робочий телефон сам набирає номер.
- Ломі набирає номер на ваше прохання («набери клієнта угоди 50000375») — з вашого робочого телефона або з лінії, яку назвали.

## 1. Налаштування
Доступ дає адміністратор: «Налаштування» → «Розділи» → «Телефонія». Без доступу розділ не відкривається, а телефон цієї людини не зливає журнал.

Робочі номери: «Телефонія» → «Номери» → «Додати номер» (адміністратор). Прив'яжіть лінію до людини, щоб «Набрати» знав, з якого телефона дзвонити; на телефоні один раз оберіть робочу SIM у розділі «Телефонія».

Нотатки й зіставлення налаштовує адміністратор або людина з доступом «Налаштування CRM» (`PUT /api/telephony/settings`; форма в інтерфейсі — у черзі робіт):
- «Писати нотатку про дзвінок у картку угоди клієнта» (типово так).
- «Якщо угоди нема — писати в картку клієнта» (так).
- «Писати й про дзвінки без відповіді» (так) — пропущені й «не додзвонилися».
- «Нотатки лише для дзвінків не старших за, днів» (3) — щоб давні дзвінки після дозіставлення не перетирали останню нотатку угоди.
- «Дозіставляти дзвінки без клієнта чи угоди за останні, днів» (14) — замовлення з площадки приходить уже після дзвінка.
Змінили — діє з наступного синку телефона, без перезапуску. Кожна зміна записується в журнал з автором.

## 2. Дзвінки і клієнти
1. Відкрийте «Телефонія» на телефоні — застосунок зіллє журнал робочої SIM (повторно можна скільки завгодно, дублів не буде).
2. У списку на комп'ютері з'являться дзвінки з ім'ям клієнта і кнопкою угоди. Ім'я береться так: свій запис у «Контактах» → клієнт нашої CRM за телефоном (телефони клієнта, додаткові контакти, об'єднані дублі → основна картка) → одержувач у блоці «Доставка» угоди.
3. Угода в рядку — остання неархівна угода цього клієнта; кнопка відкриває її картку в «Угодах» (`/crm/deals/<id>`).
4. Якщо клієнт з'явився в CRM уже після дзвінка, дзвінок дозіставиться сам при наступному синку (за налаштуванням «Дозіставляти…»).

## 3. Нотатки про дзвінки в картках
Після кожного синку телефона нові дзвінки клієнтів лягають нотатками в картку угоди: «Телефонія: вхідний дзвінок 18.10.2026 14:05 від +380… на +380… «Продажі» — розмова 2 хв 10 с». Пропущений — «без відповіді, треба передзвонити», вихідний без відповіді — «не додзвонилися»; якщо є запис — «Запис розмови — у розділі «Телефонія»». Автор нотатки — «Телефонія» з позначкою бота; та сама подія — у журналі картки. Без угоди нотатка іде в картку клієнта (якщо увімкнено). Один дзвінок — одна нотатка, повторів нема.

## 4. Контакти
Вкладка «Контакти» об'єднує клієнтів нашої CRM (телефони клієнта і додаткових контактів — «ПІБ контакту (Клієнт)») і свої записи. Перейменували клієнта тут — ім'я одразу підтягнеться в дзвінки, а в CRM картка не змінюється. Зірочка збирає вибрані номери у вкладку «Вибрані» в дзвінках.

## 5. Набрати з комп'ютера
Кнопка «Набрати» в рядку дзвінка чи контакту: сервер шле команду в застосунок на робочому телефоні (або у вебхук телефона, якщо вписали в «Номерах»), телефон починає дзвінок з робочої SIM. Журнал дзвінка приїде наступним синком.

Команда йде на телефон **власника лінії** — там стоїть робоча SIM. Лінія колеги сама не підставляється: якщо своєї лінії нема, а в компанії лише лінії, прив'язані до інших людей, клік не змусить дзвонити чужий телефон. Ні до кого не прив'язана єдина лінія — спільна, нею користуються всі.

## 6. Дзвінок у клік з будь-якого розділу
Номер телефону в CRM — кнопка (власник 22.10.2026: «нажати на телефон і дзвонити з того номера, який прив'язаний до цього аккаунта»):
1. Прив'яжіть свою лінію до себе: «Телефонія» → «Номери» → лінія → людина (адміністратор). На робочому телефоні відкрийте Helomi, дозвольте сповіщення й дзвінки і один раз оберіть робочу SIM.
2. Натисніть номер у картці угоди, клієнта, додаткового контакту, у списку завдань, на «Дашборді продажів» (кружечок з трубкою), у картці колеги в «Структурі» чи в «Користувачах». Підказка під курсором — «Подзвонити … з лінії «Продажі»».
3. Тост «Телефон набирає +380… з лінії «Продажі»» — телефон уже дзвонить, лишається взяти його й говорити. Поки команда йде, номер притишений і другий натиск нічого не шле.

Якщо лінії нема чи «Телефонію» закрито, номер працює як звичайне посилання `tel:`: на телефоні відкриється набір, на ПК — програма для дзвінків (наприклад, «Зв'язок із телефоном» Windows). Помилка (телефон не підписаний, вебхук не відповів) лишається тостом, поки його не закриють.

## 7. Ломі набирає на прохання
Попросіть Ломі в чаті: «набери клієнта угоди 50000375», «подзвони Марії Клієнт», «набери 050 111 22 33 з лінії Продажі». Ломі знаходить номер і набирає його на **вашому** робочому телефоні (лінія, прив'язана до вас), або з лінії, яку ви назвали. Дзвінок починається одразу, бо дзвонить ваш телефон за вашим проханням; якщо ШІ працює з «Спершу запитати» (дії лише після підтвердження), набір чекає в кошику, а після «Підтвердити» дзвонить телефон того, хто просив, а не того, хто підтвердив. Так само працює Остап — ваш власний чат (Claude, ChatGPT, Kimi, Gemini) з файлом сесії: дзвонить телефон людини, яка створила цей файл. Без людини (сам по собі, за розкладом, зовнішня програма за ключем) ШІ номер не набирає. У журналі ШІ — запис, хто попросив.

## Можливі помилки
| Як показується | Чому | Що зробити |
| --- | --- | --- |
| «Немає доступу до розділу «Телефонія»» | Розділ не відкрито цій людині | «Налаштування» → «Розділи» → увімкнути «Телефонія» |
| У дзвінку нема імені та угоди | Номера нема серед телефонів клієнтів і доставок | Додайте телефон у картку клієнта або запис у «Контакти»; дзвінок дозіставиться наступним синком |
| Нотатка про дзвінок не з'явилась | Дзвінок старший за «Нотатки лише для дзвінків не старших за» або нотатки вимкнено | Перевірте «Налаштування телефонії»; давні дзвінки нотатками не дублюються навмисно |
| «Нема куди слати команду» при «Набрати» | Телефон не підписаний на сповіщення й без вебхука | Відкрити Helomi на робочому телефоні, дозволити сповіщення й дзвінки, або вписати вебхук у «Номерах» |
| «Налаштування телефонії змінює адміністратор…» | Нема доступу «Налаштування CRM» | Попросити адміністратора |
| Номер відкриває програму ПК замість дзвінка з телефона | До вас не прив'язано лінію або телефон без застосунку Helomi | «Телефонія» → «Номери»: прив'язати лінію; на телефоні — Helomi зі сповіщеннями |
| «ШІ набирає номер лише на прохання людини…» | ШІ кличе набір без людини (цикл агента, MCP) | Попросіть ШІ в чаті Ломі — дзвонитиме ваш телефон |

## Для ШІ-співробітників
Розділ у каталозі — `describe_section("telephony")` (доступ — розділ «Телефонія» у «Доступах» ШІ):
- `telephony_dial values={number, line_id?, agreement_id?}` — набрати номер на робочому телефоні людини, яка попросила в чаті (її лінія або `line_id`). Без людини — 403: набирати лише на прохання. Права — людини: якщо їй «Телефонію» закрито, набору нема.
- `telephony_lines` — робочі номери (id, назва, чия, чи готова до набору з ПК) — щоб набрати «з лінії Продажі».
- `telephony_calls tab=missed|incoming|outgoing|recorded|starred q=…` — журнал дзвінків з клієнтом і угодою.
- `telephony_client_calls number=…` — історія дзвінків з одним номером.

Нотатки «Телефонії» видно в картках угод і клієнтів через звичайні інструменти угод (`deals_*`) — рядки від автора «Телефонія» з позначкою бота. Налаштування телефонії й лінії ШІ не змінює (ПРАВИЛА §5).

## Додаткова інформація
- «Угоди» (`deals.md`), «Клієнти» (`clients.md`), «Дашборд продажів» (`sales.md` — смуга «Пропущені дзвінки» бере дані звідси).