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

# Клієнти

Клієнт (контрагент) — компанія або людина з телефонами, 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).