> Усі статті WIKI Helomi: /wiki/llms.txt

# Угоди

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

## Можливості
- Список угод з пошуком за назвою, номером, ТТН, телефоном і клієнтом; фільтри за воронкою, етапом, джерелом, брендом, відповідальним, періодом, протермінуванням і додатковими полями.
- Два вигляди: «Таблиця» і «Канбан» з перетягуванням; останній вибір запам'ятовується. Номер і назва угоди — справжні посилання: клік відкриває картку тут, 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).