# Інтеграції — WIKI Helomi

> Маркетплейси, сайти, перевізники, банки й оплати, повідомлення: підключення кількох акаунтів і що вони дають.


---

# Інтеграції — вхід для ШІ

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

Категорії каталогу («Усі», «Маркетплейси», «Сайти», «Перевізники», «Оплати», «Повідомлення», «ШІ», «Інше») стоять в одному ряду; коли він не влазить у вікно, гортайте його стрілками ‹ › по краях, коліщатком миші над рядом, перетягуванням мишею або пальцем на телефоні.

## Можливості
- ШІ бачить картки «Інтеграцій» зі станом: приєднано, увімкнено, чого бракує (лише назви ключів), остання помилка, журнал картки.
- ШІ читає налаштування Нової Пошти, Укрпошти, Meest і Rozetka Delivery як у формі: акаунти-відправники, «Пов'язані статуси», «Пов'язані типи оплат та статуси», «Пов'язані поля», доступи, дефолти ТТН.
- ШІ натискає «Перевірити» в акаунті перевізника — ключем акаунта, не бачачи його.
- З доступом «Налаштування інтеграцій» ШІ пропонує зміну (наприклад, інший етап для статусу «Відправлення доставлено»), додає чи прибирає акаунт; зміна чекає «Підтвердити» адміністратора 24 години.
- У картці підтвердження видно, що саме зміниться: рядки, етапи з назвами воронок, акаунти, які зникнуть разом із ключами.
- Кожна застосована зміна — у журналі картки з підписом «ШІ <ім'я> · підтвердив <адміністратор>».

## 1. Налаштування
Робить адміністратор.

Де розділ: «Налаштування» → група «Інтеграції» → «Усі інтеграції» (з 16.10.2026 пункту «Інтеграції» в головному меню нема). Там само «Вхідні вебхуки». Старі посилання на сторінки інтеграцій (`/crm/integrations/…`) працюють: адміністратора вони переводять у «Налаштування», а людина з галочкою «Інтеграції» без прав адміністратора бачить сторінку за старою адресою.

1. «Налаштування» → «Інтеграції» → вкладка «ШІ» → плитка ШІ-співробітника → «Налаштувати» (відкривається пульт) → вкладка «Доступи».
2. «Розділи» → галочка «Інтеграції» — ШІ бачить картки й налаштування перевізників (лише читання й «Перевірити»).
3. «Інтеграції» → галочка «Налаштування інтеграцій» — ШІ може пропонувати зміни налаштувань перевізників. Разом із нею ставиться і галочка розділу «Інтеграції».
4. «Зберегти доступи». Діє з наступного запиту ШІ.

«Спочатку запитати» для інтеграцій не вимикається: зміна інтеграції змінює потік замовлень, тому її завжди підтверджує людина-адміністратор. Агенти, яких створив сам ШІ, цього доступу не отримують.

Дозвіл дається кожному ШІ-співробітнику окремо, і діє однаково, хоч би як він зайшов: Ломі (екран, чат у пульті, ваш Claude чи ChatGPT з її файлом сесії), «Claude · сесія» та інші співробітники «… · сесія» із загального файлу сесії, ваш агент через MCP чи REST. Без галочки інструментів інтеграцій у нього нема, а спроба викликати їх отримує відмову «розділ закрито у «Доступах» цього ШІ». Файл сесії, створений до видачі дозволу, перелічує старі інструменти — створіть його заново; сам токен бачить нові інструменти одразу.

Що бачить і що може ШІ саме тут — «Інтеграції» → «⋮» → «Вхід для ШІ»: інструменти з описами, поля, адреса MCP і «Файл сесії».

## 2. ШІ читає налаштування перевізника
Попросіть ШІ, наприклад: «Подивись налаштування Meest — які статуси куди ведуть». ШІ відкриває ті самі дані, що й форма «Інтеграції» → «Перевізники» → «Meest» → «Налаштування»: акаунти з дефолтами, доступи, «Пов'язані статуси», поля угоди. Замість ключів він бачить лише «задано / не задано» й останні чотири символи (`••••1234`).

## 3. ШІ пропонує зміну, адміністратор підтверджує
1. Ви просите ШІ: «У Meest статус "Відправлення доставлено" має вести на етап "Отримано"».
2. ШІ готує зміну тим самим маршрутом, що й кнопка «Зберегти» форми, але вона не застосовується: ШІ отримує відповідь «чекає підтвердження» і каже вам про це.
3. У пульті цього ШІ → «Огляд» → «Чекають підтвердження» з'являється картка: «Meest: змінити налаштування» і рядки, наприклад «Пов'язані статуси: «Відправлення доставлено» — етап «Відправлено» (Продажі) → етап «Отримано» (Продажі)». Підпис — «зміна інтеграції — підтверджує адміністратор».
4. «Підтвердити» (лише адміністратор) — зміна зберігається з тими самими перевірками, що й у формі (етап існує, користувач існує, поле угоди існує); у журналі картки Meest з'являється «налаштування перевізника збережено (ШІ <ім'я> · підтвердив <ви>)». «Відхилити» — нічого не змінюється.

Так само ШІ додає акаунт-відправника (ключі до нього потім вписує людина), прибирає акаунт (картка попередить: «акаунт зникне разом із його ключами») і створює список відправлень Укрпошти.

## 4. Ключі й токени
`NP_API_KEY`, `MEEST_TOKEN`, `MEEST_CONTRACT_ID`, `UP_BEARER`, `UP_BEARER_TRACKING`, `UP_TOKEN`, `RZ_LOGIN`, `RZ_PASSWORD`, `RZ_STATIC_TOKEN` вписує лише людина-адміністратор у полях акаунта у формі перевізника. Інструмента для ключів у ШІ нема, маршрут ключів відмовляє ШІ навіть із підтвердженням, а налаштування, які бачить ШІ, ключів не містять. Якщо для роботи бракує ключа, ШІ назве, який саме ключ і в якому акаунті вписати.

Картки маркетплейсів і сайтів ШІ бачить лише в загальному списку зі станом: адреса вебхука сайту (з токеном), ключі каналів і перемикач приймання замовлень — тільки для людини.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Інструмент «integrations_…» недоступний: розділ закрито у «Доступах» цього ШІ» | Немає галочки «Інтеграції» або «Налаштування інтеграцій» | Адміністратор ставить галочку в «Доступах» пульта ШІ |
| «Зміни налаштувань інтеграцій підтверджує адміністратор» | «Підтвердити» натиснула людина, яка не адміністратор | Попросіть адміністратора |
| «Зміну інтеграції від ШІ застосовує лише «Підтвердити» адміністратора в пульті ШІ» | Спроба змінити налаштування повз підтвердження | Нічого не робити: так і має бути |
| «Ключі й токени вписує людина в полях форми — ШІ їх не вводить» | ШІ спробував записати ключ | Ключ вписує адміністратор у формі перевізника |
| «Етапу не існує: …» / «Поля угоди не існує: …» | ШІ запропонував етап чи поле, яких нема | Відхиліть дію й уточніть ШІ етап або поле |
| «Строк підтвердження минув (24 год)» | Дію не підтвердили вчасно | Попросіть ШІ повторити |

## Для ШІ-співробітників
Ключ розділу — `integrations` (`describe_section("integrations")`). Читання — доступ «Інтеграції»; зміни — ще й доступ «Налаштування інтеграцій».

| Інструмент | Що робить |
| --- | --- |
| `integrations_list` | Картки зі станом: `kind`, назва, група, увімкнено, приєднано, `missing` (назви ключів), остання помилка; у перевізників — `carrier`, `carrier_accounts` |
| `integrations_log` | Журнал картки (`kind`, `limit`) |
| `integrations_carrier_get` | Налаштування перевізника (`kind`: `nova_poshta`, `ukrposhta`, `meest`, `rozetka_delivery`): `settings` і `options` (воронки з етапами, користувачі, поля угоди, статуси служби, типи оплат). Ключі — лише `{set, hint}` |
| `integrations_carrier_statuses` | Статуси служби для «Пов'язаних статусів» |
| `integrations_carrier_np_senders` | Нова Пошта: відправники й контактні особи ключем акаунта (`key`) |
| `integrations_carrier_check` | «Перевірити» акаунт (`kind`, `key`): `{ok, message, sender}` |
| `integrations_carrier_update` | Змінити налаштування: `values` — лише ключі, які змінюєте; списки (`status_map`, `payment_status_map`, `accounts`) — **цілком**, як у `integrations_carrier_get`. **Завжди чекає «Підтвердити» адміністратора** |
| `integrations_carrier_account_add` | Новий акаунт (`values.name`). **Чекає підтвердження** |
| `integrations_carrier_account_delete` | Прибрати акаунт (`key`) разом із ключами. **Чекає підтвердження** |
| `integrations_carrier_list_create` | Укрпошта: список відправлень (`values.name`, `type`, `account`). **Чекає підтвердження** |

SMS (TurboSMS) — окремий розділ каталогу `sms` з інструментами `sms_*` (налаштування кабінету, перегляд тексту, відправка через «спочатку запитати», журнал і статуси доставки; підписи й шаблони — з тим самим доступом «Налаштування інтеграцій» і «Підтвердити» адміністратора): [SMS (TurboSMS)](int-sms.md).

Як змінити етап у «Пов'язаних статусах»: `integrations_carrier_get` → взяти `settings.status_map` → змінити `stage_id` потрібного рядка на id етапу з `options.funnels[].stages[]` → `integrations_carrier_update` з `values: {"status_map": <увесь список>}` → отримати `pending_id` і сказати людині, що зміна чекає підтвердження в пульті.

Чого не робити:
- Не просити людину надіслати ключ у чат і не намагатися його записати — скажіть, який ключ і в якому акаунті вписати у формі.
- Не надсилати частину списку: рядок `status_map` чи акаунт, якого нема у `values`, буде прибрано (акаунт — разом із ключами).
- Не вигадувати `stage_id`, `access_user_ids`, ключі полів угоди — брати з `options`.
- Не повторювати дію, що вже чекає підтвердження (`pending_actions`).

## Додаткова інформація
- Пов'язані статті: [SMS (TurboSMS)](int-sms.md), [Нова Пошта](int-nova-poshta.md), [Укрпошта](int-ukrposhta.md), [Meest](int-meest.md), [Rozetka Delivery](int-rozetka-delivery.md), [ШІ-співробітники](ai-employees.md), [Доставки і ТТН](shipping.md).


---

# Prom

Інтеграція з Prom приймає замовлення з вашого кабінету Prom прямо в «Угоди»: клієнт знаходиться за телефоном або створюється, товари зв'язуються зі складом, доставка й оплата лягають у картку угоди. Через Prom приходять і угоди магазинів Rozetka, що працюють через Prom; переписки з покупцями йдуть у «Переписки», а залишки й ціни можна оновлювати на Prom зі свого складу.

## Можливості
- Нові замовлення Prom (статуси «Новий» і «Прийнято») опитуються кожні 5 хвилин і стають угодами; повторне надходження того самого замовлення дубля не створює, а оновлює статус і додаткові поля.
- Джерело й відповідальний для угод каналу, зв'язок позицій з товарами за артикулом, ID маркетплейсу або назвою.
- Таблиця «Пов'язані статуси»: статус Prom → етап угоди; скасовані замовлення йдуть на етап скасування з причиною.
- «Передавати етап назад на маркетплейс»: менеджер рухає угоду — статус на Prom змінюється сам.
- Автоприйняття «Новий» → «Прийнято» через N хвилин, автоматична ТТН на вибраних етапах.
- Чати про товари й замовлення в «Переписках», оператори чату.
- Оновлення залишків і цін на Prom зі складу і адреса фіду товарів.
- Кілька кабінетів Prom: кожен зі своїм ключем, налаштуваннями й журналом.

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Маркетплейси» → картка «Prom».

1. **Ключ.** У картці відкрийте вкладку «Підключення» → рядок «API ключ» → «Ввести» (або «Змінити»), вставте токен і натисніть «Зберегти ключ». Токен створюється в кабінеті Prom у налаштуваннях API. Ключ зберігається зашифрованим і більше ніде не показується повністю — лише останні символи («задано (••••1234)»). «Прибрати» стирає ключ з CRM; тоді діє значення з налаштувань сервера, якщо воно там є.
2. **Перевірка.** «Перевірити» робить безпечний запит лише на читання. Успіх — «Зв'язок є: доступ до замовлень є» з часом; помилка — текст від Prom.
3. **Налаштування продажів.** Друга вкладка картки — «Налаштування продажів». Блоки:
   - «Основне»: перемикач «Увімкнути інтеграцію», «Джерело угод», «Відповідальний»;
   - «Нові замовлення»: «Автоприйняття» з затримкою в хвилинах, «Зв'язувати товари по» (артикул / ID маркетплейсу / назва);
   - «Чати», «Пов'язані статуси», «Автоматична відправка ТТН», «Фід для маркетплейсу».

Унизу липка панель: «Зберегти» (активна лише зі змінами) і «Скасувати зміни». Зберігати може лише адміністратор.
4. **Увімкнення.** Перемикач «Інтеграція» у «Підключенні» або «Увімкнути інтеграцію» в «Налаштуваннях продажів» — це одне й те саме: приймати замовлення каналу напряму в угоди. Вибір зберігається в базі й переживає перезапуск сервера.

Поля угоди, у які лягають дані замовлення, налаштовуються як завжди — «Налаштування → Типи даних → Угоди». Дані Prom пишуться в додаткові поля з ключами `prom_order_id`, `prom_status`, `prom_payment_type`, `prom_delivery_address` та інші (ті самі ключі, що ставила інтеграція KeepinCRM).

**Бренд і юрособа.** Юрособу для угод цього кабінету задає правило в «Налаштування → Бренди та юрособи → Правила» з умовою «Канал (картка «Інтеграцій»)». Окремого поля «Бренд» у картці Prom поки нема.

**Важливо при переході з KeepinCRM.** Якщо Prom ще підключений до KeepinCRM, замовлення приходять у Helomi дзеркалом. Увімкнули приймання тут — того ж дня вимкніть Prom у KeepinCRM, інакше замовлення прийде двічі.

## 2. Приймати замовлення в угоди
1. Увімкніть інтеграцію (див. вище).
2. Кожні 5 хвилин CRM забирає нові замовлення Prom.
3. Для кожного замовлення: клієнт шукається за телефоном у будь-якому форматі (нема — створюється з джерелом каналу); угода отримує назву = № замовлення Prom, етап за «Пов'язаними статусами» (без мапи — початковий етап «Новий»), позиції — товари складу за вибраним полем (не знайдено — позиція без товару); доставка — у полях блоку «Доставка» угоди («Адреса доставки», «Одержувач», «Телефон одержувача», «Спосіб доставки»), рядок ТТН з'являється, коли ТТН створено. «Адреса доставки» — як дав Prom, лише відділення Нової Пошти названо повністю: «Київ, Відділення №88 (до 30 кг): вул. …» (Prom пише «№88»); поле Prom «prom_delivery_address» — дослівно.
4. Що сталося, видно в картці: «Стан роботи → Приймання замовлень» (час останнього прогону, скільки створено й оновлено) і «Журнал подій».

На телефоні картка йде в одну колонку; таблиця статусів стає картками рядків.

## 3. Пов'язані статуси і статус назад на Prom
1. «Налаштування продажів» → «Пов'язані статуси» → «+ Додати статус».
2. У рядку: «Статус на Prom» (Новий, Прийнято, Оплачено, Виконано, Скасовано, Відхилено, Чернетка), «Етап угоди», для етапу скасування — «Причина скасування» і «Коментар покупцю».
3. Нова угода стає на етап з мапи. Якщо замовлення прийшло повторно зі зміненим статусом, що є в мапі (або скасоване), угода рухається на відповідний етап — із записом у журналі й складськими наслідками етапу.
4. Перемикач «Зворотний зв'язок» → «Передавати етап назад на маркетплейс»: коли менеджер переводить угоду на етап з мапи, CRM ставить відповідний статус на Prom (для скасування — з причиною). Типово вимкнено.

## 4. Автоприйняття, автоматична ТТН, чати
- **Автоприйняття**: «Автоматично переводити з «Новий» на «Прийнято»» через вказані хвилини. Діє, лише поки угоду ніхто не рушив вручну. «Переводити угоду на етап» (17.10): перший за порядком етап з роллю «Прийнято» (типово), обраний етап своєї воронки або «не переводити».
- **Автоматична відправка ТТН**: позначте етапи (чипи по воронках) і «Службу доставки» (або «з даних угоди (інакше Нова Пошта)»). Коли угода переходить на позначений етап, ТТН створюється сама — лише якщо активної ТТН ще нема і є дані доставки. Помилка пишеться в журнал каналу.
- **Передача ТТН на маркетплейс**: статуси замовлення Prom, на яких приймається декларація (типово «Прийнято», «Оплачено»), і перемикач «спершу перевести в потрібний статус» («Новий» → «Прийнято»). В угоді — «⋮» рядка ТТН → «Передати ТТН на Prom» (`POST /delivery/save_declaration_id`; лише Нова Пошта, Укрпошта, Meest). Номер замовлення береться з поля `prom_order_id` і завжди йде на Prom цілим числом — навіть якщо поле має тип «число» (з імпорту KeepinCRM) чи номер записано з «№». Служба «ukr_poshta» з KeepinCRM — це Укрпошта. Якщо на Prom уже стоїть інша ТТН, підтвердження питає, чи замінити її (і попереджає, якщо стара вже в дорозі).
- **Чати**: «Чати про товари», «Чати про замовлення» і «Оператори» — хто відповідає. «Відкрити переписки →» веде в «Переписки».

## 5. Оновлення товарів і фід
- У «Підключенні» → «Стан роботи» рядок «Оновлення товарів» показує, автоматично чи вручну оновлюються залишки й ціни на Prom зі складу; «Оновити зараз» запускає оновлення.
- «Налаштування продажів» → «Фід для маркетплейсу»: перший рядок — «Фід каналу з прайс-листа» (`/feed/channel/prom.xml`: оголошення Prom з ціною з прайс-листа і залишком зі складу), другий — фід усього складу `/feed/all.xml`; у кожного «Скопіювати». Адреси не змінюються — змінюються лише товари в них. З 14.10 Аліна читає склад Helomi (`CRM_BACKEND=local`), не KeepinCRM.
- Як Аліна знаходить оголошення у фіді (23.10): спершу за точним артикулом («К000028» кирилицею і «K000028» латиницею — різні товари). Двійник з іншою літерою береться лише тоді, коли він у фіді один. Якщо двійників кілька, Аліна не вгадує: ставить оголошенню 0 і «Немає в наявності», а артикул записує в журнал прогону як «неоднозначний». Виправте артикул оголошення на Prom або в прайс-листі, і наступний прогін поставить правильну кількість.

## 6. Другий кабінет Prom (акаунти)
1. Картка «Prom» → «Підключення» → блок «Акаунти» → «+ Додати акаунт».
2. «Назва» (як підписати кабінет, напр. «Semenchenko Prom») і «API ключ» (можна ввести й пізніше) → «Додати акаунт».
3. Відкриється картка нового акаунта. Новий акаунт створюється вимкненим: перевірте ключ («Перевірити») і ввімкніть.
4. В акаунта свої перемикач, ключ, «Налаштування продажів» (джерело, відповідальний, мапа статусів) і журнал; ключ основної картки він не бере.
5. Перейменувати — поле «Назва акаунта»; прибрати — «Прибрати» (угоди лишаються, зникають ключ, налаштування й журнал акаунта).

## 7. Блок «Prom» в угоді
У картці угоди з джерелом Prom є блок «Prom (<джерело>)» з даними замовлення: ID, суми, статус, коментар, історія статусу, оплата, ТТН, доставка й отримувач. Чого Prom не передав — «…». Значення, яке можна змінити, змінюється кліком по ньому.

- Натиск на **ID** або на **назву блоку** відкриває це замовлення в кабінеті Prom (`my.prom.ua/cms/order/edit/<ID>`) у новій вкладці.
- **«?»** праворуч у заголовку блоку відкриває цю статтю у шторці одразу на цьому розділі; «Відкрити у WIKI» — повна сторінка статті.

## Усі замовлення, не лише нові (14.10)
Приймання бере замовлення в УСІХ статусах Prom, крім чернеток («Новий», «Прийнято», «Оплачено» — Пром-оплата, «Виконано», «Скасовано»; інших статусів у списку замовлень Prom нема); етап — за мапою «статус → етап» у «Налаштуваннях продажів», без мапи — за змістом статусу (виконано → етап ролі «Отримано», скасовано → «Скасована»). У картці каналу, блок «Стан роботи» → «Вивантажити замовлення» за N днів назад (повтор не дублює — записи шукаються за номером замовлення).

## Статуси Prom у картці угоди (15.10)
Панель «Prom» у картці угоди показує коди Prom людською мовою: «Статус замовлення» — «Новий», «Прийнято», «Оплачено», «Виконано», «Скасовано» (кольоровою пігулкою: зелена — оплачено чи виконано, жовта — новий, червона — скасовано); «Статус оплати» — «Оплачено», «Не оплачено», «Повернено покупцю», «Виплачено продавцю»; «Джерело створення» — «Сайт Prom», «Застосунок Prom», «Сайт компанії на Prom», «Кабінет компанії», «Bigl». У полі зберігається код Prom (`paid`, `mobile_catalog_app`…), його видно в підказці при наведенні; за кодом рухаються етапи. Власний статус магазину (`custom-…`) показується як є.

## Фінанси каналу: нарахування, комісія, виплата (16.10)
Гроші Prom у «Фінансах» — правило каналу у «Фінанси → Звірка» → рядок «Prom» (кожен акаунт — своє правило; типово вимкнено). Увімкнене правило в момент «гроші наші» (при замовленні, коли угода виграна чи на вибраних етапах) проводить дохід угоди в транзитний гаманець «Транзит · Prom» (угода стає «сплаченою») і комісію майданчика витратою по угоді; угода скасована — сторно. Заготовка комісії: сума з поля угоди `prom_commission` (її пише Prom); гроші наші, лише коли `prom_payment_type` містить «пром-оплат» — накладений платіж іде через NovaPay. Виплата Prom на рахунок — правило імпорту «Виплата каналу» або кнопка у «Вхідних»: переказ, а не другий дохід; баланс транзитного гаманця — скільки Prom ще винен. Докладно — стаття «Фінанси», розділ 7а.

З 20.10 увімкнено: Пром-оплату виплачує «ТОВ РОЗЕТКА ПЕЙ» разом з оплатами Rozetka, тож транзит спільний — «Транзит · RozetkaPay (Prom, Rozetka)»; дохід — коли угода виграна (отримана покупцем), лише Пром-оплата чи «Тип оплати checkbox» Rozetkapay. Комісія — одразу при замовленні, для будь-якої оплати: поле `prom_commission` — приймання бере його з API замовлення (`cpa_commission`, є й у накладеному платежі; повернена — 0); порожнє чи 0 — комісії нема (рішення власника 20.10); списується з «Баланс · Prom» (кабінет) — це звірка, у P&L і «Грошовий потік» не входить. Витрата на Prom — поповнення кабінету: «Комісія Прому» з чату Марії чи рядок виписки «prom.ua» — «Комісія ПРОМ» на гаманці, з якого платили (власник 21.10). Виплата «РОЗЕТКА ПЕЙ» з виписки — переказ із транзиту сам, винагорода з призначення — «Комісія RozetkaPay». API балансу в Prom нема, тож звірити комісію з кабінетом — «Завантажити виписку» у шторці правила каналу: файл історії балансу з кабінету Prom (XLSX чи CSV) — списання «оплата за замовлення» по номерах замовлень стають комісією угод, повернення її зменшують, поповнення й решта — у підсумку як «інше». Докладно — «Фінанси», розділ 7а, «Виписка майданчика».

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): PROM_API_TOKEN» | Ключ не введено | «Підключення» → «API ключ» → «Ввести» |
| У журналі картки «статус не опитано — …: Incorrect status value» | Prom не знає такого статусу списку | Решта статусів опитується далі; якщо помилка на всіх — перевірте токен і версію Helomi |
| «Помилка: …» або «HTTP 401» після «Перевірити» | Prom не прийняв токен | Створіть новий токен у кабінеті Prom і замініть ключ |
| «Prom не перевів замовлення … у «Прийнято» (без цього декларацію не прийме): …» | Замовлення на Prom «Новий», і Prom відмовив перевести його в «Прийнято» перед передачею ТТН; причина — текст Prom після двокрапки | Перевірте замовлення в кабінеті Prom (скасоване, чуже, іншого кабінету); переведіть у «Прийнято» там і передайте ТТН ще раз |
| «Prom не прийняв декларацію: …» | Prom відмовив записати ТТН (уже є інша, не та служба доставки) | Перевірте замовлення в кабінеті Prom і службу доставки ТТН |
| «Перемикати канали може лише адміністратор» | Ви не адміністратор | Попросіть адміністратора |
| «Акаунт з ключем «…» уже є» | Така назва вже зайнята іншим акаунтом | Дайте акаунту іншу назву |
| «Пов'язані статуси, рядок N: оберіть етап» | У рядку мапи не вибрано етап | Виберіть етап або приберіть рядок |
| «Пов'язані статуси: статус «…» з тим самим етапом вказано двічі» | Дубль рядка | Приберіть зайвий рядок |
| «Затримка автоприйняття: від 0 до 1440 хв» | Завелика затримка | Вкажіть менше число |
| Замовлення прийшло двічі | Prom ще підключений і до KeepinCRM | Вимкніть Prom у KeepinCRM |

## Для ШІ-співробітників
5`). ШІ бачить результат у «Угодах» через `deals_list` / `deals_get`: джерело угоди, додаткові поля `prom_order_id`, `prom_status` (код Prom: `pending`, `received`, `paid`, `delivered`, `canceled`), `prom_payment_status` (`paid`, `unpaid`, `refunded`, `paid_out`), `prom_source`, `prom_payment_type`, `prom_delivery_address`… і акаунт, з якого прийшла угода (поле `crm_integration`, напр. `prom-semenchenko`; для основного кабінету його нема). Цю статтю ШІ читає інструментом `help("int-prom")`.

Чого не робити: не створювати вручну угоду на замовлення Prom, яке вже прийшло (шукати за № замовлення в `deals_list`); не змінювати поле `prom_order_id` — за ним CRM впізнає повтор.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Доставки і ТТН](shipping.md), [Склад і товари](products.md), [Переписки](chats.md), [Rozetka](int-rozetka.md).


---

# Rozetka

Інтеграція з Rozetka через Seller API приймає замовлення маркетплейсу в «Угоди», передає статус і ТТН назад на Rozetka, приносить чати покупців у «Переписки» і дає створювати ТТН у «Магазини Rozetka». Підключити можна одним натиском: увійти логіном і паролем кабінету продавця і натиснути «Підключити Rozetka» — налаштування, статуси й приймання замовлень увімкнуться самі.

## Можливості
- Вхід логіном і паролем кабінету продавця (тимчасовий токен на 24 години оновлюється сам) або ключем API.
- «Підключити Rozetka» — одна кнопка: перевірка доступу, налаштування продажів, пов'язані статуси, «Магазини Rozetka», приймання замовлень і перше опитування.
- Замовлення Rozetka (нові, підтверджені й ті, що «Обробляються менеджером») кожні 5 хвилин стають угодами; повтор не дублюється.
- Статуси Rozetka беруться з Seller API; таблиця «Пов'язані статуси» — статус → етап угоди.
- Автоприйняття: «Нове замовлення» → «Обробляється менеджером» на Rozetka; чи й куди переводити угоду в CRM — налаштування
  «переводити угоду на етап» (типово для Rozetka — «не переводити», як у KeepinCRM).
- Статус назад на Rozetka, коли менеджер рухає угоду.
- Чати про товари, про замовлення і запитання до продавця.
- ТТН у «Магазини Rozetka» через Rozetka Delivery з доступом по людях.
- «ТТН із замовлення» (16.10): замовлення з доставкою ROZETKA Delivery — окрема форма в угоді, накладну створює сама Rozetka в кабінеті продавця й одразу прив'язує до замовлення (як у KeepinCRM).
- Імпорт усіх старих замовлень і клієнтів за N днів.
- Оновлення залишків і цін на Rozetka — через Seller API (у кабінеті Rozetka прайс-лист типу «Особистий кабінет (API)»): Helomi шле `PUT /items/mass-update` для кожного оголошення Rozetka з прайс-листа («Оголошення з каналів»): залишок — вільний залишок пов'язаних товарів складу, ціна — з прайс-листа. Автоматично за розкладом («Склад → Публікації» → картка Rozetka → «автоматично кожні N хв», типово 60) або кнопкою «Оновити зараз» у картці Rozetka / «Публікаціях» (спершу «Показати, що зміниться»). Позиція без зв'язку зі складом не чіпається. Запобіжник: якщо за один прогін у нуль пішло б забагато оголошень — прогін зупиняється, підтвердити можна кнопкою. Фід каналу `/feed/channel/rozetka.xml` лишається для перевірки.
- «На Rozetka» в рядку ТТН угоди — передати ТТН. Rozetka приймає ТТН **лише разом зі статусом** (Seller API «Редагування замовлення (статус, ТТН)»: `status` обов'язковий; без нього Rozetka відповідає «успіх», але ТТН не записує). Helomi бере дозволені переходи замовлення (`expand=status_available`) і шле `PUT /orders/{id}` `{status, ttn}`: 61, якщо дозволено, інакше 2 «Дані підтверджено» (з ТТН Rozetka сама ставить 61), інакше 3; далі трекінг веде Rozetka. Приймає з «Обробляється менеджером» (26) і «Підтверджено» (2); з «Нове» Helomi спершу ставить 26 (як автоприйняття). Результат перевіряється перечитуванням замовлення, новий статус записується в угоду (етап угоди не змінюється). Правило — «Налаштування продажів → Передача ТТН на маркетплейс».

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Маркетплейси» → картка «Rozetka» → вкладка «Підключення».

Є два способи доступу — оберіть один:
- **Логін і пароль кабінету продавця.** Рядок «Кабінет Rozetka» → «Логін» → логін і пароль → «Увійти». Після входу видно «Авторизований як: <логін>» і до якого часу діє токен. Rozetka дає токен на 24 години — CRM оновлює його сама перед опитуванням. Пароль зберігається зашифрованим. «Вийти» забуває логін і пароль (далі діє ключ API, якщо він заданий).
- **Ключ API.** Рядок «API ключ (Seller API)» → «Ввести» → «Зберегти ключ». Ключ береться в кабінеті продавця Rozetka в розділі безпеки API.

«Перевірити» — безпечний запит лише на читання; успіх — «доступ до замовлень є».

Друга вкладка картки — «Налаштування продажів»: «Основне» (перемикач, «Джерело угод», «Відповідальний»), «Нові замовлення» («Автоприйняття», «Зв'язувати товари по»), «Чати», «Пов'язані статуси», «Автоматична відправка ТТН», «Фід для маркетплейсу», «Магазини Rozetka», «Імпорт замовлень і клієнтів». Унизу — «Зберегти» і «Скасувати зміни».

Дані замовлення пишуться в додаткові поля угоди з ключами `rozetka_order_id`, `rozetka_status` (назва статусу) і `rozetka_status_code` (його код), `rozetka_status_history`, `rozetka_order_amount`, `rozetka_amount_with_discount`, `rozetka_payment_type`, `rozetka_payment_status`, `rozetka_user_rating`, `rozetka_delivery_address`, `rozetka_delivery_recipient_title`, `rozetka_delivery_cost` та інші (повний перелік — у розділі 8). Самі поля налаштовуються в «Налаштування → Типи даних → Угоди».

Юрособа для угод Rozetka — правилом у «Налаштування → Бренди та юрособи → Правила» з умовою «Канал (картка «Інтеграцій»)».

## 2. Підключити одним натиском
1. Увійдіть логіном/паролем або введіть ключ API.
2. Рядок «Одним натиском» → «Підключити Rozetka» → підтвердіть.
3. CRM перевірить доступ і поставить налаштування як у KeepinCRM: джерело «Rozetka», головний відповідальний, «Нове замовлення» → «Обробляється менеджером» через 1 хвилину, товари за артикулом, усі три види чатів, статус назад на Rozetka, пов'язані статуси (статуси шукаються в списку Rozetka за назвою, етапи — у воронці «Продажі» за назвою), «Магазини Rozetka» з доступом відповідальному; потім увімкне приймання і зробить перше опитування.
4. Під кнопкою з'явиться «Підключено: …», перелік застосованого і пропущеного (з рискою): наприклад, етапу з такою назвою у воронці нема. Пропущене допишіть у «Налаштуваннях продажів» вручну.

Типовий відповідальний і назви етапів у цьому наборі взято з компанії власника; якщо такого користувача нема, CRM ставить іншого і пише це в пропущеному.

Повторне натискання — «Застосувати налаштування знову».

**Важливо.** Того ж дня вимкніть інтеграцію Rozetka в KeepinCRM, інакше замовлення прийдуть двічі.

## 3. Приймати замовлення в угоди
Коли інтеграцію ввімкнено, CRM кожні 5 хвилин забирає замовлення. Клієнт шукається за телефоном (нема — створюється), угода отримує назву = № замовлення, етап за «Пов'язаними статусами», позиції — за вибраним полем зв'язку, доставку й оплату. Повторне надходження оновлює статус і додаткові поля (оплату, статус оплати, ТТН, історію статусів), а якщо статус на Rozetka справді змінився і є в мапі — рухає угоду. Те саме замовлення з тим самим кодом статусу етап не чіпає, навіть якщо змінився лише запис статусу (наприклад, код «1» став назвою «Нове замовлення»). Результат — «Стан роботи → Приймання замовлень» і «Журнал подій».

«Адреса доставки» угоди — як у KeepinCRM: місто, вулиця, будинок і точка з номером, напр. «Київ, вул. Якуба Коласа, 15, Відділення №88»; поштомат — «Поштомат №13 (маг. …)», село — з районом і областю, точка ROZETKA Delivery — адреса з описом. До 15.10 номер відділення потрапляв у вулицю («вул. Якуба Коласа 88 15») — такі незмінені адреси в уже створених угодах уточнено разовою заявкою; вписане людиною не чіпали.

## 4. Пов'язані статуси і статус назад на Rozetka
1. «Налаштування продажів» → «Пов'язані статуси» → «+ Додати статус».
2. «Статус на Rozetka» (зі списку Rozetka за назвою) → «Етап угоди»; для етапу скасування — «Причина скасування» і «Коментар покупцю».
3. Один статус можна прив'язати до кількох етапів: нова угода стане на перший рядок, а угода на будь-якому з цих етапів не рухатиметься.
4. «Зворотний зв'язок» → «Передавати етап назад на маркетплейс»: етап угоди → статус на Rozetka за цією мапою.
5. «Автоприйняття» → «Автоматично змінити статус з «Нового замовлення» на «Обробляється менеджером»» через N хвилин: CRM ставить цей статус на Rozetka, лише поки угоду ніхто не рушив вручну. Під перемикачем — «переводити угоду на етап»: «не переводити (лише статус на Rozetka)» — угода лишається там, куди її поставив рядок «Пов'язаних статусів» (наприклад «1» → «Новий»); «перший етап «Прийнято» воронки» — перший за порядком етап з роллю «Прийнято» (у «Продажах» це «Бронь» — тому 15–17.10 нові замовлення опинялись на «Бронь»); або будь-який етап зі списку (лише своєї воронки). Власник 17.10 обрав «як у KeepinCRM»: «1» → «Новий», автоприйняття не переводить.

## 5. Магазини Rozetka: ТТН у точки видачі
1. «Налаштування продажів» → блок «Магазини Rozetka» → перемикач «Увімкнути створення ТТН в магазини Rozetka».
2. «Відправник»: «Оновити інформацію» підтягує відправника з налаштувань сервера; або заповніть ім'я, телефон, місто й відділення руками.
3. «Параметри відправлення»: довжина, висота, ширина, вага, об'єм і короткий опис (вага товарів угоди, якщо є, головніша).
4. «Доступ до доставки»: після підключення доступу нема ні в кого — поставте «Показати» тим, хто створює ТТН. Без галочки людина бачить і друкує ТТН, але створити не може.
5. В угоді з доставкою «Магазини Rozetka» у блоці «Доставка» ТТН створюється в точку видачі через Rozetka Delivery. Докладно — [Rozetka Delivery](int-rozetka-delivery.md).

## 5а. ТТН із замовлення: доставка ROZETKA Delivery (16.10)
Покупець вибрав у замовленні доставку ROZETKA Delivery — таке замовлення не приймає ТТН ззовні (ЕН з власного акаунта Rozetka Delivery Rozetka відхиляє: `check_correctness_of_data`). Накладну створює сама Rozetka — так робить і KeepinCRM.
1. Перемикач — «Налаштування продажів» → блок «Магазини Rozetka» → «ТТН із замовлення на боці Rozetka» (типово увімкнено). Вимкнули — в угоді знову звичайна шторка «Створити ТТН».
2. В угоді з Rozetka, де «Служба доставки (Rozetka)» — ROZETKA Delivery, у блоці «Доставка» «+» і «Додати місце» відкривають форму «ТТН із замовлення Rozetka».
3. «Замовлення Rozetka» — одержувач, куди й оплата: лише показ, Rozetka бере їх із замовлення (накладений платіж — як у замовленні).
4. «Параметри відправлення» — вага (0,1–30 кг), довжина, ширина, висота (1–120 см), місць, опис до 100 символів. Типово — посилка з налаштувань ROZETKA Delivery кабінету продавця (або вага товарів угоди, або параметри цієї картки).
5. «Відправник» — ПІБ, телефон, місто й відділення відправлення зі списку ROZETKA Delivery; типово — відправник за замовчуванням з кабінету продавця. Інше місто — введіть назву, список відділень оновиться. У списку всі відділення міста (Rozetka віддає їх сторінками по 50, форма збирає всі); відділення з кабінету, якого у списку нема, показується як «З кабінету Rozetka».
6. «Платник доставки» — одержувач або відправник; безкоштовна для покупця доставка (вартість у замовленні 0) — типово відправник.
7. «Створити ТТН на Rozetka» — ТТН з'являється в угоді (служба Rozetka Delivery), у полі `rozetka_ttn` і в трекінгу; стікер — «⋮ → Роздрукувати стікер» (друк Rozetka). У замовленні вже є ТТН — кнопка вимкнена, номер можна записати через «вручну». «Інший перевізник» — звичайна шторка.
8. Видалити таку ТТН можна лише в кабінеті продавця Rozetka (у Seller API методу нема); «⋮ → Видалити ТТН» пояснить це й запропонує прибрати її лише з угоди.

Доступ — той самий «Доступ до доставки» з блоку «Магазини Rozetka».

## 6. Імпорт старих замовлень і клієнтів
1. Спершу пов'яжіть статуси з етапами — інакше всі замовлення стануть на початковий етап.
2. «Імпорт замовлень і клієнтів» → «Запуск»: вкажіть «за N дн.» → «Запустити імпорт».
3. Імпорт іде у фоні сторінка за сторінкою (Rozetka віддає по 20 замовлень): «Триває», потім «Готово» з лічильниками «отримано, створено, оновлено, в архів». Виконані й скасовані замовлення йдуть в архів; дублі за `rozetka_order_id` не створюються.

## 7. Другий кабінет Rozetka (акаунти)
Картка «Rozetka» → «Підключення» → «Акаунти» → «+ Додати акаунт» → «Назва» і «API ключ (Seller API)» (можна пізніше) → «Додати акаунт». Новий акаунт вимкнений: перевірте ключ і ввімкніть. У нього свої ключ, вхід у кабінет, налаштування продажів і журнал. «Прибрати» — угоди лишаються, зникають ключ, налаштування й журнал акаунта.

## 8. Блок «Rozetka» в угоді
У картці угоди з джерелом Rozetka є блок «Rozetka (<джерело>)» з даними замовлення. Чого Rozetka не передала — «…». Значення, яке можна змінити, змінюється кліком по ньому.

| Рядок | Звідки (Seller API) | Поле угоди |
| --- | --- | --- |
| ID | номер замовлення | `rozetka_order_id` |
| Рейтинг клієнта, (id) | `user_rating`: 1 — високий, 2 — середній, 3 — низький відсоток викупу | `rozetka_user_rating`, `rozetka_user_rating_id` |
| Сума замовлення, Сума зі знижкою | `amount`, `amount_with_discount` (товари, без доставки) | `rozetka_order_amount`, `rozetka_amount_with_discount` |
| Статус замовлення | назва статусу (`status_data`), код — окремо | `rozetka_status`, `rozetka_status_code` |
| Коментар | коментар покупця | `rozetka_comment` |
| Джерело створення | `created_type`: від покупця, з кабінету продавця, по API… | `rozetka_source` |
| Історія статусу замовлення | `order_status_history`, найновіші зверху | `rozetka_status_history` |
| Спосіб оплати, Статус оплати | `payment`: метод оплати і статус («Оплачено»…) | `rozetka_payment_type`, `rozetka_payment_status` |
| ТТН, Спосіб доставки, ПІБ і телефон отримувача, Адреса, Вартість доставки | `ttn`, `delivery` | `rozetka_ttn`, `rozetka_delivery_*` |
| Інша особа отримувач | ПІБ або телефон отримувача не ті, що в покупця | `rozetka_other_recipient` |
| Перетелефоновувати | `callback_off`: «Ні», коли покупець просив не дзвонити | `rozetka_callback` |
| Фулфілмент | `is_fulfillment` | `rozetka_fulfillment` |

Комісії Rozetka Seller API у замовленні не віддає — рядок «Комісія» лишається порожнім.

- Натиск на **ID** або на **назву блоку** відкриває це замовлення в кабінеті продавця Rozetka (`seller.rozetka.com.ua/main/orders/all/<ID>`) у новій вкладці. Якщо ви ще не входили в кабінет у цьому браузері, Rozetka спершу попросить увійти. Замовлення з другого кабінету (акаунта) відкриється, коли в браузері виконано вхід саме в той кабінет.
- **«?»** праворуч у заголовку блоку відкриває цю статтю у шторці одразу на цьому розділі; «Відкрити у WIKI» — повна сторінка статті.

## Усі замовлення, не лише нові (14.10)
Приймання бере замовлення в УСІХ статусах Seller API (нові, підтверджені, у доставці, виконані, скасовані, повернення); етап — за мапою «статус → етап», без мапи — за змістом статусу (у доставці → «Відправлено», виконано → «Отримано», не буде → «Скасована», повернення → «Повернення»). У картці каналу → «Стан роботи» → «Вивантажити замовлення» за N днів назад.

## Якщо замовлення не з'являються
Опитування йде кожні 5 хвилин: Seller API `/orders/search` з групою «усі замовлення» двічі — від дати створення і від дати зміни (останнє опитування мінус 2 години), усі сторінки (по 20 замовлень). Так нові замовлення стають угодами, а оплата, статус і ТТН, що змінились на Rozetka пізніше, оновлюються в уже створених угодах. У картці Rozetka → «Журнал подій» має бути «intake: отримано N, створено M»; якщо рядків нема зовсім — замовлень за вікно не було; «ПОМИЛКА» з текстом — ключ чи Rozetka. «Вивантажити замовлення» за N днів у «Стані роботи» бере все заново без дублів.

## Фінанси каналу: нарахування, комісія, виплата (16.10)
Гроші Rozetka у «Фінансах» — правило каналу у «Фінанси → Звірка» → рядок «Rozetka» (кожен акаунт — своє правило; типово вимкнено). Увімкнене правило в момент «гроші наші» (при замовленні, коли угода виграна чи на вибраних етапах) проводить дохід угоди в транзитний гаманець «Транзит · Rozetka» (угода стає «сплаченою») і комісію майданчика витратою по угоді; угода скасована — сторно. Заготовка комісії: сума з поля угоди `rozetka_commission` (її пише Rozetka). Виплата Rozetka на рахунок — правило імпорту «Виплата каналу» або кнопка у «Вхідних»: переказ, а не другий дохід; баланс транзитного гаманця — скільки Rozetka ще винен. Докладно — стаття «Фінанси», розділ 7а.

З 20.10 увімкнено: «ТОВ РОЗЕТКА ПЕЙ» платить і за Rozetka, і за Пром-оплату — транзит спільний, «Транзит · RozetkaPay (Prom, Rozetka)»; дохід — коли угода виграна, лише якщо «Тип оплати checkbox» Rozetkapay (картка, Apple/Google Pay, наложка ROZETKA Delivery; наложка Новою поштою йде через NovaPay). Комісія — одразу при замовленні, для будь-якої оплати: поле `rozetka_commission` — приймання бере його з API замовлення (`commission_sum` позицій × кількість, як KeepinCRM); порожнє чи 0 — комісії нема (рішення власника 20.10); з «Баланс · Rozetka» — це звірка, у P&L і «Грошовий потік» не входить; витрата на Rozetka — поповнення кабінету («Комісія Розетка» на гаманці, з якого платили, власник 21.10). Виплата з виписки — переказ із транзиту сам, винагорода з призначення — «Комісія RozetkaPay». Щодня (і кнопкою «Підтягнути з API за 7 днів» у шторці правила каналу) комісію звіряє журнал балансу кабінету з API: комісія замовлення мінус повернення при скасуванні — якщо інша, ніж у журналі, береться з кабінету; зарахування на баланс без замовлення — у підсумку як «поповнення». Докладно — «Фінанси», розділ 7а, «Виписка майданчика».

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| Біля ТТН замість кнопки «На Rozetka» — підказка «Доставка ROZETKA Delivery — ТТН створює сама Rozetka…» | Замовлення з доставкою ROZETKA Delivery: накладну створює Rozetka після підтвердження даних, ТТН від продавця вона не приймає (`check_correctness_of_data`) | Нічого передавати не треба; якщо створили ЕН з власного акаунта Rozetka Delivery — вона зайва, видаліть її («⋮ → Видалити ТТН»); ТТН створіть формою «ТТН із замовлення» (розділ 5а) |
| «Rozetka не створила ТТН: …» у формі «ТТН із замовлення» | Rozetka відхилила дані посилки чи відправника (текст після двокрапки — від Rozetka) | Перевірте вагу, габарити, відділення відправлення; замовлення має бути в статусі, де Rozetka дозволяє створити ТТН |
| «На угоді вже є активна ТТН Rozetka …» | Друга ТТН Rozetka на ту саму угоду | Зайву ТТН спершу видаліть з угоди |
| «ТТН … створено в кабінеті Rozetka із замовлення — видалити її можна лише в кабінеті продавця» | У Seller API нема методу видалення такої ТТН | Видаліть у кабінеті продавця Rozetka, потім «Прибрати з угоди» |
| «Rozetka не прийняла ТТН: 1005 — check_correctness_of_data …» після «На Rozetka» | Rozetka не прийняла номер ТТН: щойно створена ЕН Rozetka Delivery ще не відома кабінету продавця або гонка статусів | Helomi сам повторює до 3 разів; не допомогло — натисніть «На Rozetka» ще раз за кілька хвилин; подробиці після коду — що саме не так |
| «Вкажіть логін і пароль кабінету продавця Rozetka» | Порожнє поле у формі входу | Заповніть обидва поля |
| «Rozetka не прийняла логін/пароль: …» | Неправильний логін чи пароль | Перевірте дані в кабінеті продавця |
| «Нема ключа Rozetka — увійдіть або введіть ключ API» | Немає ні входу, ні ключа | Увійдіть або введіть ключ |
| «не задано (у картці чи .env): ROZETKA_SELLER_API_KEY» | «Перевірити» без ключа | Увійдіть або введіть ключ |
| «Rozetka не приймає ТТН у статусі «…»» | З поточного статусу замовлення Rozetka не дозволяє перейти ні в 61, ні в 2, ні в 3 (наприклад, виконане чи скасоване) | Перевірте замовлення в кабінеті продавця |
| «Rozetka не дозволяє змінювати доставку замовлення …» | У замовленні `is_delivery_edit_available = false` | Змініть доставку в кабінеті продавця або зверніться в підтримку Rozetka |
| «У .env не задано ROZETKA_SENDER_NAME / PHONE / CITY / DEPARTMENT — заповніть відправника руками» | «Оновити інформацію» без відправника на сервері | Заповніть «Відправник» вручну |
| «Нема доступу до створення ТТН у магазини Rozetka — надайте його в картці Rozetka → …» | Людині не дано «Показати» в «Доступ до доставки» | Адміністратор ставить галочку в «Магазини Rozetka» → «Доступ до доставки» |
| Замовлення прийшло двічі | Rozetka ще підключена до KeepinCRM | Вимкніть Rozetka в KeepinCRM |

## Для ШІ-співробітників
5`). «ТТН із замовлення» (розділ 5а) ШІ робить тими самими маршрутами, що й форма: `shipping_list` (поле `rozetka_order`), `shipping_rozetka_order_form`, `shipping_rozetka_order_pickups`, `shipping_rozetka_order_create` (через кошик підтверджень — відправка назовні). ШІ бачить результат у «Угодах» (`deals_list`, `deals_get`): джерело «Rozetka», додаткові поля `rozetka_order_id`, `rozetka_status`, `rozetka_status_code`, `rozetka_payment_type`, `rozetka_payment_status`, `rozetka_order_amount`… і акаунт, з якого прийшла угода (`crm_integration`; для основного кабінету його нема). Статтю ШІ читає інструментом `help("int-rozetka")`.

Чого не робити: не створювати вручну угоду на замовлення, яке вже прийшло; не змінювати `rozetka_order_id`.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Доставки і ТТН](shipping.md), [Rozetka Delivery](int-rozetka-delivery.md), [Prom](int-prom.md), [Переписки](chats.md).


---

# Kasta

Інтеграція з Kasta приймає замовлення маркетплейсу Kasta в «Угоди» за офіційним API постачальника і передає назад на Kasta статус замовлення та ТТН. Підключається одним натиском: ввести токен і натиснути «Підключити Kasta». ТТН для замовлень Kasta створюються лише через кабінет hub.kasta.ua — для цього є окрема картка «Kasta hub» у «Перевізниках».

## Можливості
- Потік змін замовлень Kasta: CRM читає його за курсором, перше опитування — замовлення за останні два дні (старіших Kasta не віддає).
- Угода з назвою = № замовлення Kasta, клієнт за телефоном, позиції за артикулом постачальника, доставка службою «Kasta».
- «Пов'язані статуси»: статус Kasta → етап угоди.
- «Передавати статус і ТТН на Kasta»: менеджер рухає угоду — статус на Kasta змінюється сам, з ТТН угоди на кроці «Зареєстровано у кур'єрській службі».
- Блок «Kasta» в картці угоди: статус замовлення, статус доставки, запит покупця на відміну, історія, кнопки дій.
- Кілька магазинів Kasta зі своїми токенами.

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Маркетплейси» → картка «Kasta» → вкладка «Підключення».

1. Рядок «API токен» → «Ввести» → вставте токен → «Зберегти ключ». Токен береться в кабінеті Kasta: «Налаштування → Загальні → API». Зберігається зашифрованим, показуються лише останні символи.
2. «Перевірити» читає одне замовлення з потоку Kasta (лише читання).
3. Рядок «Потік замовлень» показує «читається · останній раз …» або «ще не почато». «Почати заново» скидає курсор (якщо щось пішло не так).
4. Вкладка «Налаштування продажів»: «Основне» («Увімкнути інтеграцію», «Джерело угод», «Відповідальний»), «Нові замовлення» («Автоприйняття», «Зв'язувати товари по»), «Пов'язані статуси» з перемикачем «Передавати статус і ТТН на Kasta», «Фід для маркетплейсу» («Фід каналу з прайс-листа» `/feed/channel/kasta.xml` — його з 14.10 читає ШІ Єлизавета замість фіду KeepinCRM: залишки — зі складу Helomi, ціни — з прайс-листа; і фід усього складу). Блоку «Автоматична відправка ТТН» тут нема: ТТН Kasta — лише через hub.kasta.ua. Блок «Передача ТТН на маркетплейс» — статуси, після яких ТТН приймається (типово «Упаковано»), і «спершу перевести»: в угоді «⋮» рядка ТТН → «Передати ТТН на Kasta» = статус «Зареєстровано у кур'єрській службі» з номером; бракує «Підтверджено»/«Упаковано» — Helomi передає їх першими (як блок «Kasta» в угоді).
5. Для ТТН підключіть картку «Kasta hub» у вкладці «Перевізники» ([стаття](int-kasta-hub.md)). ТТН, уже створену в кабінеті hub.kasta.ua вручну, записують в угоду так: блок «Доставка» → «вручну» (або «+» → «Додати ТТН») → номер → «Записати ТТН». Номер лягає в наявний рядок доставки Kasta з замовлення (другого рядка не буде), далі статус оновлюється сам, і ТТН можна передати на Kasta.

Дані замовлення пишуться в додаткові поля угоди (`kasta_order_id` та інші); поля налаштовуються в «Налаштування → Типи даних → Угоди». Юрособа угод Kasta — правилом «Налаштування → Бренди та юрособи → Правила» з умовою «Канал (картка «Інтеграцій»)».

## 2. Підключити одним натиском
1. Введіть «API токен».
2. Рядок «Одним натиском» → «Підключити Kasta» → підтвердіть.
3. CRM ставить налаштування як у KeepinCRM: джерело «Kasta», головний відповідальний, товари за артикулом, пов'язані статуси (воронка «Продажі Каста»: Необроблені, Передано на збірку, Зібрано, Відправлено; воронка «Продажі»: Отримано, Угода скасована), статус і ТТН назад на Kasta; потім вмикає приймання і робить перше опитування.
4. Під кнопкою — що застосовано і що пропущено (наприклад, етапу з такою назвою нема). Пропущене допишіть вручну в «Пов'язаних статусах».

Набір «одним натиском» узято з компанії власника. Повторно — «Застосувати налаштування знову».

**Важливо.** Того ж дня вимкніть інтеграцію Kasta в KeepinCRM, інакше замовлення прийдуть двічі.

## 3. Приймати замовлення в угоди
Коли інтеграцію ввімкнено, CRM кожні 5 хвилин читає потік змін. Статус замовлення береться з його історії (Створено → Підтверджено → Упаковано → Зареєстровано у кур'єрській службі → Доставлено; або Відмінено). Нове замовлення стає угодою на етапі з «Пов'язаних статусів»; повтор оновлює статус і, якщо статус є в мапі, рухає угоду. Справжній перевізник посилки записується в поле угоди, а служба доставки — «Kasta». Що сталося — «Стан роботи» і «Журнал подій» картки.

«Адреса доставки» угоди: Нова Пошта — як дає Kasta («Київ, Відділення №88 (до 30 кг): вул. …»), Укрпошта — «Київ, 01001, просп. …, 4» (індекс окремо, не в дужках).

## 4. Статус і ТТН назад на Kasta
Увімкніть «Передавати статус і ТТН на Kasta» у «Пов'язаних статусах». Коли менеджер переводить угоду на етап з мапи:
- пропущені проміжні «Підтверджено» й «Упаковано» CRM надішле сама («Упаковано» — з позиціями й сумою);
- на «Зареєстровано у кур'єрській службі» — з ТТН угоди;
- «Відмінено» — з причиною зі списку Kasta.

Помилки Kasta пишуться в журнал картки людською мовою.

## 5. Блок «Kasta» в угоді
У картці угоди з Kasta є блок «Kasta»: статус замовлення пігулкою, статус доставки, запит покупця на відміну (червоним), історія статусів. Дії: «Підтвердити», «Упаковано», «Передати ТТН» (з полем номера), «Відмінити…» з «Причиною відміни», «Оновити». Якщо бракує проміжних статусів, кнопка підказує, що саме буде передано першим.

Над ним — блок «Kasta (<джерело>)» з даними замовлення: ID, «Сума замовлення», «Статус замовлення», «Історія статусу замовлення», «Спосіб оплати», «Статус оплати» («Оплачено» карткою на Kasta, «Післяплата», «Очікує оплати»), «ТТН», «Спосіб доставки» (Нова Пошта / Укрпошта), отримувач, телефон, «Адреса доставки», «Вартість доставки», «Коментар». Назва блоку й ID — посилання на замовлення в кабінеті hub.kasta.ua: поки посилку не відправлено — вкладка «Нові» (`hub.kasta.ua/customer-orders/new?order=…`), далі — «Відправлені» (`…/sent?order=…`). Номер замовлення в заголовку блоку «Kasta» теж відкриває його в кабінеті. Коли блок «Kasta» відкривається, свіжі дані замовлення одразу лягають в угоду (поля блоку, джерело вітрини, ТТН і статус посилки) — етап при цьому не рухається. «?» у заголовку блоку відкриває цю статтю у шторці одразу на цьому розділі.

## 6. Другий магазин Kasta (акаунти)
Картка «Kasta» → «Підключення» → «Акаунти» → «+ Додати акаунт» → «Назва» і «API токен» → «Додати акаунт». Новий акаунт вимкнений: перевірте токен і ввімкніть (або «Підключити Kasta» в його картці). У акаунта свої токен, потік, налаштування продажів і журнал.

## 7. Укрпошта Маркет і доставка Укрпоштою (22.10)
«Укрпошта Маркет» (маркетплейс у застосунку Укрпошти) працює через Kasta: продавець — той самий кабінет hub.kasta.ua, замовлення приходять тим самим потоком, статуси й ТТН — як у звичайної Kasta. Щоб продажі рахувались окремо, такі угоди отримують своє джерело. Його обирають у картці «Kasta» → «Налаштування продажів» → «Основне» → «Джерело «Укрпошта Маркет»»; типово — джерело з назвою «Укрпошта Маркет» (великі й малі літери не важливі), а якщо його нема — створюється. Угода, яку вже прийняли з джерелом «Kasta», переходить на джерело вітрини при наступній зміні замовлення або коли відкрити блок «Kasta»; джерело, яке людина змінила вручну, не чіпається. У блоці «Kasta» в угоді вітрину видно жовтою пігулкою «Укрпошта Маркет».

Kasta возить і Укрпоштою. ТТН для таких замовлень, як і раніше, створюється лише в кабінеті hub.kasta.ua; Helomi сам бере номер із замовлення в рядок ТТН угоди. Хто везе, видно за номером: ШК Укрпошти — 13 цифр (`0505737109865`), ЕН Нової Пошти — 14. У списку угод і в блоці «Доставка» стоїть перевізник («УП» / «НП») і статус посилки, а не «Kasta». Статус оновлює трекінг тієї служби (для Укрпошти потрібен токен відстеження в картці «Укрпошта» у «Перевізниках»); поки служба статусу не дала, у рядку ТТН — статус від самої Kasta («Створено, не відправлено», «Відправлено», «Прибув у відділення», «Доставлено»). Статус служби, щойно він є, головніший — Kasta його не перетирає.

## Усі замовлення, не лише нові (14.10)
Приймання читає потік змін Kasta від збереженого курсора; «Вивантажити замовлення» за N днів у картці каналу скидає курсор і читає потік заново від дати (повтор не дублює).

## Фінанси каналу: нарахування, комісія, виплата (16.10)
Гроші Kasta у «Фінансах» — правило каналу у «Фінанси → Звірка» → рядок «Kasta» (кожен акаунт — своє правило; типово вимкнено). Увімкнене правило в момент «гроші наші» (при замовленні, коли угода виграна чи на вибраних етапах) проводить дохід угоди в транзитний гаманець «Транзит · Kasta» (угода стає «сплаченою») і комісію майданчика витратою по угоді; угода скасована — сторно. Заготовка комісії: 25 % від суми угоди. Виплата Kasta на рахунок — правило імпорту «Виплата каналу» або кнопка у «Вхідних»: переказ, а не другий дохід; баланс транзитного гаманця — скільки Kasta ще винен. Докладно — стаття «Фінанси», розділ 7а.

З 20.10 увімкнено: «Транзит · Kasta», дохід — коли угода виграна (усі угоди: Kasta сама доставляє й збирає гроші), комісія 21,6 % одразу при замовленні з «Баланс · Kasta» (кабінет) — це звірка; витрата на Kasta — передоплата гарантійного рахунку (списання «kastaua_3pl» — «Комісія Каста», власник 21.10). Виплати «ФК «Артуа»» і бонуси «Маркасон» (опис містить «kastaua_3pl») — переказ із транзиту сам, «комiсiя N грн» з призначення — «Комісія Каста». Розрахункові 21,6 % щодня (і кнопкою «Підтягнути з API за 7 днів» у шторці правила каналу) замінює реальна комісія з «Звіту по транзакціях рахунку» Kasta (колонка «Гарантійний рахунок, роялті» по кожному замовленню); поповнення гарантійного рахунку, штрафи й виплати бонусів — у підсумку як «інше». Докладно — «Фінанси», розділ 7а, «Виписка майданчика».

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): KASTA_API_TOKEN» | Токен не введено | «Підключення» → «API токен» → «Ввести» |
| «Нема токена Kasta в картці інтеграції» | Дія в угоді без токена | Введіть токен у картці Kasta |
| «Угода не з Kasta (нема номера замовлення Kasta)» | В угоді нема `kasta_order_id` | Дія доступна лише для угод з Kasta |
| «В угоді нема ТТН — створіть ТТН (блок «Доставка») і передайте ще раз» | «Передати ТТН» без номера | Створіть ТТН через hub.kasta.ua і повторіть |
| «Доставлене замовлення відмінити не можна — оформіть повернення на Kasta» | Замовлення вже доставлено | Оформіть повернення в кабінеті Kasta |
| «Замовлення вже відмінено на Kasta» | Повторна відміна | Нічого робити не треба |
| «Kasta: ТТН створюються лише через кабінет hub.kasta.ua (служба «kasta»)» | Для Kasta вибрано іншу службу ТТН | Оберіть службу «Kasta (hub.kasta.ua)» |
| Замовлення прийшло двічі | Kasta ще підключена до KeepinCRM | Вимкніть Kasta в KeepinCRM |

## Для ШІ-співробітників
5`). ШІ бачить результат у «Угодах» (`deals_list`, `deals_get`): джерело «Kasta», додаткове поле `kasta_order_id` і акаунт, з якого прийшла угода (`crm_integration`). Кнопок блоку «Kasta» в інструментах нема — статус на Kasta міняє людина або етап угоди за мапою. Статтю ШІ читає інструментом `help("int-kasta")`.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Kasta hub](int-kasta-hub.md), [Доставки і ТТН](shipping.md).


---

# Епіцентр

Інтеграція з Епіцентр Маркетплейсом приймає замовлення напряму в «Угоди» за офіційним Merchant API: клієнт, товари, статус, а назад на Епіцентр іде статус замовлення і ТТН. Підключається одним натиском: вставити «API ключ» і натиснути «Підключити Епіцентр». Залишки товарів на Епіцентрі оновлює ШІ Аня.

## Можливості
- Замовлення за датою оновлення кожні 5 хвилин; перше опитування — за останні два дні.
- Нові замовлення одразу переводяться в «Підтверджено продавцем»: поки замовлення «Нове», Епіцентр не показує даних покупця.
- Угода створюється лише для робочих статусів; угоди, що вже прийшли з KeepinCRM, знаходяться за номером і не дублюються. Якщо з одним номером замовлення є кілька угод (наприклад, злитий дубль в архіві), оновлення статусу йде в угоду, що в роботі. Злиті 13.10 дублі (50000001–50000005) видалено 15.10 у «Видалену інформацію» — у картці клієнта лишається одна угода.
- «Пов'язані статуси» (14 статусів Епіцентру) → етапи угоди; один статус можна прив'язати до кількох етапів.
- «Передавати статус і ТТН на Епіцентр»: дозволені проміжні статуси CRM надсилає сама, перед «Відправлено» — ТТН угоди.
- Автоматична ТТН на етапах, фід товарів, кілька магазинів зі своїми ключами.
- Блок «Епіцентр» в угоді заповнюється повністю: сума, коментар, історія статусів, оплата, ТТН, доставка й адреса з номером відділення, вартість доставки, отримувач, комісія. Назва блоку і ID відкривають замовлення в кабінеті Епіцентру.

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Маркетплейси» → картка «Епіцентр» → вкладка «Підключення».

1. Рядок «API ключ» → «Ввести» → вставте ключ → «Зберегти ключ». Ключ береться в кабінеті Епіцентру: «Налаштування → Налаштування компанії → Додаткові параметри → «Підключення до API по замовленням»». Зберігається зашифрованим, показуються лише останні символи.
2. «Перевірити» читає одне замовлення зі списку (лише читання).
3. Вкладка «Налаштування продажів»:
   - «Основне»: «Увімкнути інтеграцію», «Джерело угод», «Відповідальний»;
   - «Нові замовлення»: «Підтвердження» — перемикач «Автоматично «Нове» → «Підтверджено продавцем»» (типово ввімкнено), «Автоприйняття», «Зв'язувати товари по»;
   - «Пов'язані статуси» з перемикачем «Передавати статус і ТТН на Епіцентр»;
   - «Передача ТТН на маркетплейс»: статуси, на яких Епіцентр приймає номер ТТН (типово «Підтверджено», «Підтверджено продавцем»), і «спершу перевести» («Нове» → «Підтверджено продавцем» → «Підтверджено»). В угоді — «⋮» рядка ТТН → «Передати ТТН на Епіцентр» (`PATCH …/shipment-number`; лише Нова Пошта, Укрпошта, Meest; статус «Відправлено» не ставиться — його передає етап угоди).
   - «Автоматична відправка ТТН», «Фід для маркетплейсу» («Фід каналу з прайс-листа» `/feed/channel/epicentr.xml` — оголошення Епіцентру з папки «Епіцентр» прайс-листа, ціна «Ціна Епіцентр», залишок зі складу Helomi; його з 14.10 читає ШІ Аня; і фід усього складу).

Унизу — «Зберегти» і «Скасувати зміни».

Дані замовлення пишуться в додаткові поля угоди з ключами `epicentrk_order_id`, `epicentrk_status` (як у KeepinCRM) і `epicentr_*` — повний перелік у таблиці [розділу 5](#5-блок-епіцентр-в-угоді). Поля налаштовуються в «Налаштування → Типи даних → Угоди». Юрособа угод Епіцентру — правилом «Налаштування → Бренди та юрособи → Правила» з умовою «Канал (картка «Інтеграцій»)».

## 2. Підключити одним натиском
1. Введіть «API ключ».
2. Рядок «Одним натиском» → «Підключити Епіцентр» → підтвердіть.
3. CRM ставить налаштування як у KeepinCRM: джерело «Епіцентр», головний відповідальний, товари за назвою, 13 пов'язаних статусів (воронка «Продажі Епіцентр»), статус і ТТН назад на Епіцентр, нові замовлення одразу «Підтверджено продавцем»; вмикає приймання і робить перше опитування.
4. Під кнопкою — застосоване й пропущене. Пропущене допишіть у «Пов'язаних статусах».

Набір «одним натиском» узято з компанії власника. Повторно — «Застосувати налаштування знову».

**Важливо.** Того ж дня вимкніть інтеграцію Епіцентру в KeepinCRM — інакше обидві CRM підтверджуватимуть і рухатимуть ті самі замовлення.

## 3. Приймати замовлення в угоди
Коли інтеграцію ввімкнено, CRM кожні 5 хвилин забирає оновлені замовлення. Нове одразу підтверджується, після чого створюється клієнт (за телефоном) і угода: назва = № замовлення, етап за «Пов'язаними статусами», позиції за вибраним полем. Якщо статус прив'язано до кількох етапів, нова угода стає на перший рядок, а угода на будь-якому з цих етапів не рухається. Стан — у «Стан роботи» і «Журнал подій».

«Адреса доставки» угоди — місто й відділення з номером: «Київ, Відділення №17: бульв. Лесі Українки, 10» (до 15.10 номер губився — лишалась лише вулиця); інший тип точки — «№55555: вул. …»; самовивіз із магазину — назва магазину й адреса.

У списку замовлень Епіцентр не віддає назв міста й відділення — лише в повних даних замовлення. Тому для нової угоди CRM одразу читає повні дані, а для наявної — щойно замовлення на Епіцентрі змінилось (ТТН, статус, доставка, отримувач). Незмінені замовлення повторно не читаються. Угоди, що прийшли з KeepinCRM, дочитуються при першому опитуванні або коли угоду відкрили.

## 4. Статус і ТТН назад на Епіцентр
Увімкніть «Передавати статус і ТТН на Епіцентр». Коли менеджер переводить угоду на етап з мапи, CRM міняє статус на Епіцентрі: дозволені проміжні переходи надсилає сама, перед «Відправлено» — спершу ТТН угоди (Нова Пошта, Укрпошта або Meest), «Скасовано» — з причиною й коментарем. Перехід, якого Епіцентр не дозволяє, — пояснення в журналі картки, не помилка.

## 5. Блок «Епіцентр» в угоді
У картці угоди з джерелом Епіцентр є два блоки.

**«Епіцентр (<джерело>)»** — дані замовлення. Чого Епіцентр не передав, показано як «…». Рядків, яких у Епіцентру не буває (рейтинг покупця, сума зі знижкою, джерело створення, фулфілмент), у блоці нема. Вони з'являються, лише коли поле в угоді вже є, наприклад в угоді з KeepinCRM.

| Рядок | Звідки (Merchant API) | Поле угоди |
| --- | --- | --- |
| ID | номер замовлення | `epicentrk_order_id` (`epicentr_order_id`) |
| Сума замовлення | `subtotal` (товари) | `epicentr_order_amount` |
| Статус замовлення | назва статусу, код — окремо | `epicentrk_status`, `epicentr_status_code` |
| Коментар | коментар покупця і «До доставки: …» | `epicentr_comment` |
| Історія статусу замовлення | Епіцентр історії не віддає — її веде CRM: рядок на кожну зміну статусу (київський час), найновіші зверху. Перший рядок — статус на момент першого читання | `epicentr_status_history` |
| Спосіб оплати, Статус оплати | `paymentProvider`, `paymentStatus` («Кошти заблоковано»…) | `epicentr_payment`, `epicentr_payment_status` |
| ТТН | номер ТТН, який знає Епіцентр (переданий з CRM або створений Епіцентром), з кнопкою «Скопіювати» | `epicentr_ttn` |
| Спосіб доставки | служба | `epicentr_service` |
| ПІБ і телефон отримувача | отримувач (інша особа, якщо її вказано) | `epicentr_recipient_name`, `epicentr_recipient_phone` |
| Інша особа отримувач | `isAlternateRecipient` | `epicentr_other_recipient` |
| Адреса доставки | населений пункт і точка видачі з номером: «Київ, Відділення №17: бульв. Лесі Українки, 10»; інша точка — «№55555: вул. …»; самовивіз — назва магазину й адреса; кур'єр — вулиця, будинок, квартира | `epicentr_delivery_address` (`epicentr_settlement`, `epicentr_office`) |
| Вартість доставки | `deliveryPrice` | `epicentr_delivery_cost` |
| Перетелефоновувати | «Ні», коли покупець просив не телефонувати для підтвердження (`skipCustomerContact`) | `epicentr_callback` |
| Комісія | деталізація рахунку замовлення (`orderCommissionTotal`). Потрібне право ключа на рахунки. Без нього рядок лишається як був, приймання не зупиняється | `epicentr_commission` (`epicentrk_commission` з KeepinCRM) |

В угодах з KeepinCRM адреса лежить у двох полях, «Населений пункт» і «Відділення». Блок показує їх разом в одному рядку.

- Натиск на **назву блоку** або на **ID** відкриває замовлення в кабінеті Епіцентру (`admin.epicentrm.com.ua/oms/orders/<id замовлення>`) у новій вкладці. Кабінет відкриває замовлення за внутрішнім id (uuid), а не за номером. Тому в угоді з KeepinCRM посилання з'являється після першого відкриття угоди: блок нижче знаходить замовлення за номером і запам'ятовує його id. Якщо ви ще не входили в кабінет у цьому браузері, Епіцентр спершу попросить увійти.
- **«?»** праворуч у заголовку відкриває цю статтю у шторці одразу на цьому розділі.

**«Епіцентр <№>»** — живий стан замовлення: статус, доставка, ТТН, історія статусів і дії. Дії приходять із сервера: передати статус, «Передати ТТН» з номером, «Відмінити…» з причиною; кнопка «Оновити». Номер у заголовку теж відкриває замовлення в кабінеті. Коли блок відкривається, CRM бере свіжі дані замовлення з Епіцентру й одразу дописує їх у поля угоди: доставку, ТТН, оплату, суми, id замовлення. Картка перечитується, а в журналі угоди з'являється запис «оновлено з Епіцентру (відкрито угоду)». Статус блок у поля не пише: зміну статусу й рух етапу робить приймання, щоб етап не пропустити.

## 6. Другий магазин Епіцентру (акаунти)
Картка «Епіцентр» → «Підключення» → «Акаунти» → «+ Додати акаунт» → «Назва» і «API ключ» → «Додати акаунт». Новий акаунт вимкнений: перевірте ключ і ввімкніть (або «Підключити Епіцентр» у його картці). У акаунта свої ключ, налаштування продажів і журнал.

## Усі замовлення, не лише нові (14.10)
Приймання створює угоду для замовлення в будь-якому статусі Епіцентру (і завершені, і скасовані) — етап за мапою або за змістом статусу. У картці каналу → «Стан роботи» → «Вивантажити замовлення» за N днів назад (за датою зміни замовлення).

## Фінанси каналу: нарахування, комісія, виплата (16.10)
Гроші Епіцентр у «Фінансах» — правило каналу у «Фінанси → Звірка» → рядок «Епіцентр» (кожен акаунт — своє правило; типово вимкнено). Увімкнене правило в момент «гроші наші» (при замовленні, коли угода виграна чи на вибраних етапах) проводить дохід угоди в транзитний гаманець «Транзит · Епіцентр» (угода стає «сплаченою») і комісію майданчика витратою по угоді; угода скасована — сторно. Заготовка комісії: 17 % від суми угоди. Виплата Епіцентр на рахунок — правило імпорту «Виплата каналу» або кнопка у «Вхідних»: переказ, а не другий дохід; баланс транзитного гаманця — скільки Епіцентр ще винен. Докладно — стаття «Фінанси», розділ 7а.

З 20.10 увімкнено: «Транзит · Епіцентр», дохід — коли угода виграна й оплачена на майданчику (monobank, картка), комісія — поле `epicentr_commission` з API (порожнє чи 0 — комісії нема, рішення власника 20.10), одразу при замовленні з того самого транзиту (мінус — ми винні Епіцентру). Оплата рахунку Епіцентру за комісію з банку категорією «Комісія Епіцентр» — переказ у цей транзит, а не друга комісія.

**Оплата замовлення (з 22.10).** Передоплату Епіцентр платить кожне замовлення окремо через еквайринг monobank: рядок виписки «Оплата замовлення 58372062. Покриття за проведені трансакції згідно договору еквайринга Еквайринг, MM033489, Загалом 130.00 грн. Комісія банку 1.69 грн.» від АТ «УНІВЕРСАЛ БАНК». Правило імпорту «Оплата замовлень (еквайринг monobank, Епіцентр)» знаходить угоду з цим номером замовлення: угода вже нарахована в «Транзит · Епіцентр» — переказ з транзиту на рахунок (підстава — угода) і комісія банку з транзиту; ще ні — дохід угоди на 130 ₴ і комісія 1,69 ₴ витратою по угоді; угоди нема — рядок у «Вхідних» з поясненням. Докладно — стаття [Фінанси](finance.md), розділ 7, п. 11. До 22.10 ці рядки правило «Кешбек і відсотки банку» клало в «Інші доходи»; два такі рядки (15.10 і 19.10) перенесено скриптом.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): EPICENTR_TOKEN» | Ключ не введено | «Підключення» → «API ключ» → «Ввести» |
| «Нема API ключа Епіцентру в картці інтеграції» | Дія в угоді без ключа | Введіть ключ у картці |
| «Угода не з Епіцентру (нема номера замовлення Епіцентру)» | В угоді нема `epicentrk_order_id` | Дія лише для угод з Епіцентру |
| «В угоді нема ТТН — створіть ТТН (блок «Доставка») і передайте ще раз» | «Відправлено» без ТТН | Створіть ТТН в угоді й повторіть |
| У журналі: перехід не дозволено | Епіцентр не приймає такий перехід статусу | Перевірте «Пов'язані статуси» або змініть статус у кабінеті |
| Замовлення рухаються двічі | Епіцентр ще підключений до KeepinCRM | Вимкніть Епіцентр у KeepinCRM |
| Назва блоку без посилання | В угоді ще нема id замовлення Епіцентру (угода з KeepinCRM) | Відкрийте угоду ще раз після того, як блок «Епіцентр <№>» завантажився, або натисніть «Оновити» |
| «Комісія» порожня | Ключ API не має права на рахунки (`processing.my.invoice.read`) | Дайте ключу це право в кабінеті Епіцентру або дивіться комісію в кабінеті |

## Для ШІ-співробітників
5`). ШІ бачить результат у «Угодах» (`deals_list`, `deals_get`): джерело «Епіцентр», поля `epicentrk_order_id`, `epicentrk_status`, `epicentr_*` (таблиця розділу 5: ТТН `epicentr_ttn`, адреса `epicentr_delivery_address`, історія `epicentr_status_history` тощо) і акаунт, з якого прийшла угода (`crm_integration`). Ці поля заповнює приймання — ШІ їх не редагує. Статтю ШІ читає інструментом `help("int-epicentr")`.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Доставки і ТТН](shipping.md), [Kasta](int-kasta.md).


---

# OLX

Інтеграція з OLX через Partner API приносить переписки з покупцями в «Переписки», дає створити угоду з розмови «OLX Доставки» і оновлювати оголошення й ціни зі складу. Окремого списку замовлень Partner API OLX не віддає, тому угода з'являється з переписки, а не опитуванням, як у Prom чи Rozetka.

## Можливості
- Підключення акаунта OLX через Partner API; токен оновлюється сам, картка показує, скільки днів він ще дійсний.
- Переписки з покупцями — у «Переписках»; стан полера видно в картці.
- Угода з переписки: ім'я й телефон покупця, оголошення, товар за артикулом; повторно з тієї самої розмови угода не дублюється.
- Джерело, відповідальний, чати й оператори, автоматична ТТН на етапах, зв'язок товарів.
- Оновлення оголошень і цін зі складу.

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Маркетплейси» → картка «OLX» → «Підключення».

1. Ключі застосунку OLX Partner API: «Client ID» і «Client secret» → «Ввести» → «Зберегти ключ». Їх видає OLX, коли ви реєструєте застосунок у партнерській програмі.
2. Сам акаунт OLX підключається кнопкою «Підключити OLX» у «Переписках» → «Стан каналів» (вхід в OLX і дозвіл доступу).
3. «Перевірити» читає профіль: успіх — «акаунт: <ім'я>»; якщо OLX не підключено — підказка, куди натиснути.
4. «Стан роботи»: «Підключення OLX» (підключено / не підключено), «Акаунт», «Токен дійсний ще N дн.», «Полер «Переписок»».

Кількох акаунтів OLX поки нема — одна картка на організацію.

## 2. Угода з переписки OLX
Угоду створює менеджер з розмови «OLX Доставки» в «Переписках». CRM бере ім'я й телефон покупця, оголошення (назву, ціну) і шукає товар: за артикулом, потім за додатковим полем товару «Оголошення на ОЛХ», потім за списком оголошень ШІ Віки; не знайшла — вільна позиція з назвою оголошення. В угоді з'являються поля `olx_order_id` (за ним повтор не дублюється), `olx_advert_id`, `olx_conversation_id`.

Де саме кнопка створення угоди в «Переписках» —.

## 3. Налаштування продажів OLX
Вкладка «Налаштування продажів»: «Основне» («Увімкнути інтеграцію», «Джерело угод», «Відповідальний»), «Нові замовлення» («Автоприйняття», «Зв'язувати товари по»), «Чати» («Чати про товари», «Чати про замовлення», «Оператори», «Відкрити переписки →»), «Автоматична відправка ТТН». «Пов'язаних статусів» нема: статусів замовлень API OLX не віддає. Унизу — «Зберегти».

## 4. Оголошення і ціни
«Підключення» → «Стан роботи» → «Оновлення товарів»: автоматично чи вручну оновлюються оголошення зі складу; «Оновити зараз». Ціни оголошень веде ШІ Віка.

Віка також виправляє текст опису оголошення точними замінами (наприклад, артикул кольору, щоб оголошення збігалося зі складом): бере оголошення з OLX, міняє лише вказані фрагменти, ціну й решту полів лишає як були, і пише зміну в свій журнал. Якщо фрагмента в описі нема або він трапляється кілька разів, оголошення не чіпається.

**«Виставити на OLX»** (програма Віки): вибрані оголошення, які OLX вимкнув (закінчився ліміт, термін, не оплачено), Віка вмикає знову. Спершу розрахунок без витрат: які оголошення можна увімкнути (на модерації, заблоковані тощо — пропускаються з поясненням), скільки слотів уже є в куплених пакетах, що докупити — найдешевша комбінація з живого прайсу OLX (пакети від 3 і окремі розміщення: 4 оголошення — пакет на 3 + 1 окремо, а не два пакети), сума, баланс рахунку OLX і чого не вистачає. Ціну окремого розміщення OLX наперед не каже: поки її не знаємо — оцінка «≈» (половина пакета на 3), після першої покупки в категорії — точна. Купити й увімкнути може лише власник або адміністратор: сума має збігтися з підтвердженою, за раз — не більше 20 000 грн; гроші справжні. Кожен прогін — у журналі (що куплено, що увімкнено, що не вдалося); прогін, обірваний рестартом, позначається «перервано — перевірте кабінет OLX».

## 5. Блок «OLX» в угоді
У картці угоди з джерелом OLX є блок «OLX (<джерело>)» з даними, що прийшли з переписки (`olx_*`); чого нема — «…». ID показується без посилання: окремої сторінки замовлення в кабінеті OLX Partner API не дає. «?» у заголовку блоку відкриває цю статтю у шторці.

## Фінанси каналу: нарахування, комісія, виплата (16.10)
Гроші ОЛХ у «Фінансах» — правило каналу у «Фінанси → Звірка» → рядок «ОЛХ» (кожен акаунт — своє правило; типово вимкнено). Увімкнене правило в момент «гроші наші» (при замовленні, коли угода виграна чи на вибраних етапах) проводить дохід угоди в транзитний гаманець «Транзит · ОЛХ» (угода стає «сплаченою») і комісію майданчика витратою по угоді; угода скасована — сторно. Заготовка комісії: 20 грн + 3 % від суми угоди лише при оплаті через ОЛХ Доставку (поле «Спосіб оплати» містить «ОЛХ дост…», служба доставки ОЛХ або checkbox UAPay); комісію, яку надсилає ШІ Едуард, проведено одразу точною сумою, а табличка комісій ОЛХ Марії вже не просить «записати витратою». Виплата ОЛХ на рахунок — правило імпорту «Виплата каналу» або кнопка у «Вхідних»: переказ, а не другий дохід; баланс транзитного гаманця — скільки ОЛХ ще винен. Докладно — стаття «Фінанси», розділ 7а.

З 20.10 увімкнено: «Транзит · ОЛХ». Угоду ОЛХ Доставки, яку ШІ Едуард заводить через Telegram (джерело угоди «ОЛХ»), «Фінанси» вважають каналом ОЛХ. Дохід — коли угода виграна, лише при ОЛХ Доставці; комісія — точна від Едуарда або 20 грн + 3 %, одразу при замовленні з того самого транзиту. Виплата «ЮАПЕЙ» («…OLX.1» — це ОЛХ Доставка, не Prom) — переказ із транзиту сам.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «OLX не підключено — «Переписки» → «Стан каналів» → «Підключити OLX»» | Акаунт OLX не авторизовано | Підключіть у «Переписках» |
| «не задано (у картці чи .env): OLX_PARTNER_CLIENT_ID, OLX_PARTNER_CLIENT_SECRET» | Ключі застосунку не введено | Введіть «Client ID» і «Client secret» |
| «OLX не віддав профіль» | OLX відповів без даних | Перепідключіть OLX і перевірте знову |
| «Полер «Переписок»: помилка …» | Збій отримання переписок | Подивіться текст помилки, перепідключіть OLX |

## Для ШІ-співробітників
5`). ШІ бачить угоди з OLX у «Угодах» (`deals_list`, `deals_get`): джерело і поля `olx_order_id`, `olx_advert_id`, `olx_conversation_id`. Статтю ШІ читає інструментом `help("int-olx")`.

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


---

# Сайти (WooCommerce та інші): акаунти, поля, вебхук

Інтеграція «Сайти» приймає замовлення з ваших інтернет-магазинів на WooCommerce прямо в «Угоди». Кожен сайт — окрема картка зі своїм перемикачем, адресою вебхука, джерелом, відповідальним, мапою статусів, мапінгом полів і журналом. Найпростіше підключення — замінити на сайті адресу вебхука на «Вебхук url» з картки: поля вже зв'язані, перше замовлення саме ввімкне картку.

## Можливості
- Окрема картка на кожен сайт (акаунт каналу «Сайти»); стільки сайтів, скільки потрібно.
- «Вебхук url» з токеном в адресі — підпис і секрет не потрібні; тіло — JSON або форма.
- Вебхук WooCommerce з підписом (теми «Замовлення створено» і «Замовлення оновлено») і секретом.
- Вкладка «Поля»: «зовнішня назва поля → поле CRM» для контрагента, угоди й товарів, «Як у KeepinCRM».
- «Історія запитів акаунту»: що прийшло, що створено, які поля пропущено; «Перевірити мапінг», «Обробити ще раз».
- Повтор того самого замовлення не створює дубля; наявний клієнт за телефоном чи email дозаповнюється.
- Мапа статусів WooCommerce → етап, автоматична ТТН, фід товарів, оновлення товарів на сайтах.
- Спільна картка «Усі сайти (WooCommerce)»: чат із сайтів, фід, «усі сайти разом».

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Сайти» → картка сайту (підписана доменом, напр. «shop.com.ua»).

У картці сайту три вкладки:
- **«Підключення»** — перемикач «Інтеграція» (приймати замовлення цього сайту в угоди; зберігається в базі), «Секрет підпису вебхука» (потрібен лише для адреси з підписом), «Логотип» («Завантажити», «Взяти з сайту», «Стандартний»), блок «Вебхук» з «Вебхук url» і «Адреса з підписом» (кнопки «Скопіювати»), «Стан роботи», «Журнал подій», «Останні запити від сайту», «Прибрати акаунт».
- **«Поля»** — мапінг полів і «Історія запитів акаунту» (розділи 4–5).
- **«Налаштування продажів»** — «Основне» (перемикач, «Назва», «Компанія», «Джерело угод», «Відповідальний»), «Нові замовлення», «Вебхук url», «Пов'язані статуси», «Автоматична відправка ТТН», «Фід для маркетплейсу».

Спільна картка **«Усі сайти (WooCommerce)»** у тій самій вкладці: блок «Сайти» (список усіх сайтів зі станом і «+ Додати сайт»), ключ «Сайти чату (slug:Назва:ключ, через кому)» для чату з сайту, «Стан роботи» з оновленням товарів. Її перемикач — «приймати замовлення з усіх сайтів разом»; коли він увімкнений, перемикачі окремих сайтів сайт не вимикають.

Джерело угод за замовчуванням — назва компанії сайту; бренд угоди визначається за цією назвою (профіль у «Налаштування → Компанії та реквізити»). Юрособа — правилом «Налаштування → Бренди та юрособи → Правила» з умовою «Канал (картка «Інтеграцій»)».

## 2. Підключити сайт через «Вебхук url»
1. Картка сайту → вкладка «Поля» → блок «Вебхук url» → «Адреса для сайту» → «Скопіювати».
2. На сайті замініть адресу вебхука KeepinCRM (`https://api.keepincrm.com/callbacks/webhook/…`) на цю. Тіло запиту лишається тим самим — поля вже зв'язані.
3. Зробіть тестове замовлення на сайті.
4. Перший справжній запит сам вмикає картку сайту (один раз; якщо вимкнули вручну — далі діє перемикач). «Стан» покаже, коли адресу активовано.
5. Перевірте «Історію запитів акаунту» і нову угоду в «Угодах».

«Нова адреса» генерує новий токен: стара адреса перестане приймати замовлення, її треба замінити на сайті.

## 3. Підключити через вебхук WooCommerce з підписом
1. «Підключення» → «Секрет підпису вебхука» → «Ввести» → придумайте секрет → «Зберегти ключ».
2. На сайті: WooCommerce → Налаштування → Додатково → Вебхуки → два вебхуки на «Адресу з підписом» з картки: теми «Замовлення створено» і «Замовлення оновлено», секрет — той самий.
3. Увімкніть перемикач «Інтеграція» картки сайту.

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

## 4. Поля контрагента, угоди і товарів
Вкладка «Поля»:
- **«Поля контрагента»**: «Тип контрагента» (Клієнт / Лід), «Головний відповідальний», «Джерело», «Статус» (номер статусу контрагента з KeepinCRM), «Теги» (через кому) і таблиця «Зовнішня назва поля» → «Helomi: поля контрагента».
- **«Поля угоди»**: «Етап» (якщо статус замовлення не знайшовся в мапі статусів) і таблиця «змінна → поле угоди»: назва, коментар, ID замовлення, статус, тип оплати, сума, знижка, теги, доставка (служба, місто, відділення, адреса, отримувач, телефон, ТТН, післяплата), додаткові поля.
- **«Поля товарів»**: «Масив товарів *» (напр. `line_items`), «Артикул», «Назва», «Кількість», «Знижка (необов'язково)»; «Ціна товару передається в копійках» (сайт шле 12500 замість 125.00), «Тип знижки».

«+ Додати» — новий рядок, «Прибрати рядок» — прибрати. Змінні пишуться так само, як у вхідних вебхуках: `a.b`, `a[].b`, `{{a}} {{b}}`, `/текст/`. «Як у KeepinCRM» повертає початкове заповнення. «Зберегти» / «Скасувати зміни» — у панелі внизу. Змінювати поля може лише адміністратор.

Чого нема в запиті, береться зі стандартного розбору WooCommerce (billing, line_items). Значення, яке не підходить під тип додаткового поля, замовлення не зупиняє: поле пропускається, причина — в історії й журналі.

## 5. Історія запитів: перевірити й обробити ще раз
«Поля» → «Історія запитів акаунту» (до 200 останніх запитів): «Дата», «Клієнт», угода, «Помилки», «Відповідь», тіло («показати»).
- «Змінні» — назви полів запиту з прикладами; клік вставляє змінну в рядок полів, де стоїть курсор.
- «Перевірити мапінг» — показує, що вийде, нічого не створюючи.
- «Обробити ще раз» — обробляє запит за поточними полями: угода створиться або оновиться, дубля не буде.
- «Оновити» — перечитати історію.

## 6. Налаштування продажів сайту
- «Пов'язані статуси»: статус WooCommerce (Очікує оплати, В обробці, Утримується, Виконано, Скасовано, Повернено кошти, Не вдалося) → етап угоди. Передавати статус назад на сайт поки не можна.
- «Автоматична відправка ТТН»: етапи й служба доставки.
- «Зв'язувати товари по»: артикул, ID маркетплейсу або назва.
- «Фід для маркетплейсу»: «Фід каналу з прайс-листа» (`/feed/channel/sites-<slug>.xml` — товари саме цього сайту з його id, ціною з прайс-листа і залишком зі складу) і фід усього складу `/feed/all.xml`. З 14.10 у налаштуваннях імпорту товарів на сайті адресу фіду KeepinCRM замінюють на фід каналу (робить власник).

## 7. Додати чи прибрати сайт
1. Картка «Усі сайти (WooCommerce)» → блок «Сайти» → «+ Додати сайт».
2. «Компанія» (джерело угод сайту) і «Домен сайту» (з нього складеться адреса вебхука) → «Додати сайт».
3. Відкриється картка нового сайту, вимкнена. Далі — розділ 2 або 3.

Прибрати: картка сайту → «Підключення» → «Прибрати». Угоди лишаються; зникають секрет, налаштування, журнал і історія запитів.

## 8. Побачити, що клієнт оплатив на сайті
Коли клієнт платить карткою на сайті, скасовує несплачене замовлення чи отримує гроші назад, сайт сам оновлює угоду: поле «Статус оплати:», нотатку «Сайт <домен>: статус оплати — …» з деталями оплати і рядок «Оплата: …» у коментарі угоди.

1. Відкрийте угоду сайту — її назва починається з префікса сайту, напр. «PP-453».
2. У «Даних угоди» подивіться рядок «Коментар»: «Оплата: Оплачено (Monobank · Apple Pay · … · 719,00 ₴ · статус success · RRN … · рахунок …)».
3. Ті самі деталі — у нотатці «Сайт <домен>: статус оплати — Оплачено» у стрічці праворуч.

Статуси оплати: «Оплачено», «Очікує оплати», «Не оплачено», «При отриманні», «Повернено». Решта коментаря (коментар покупця, юрособа, набори) не змінюється, а зміну видно в журналі угоди від імені «Сайт». Коментар угод з Telegram, який пише ШІ Едуард, статус оплати не переписує.

> [!NOTE]
> ШІ Олесь бере оплату угоди сайту з цього рядка: «Оплата: Оплачено» — угода оплачена, Олесь створює ТТН і передає її на збірку. У «Фінанси» оплата сама не проводиться, тож «Сплачено» в угоді лишається 0, доки платіж не внесуть.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «пропущено: …» в «Останніх запитах від сайту» | Перемикач сайту вимкнено | Увімкніть «Інтеграція» в картці сайту |
| «Невірний підпис вебхука» (відповідь сайту 403) | Секрет на сайті й у картці різний | Введіть однаковий секрет або перейдіть на «Вебхук url» |
| «Невідома адреса вебхука» (404) | Адресу замінили кнопкою «Нова адреса» або сайт прибрано | Скопіюйте актуальну адресу з картки |
| «Очікую замовлення (JSON-об'єкт або форму)» | Сайт надіслав порожнє чи інше тіло | Перевірте налаштування вебхука на сайті |
| В історії поле пропущено з причиною | Значення не підходить під тип додаткового поля | Виправте рядок у «Полях», «Зберегти», «Обробити ще раз» |
| Замовлення прийшло двічі | Сайт ще шле і в KeepinCRM, і з підписом, і на «Вебхук url» | Залиште одну адресу |
| Клієнт оплатив, а «Сплачено» в угоді 0 | Оплата з сайту лише позначає угоду оплаченою, у «Фінанси» вона сама не проводиться | Дивіться «Оплата: …» у коментарі угоди; платіж у «Фінанси» вносить людина |

## Для ШІ-співробітників
5`). ШІ бачить результат у «Угодах» (`deals_list`, `deals_get`): джерело (назва компанії сайту), поле `sites_order_id` (`<slug>:<номер>`) і акаунт сайту (`crm_integration`, напр. `sites-pocoprint`). Оплату на сайті ШІ бачить у полі «Статус оплати:» (`status_oplati_946`) і в рядку «Оплата: …» коментаря угоди. Статтю ШІ читає інструментом `help("int-sites")`.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Вебхуки](int-webhook.md), [Склад і товари](products.md).


---

# Webhook

Інтеграція Webhook з'єднує Helomi з будь-яким сервісом у дві сторони. Вхідні вебхуки приймають дані з сайту, форми чи іншого сервісу (WooCommerce, Contact Form 7, Weblium, Facebook Leads через Apix-Drive, WIX) і за вашим мапінгом створюють контрагента, угоду й завдання. Вихідні — це тригери з дією Webhook: коли в CRM стається подія, дані йдуть в інший сервіс (SMS, Viber, Telegram, залишки…).

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

## 1. Налаштування
Дорога до вхідних: «Налаштування» → «Інтеграції» → вкладка «Інше» → картка «Webhook»; або «Налаштування → Автоматизація → Вхідні вебхуки». Дорога до вихідних: «Налаштування → Автоматизація → Тригери (Webhook)».

Дивитися може кожен з доступом до «Інтеграцій»; створювати й змінювати — адміністратор або людина з доступом до «Налаштувань CRM». Ключів у картці нема («Ключ доступу: Не потрібен.»). «Стан роботи» показує «Вхідних вебхуків: N з M увімкнено» і «Тригерів Webhook: N з M увімкнено».

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

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

## 3. Мапінг: контрагент, угода, завдання
- **Контрагент** (створюється завжди): «Тип контрагента» (Лід / Клієнт), «Головний відповідальний», «Джерело», «Статус ліда (ID)», «Теги (через кому)», «Наявний контрагент» (що робити, якщо такий уже є), і таблиця «Поле CRM» ← змінна; «+ Додати змінну». Обов'язково — «Назва компанії» або «Контактна особа».
- **«Створювати угоду»**: обов'язково «Назва угоди»; «ID замовлення» не дасть створити дубль. «Воронка», «Етап», «Товари» — масив товарів у запиті і чотири стандартні змінні елемента (назва, кількість, ціна, артикул); артикул шукається на складі.
- **«Створювати завдання»**: обов'язково «Назва завдання» (чітка назва в скісних рисках, напр. `/Передзвонити/`), «Термін, хвилин від запиту».

Синтаксис змінних: `a.b`, `a[].b`, `a[1].b`, `$.x`, `/текст/` (постійний текст), `{{a}} {{b}}` (склеїти кілька).

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

## 5. Вихідні: тригер з дією Webhook
1. «Налаштування → Автоматизація → Тригери (Webhook)» → «+ Новий тригер» або «З шаблону…» (Viber і SMS через TurboSMS, SMS Club, AlphaSMS, Telegram, Хорошоп, Kasta, рух товару та інші).
2. «Назва», «Таблиця з даними», «Умова виконання» (напр. `stage.name == 'Відправлено'`, `result == 'successful'`, `AND` / `OR`), «Метод запуску» («Відразу», «З затримкою» — «Затримка, хвилин», «На основі поля з типом дата» — поле, «До дати» / «Після дати», дні, година).
3. Дія: «URL», «Метод відправки», «Content-Type», «Успішний статус запиту», «Заголовки запиту (Headers)», «Параметри запиту (Params)», «Тіло запиту (Body)» зі змінними (товари — `{{#jobs}}…{{/jobs}}`), «Успішна відповідь (Response)» — значення з відповіді в поле запису.
4. «Перевірка» → «Виконати на записі» — пробний запуск. «Журнал спрацювань» — останні 100 спрацювань; ключі в запитах приховано.

Імпорт і дзеркало KeepinCRM тригерів не запускають; тригер спрацьовує лише на нові дії. Докладно про тригери — [Налаштування: тригери](settings-triggers.md).

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

## Для ШІ-співробітників
5`). Записи, створені вебхуком, ШІ бачить у «Клієнтах», «Угодах», «Завданнях» звичайними інструментами. Статтю ШІ читає інструментом `help("int-webhook")`.

## Додаткова інформація
- Пов'язані статті: [Вебхуки](settings-webhooks.md), [Налаштування: тригери](settings-triggers.md), [Сайти](int-sites.md).


---

# Нова Пошта

Інтеграція з Новою Поштою дає створювати ТТН прямо з угоди, друкувати стікери, бачити статус посилки й автоматично переводити угоду на етап за статусом доставки. Налаштування повторюють KeepinCRM: що писати в ТТН, скільки місць і які габарити, кілька відправників (акаунтів) зі своїми ключами й доступами, зв'язок статусів і полів угоди.

## Можливості
- Створення ТТН з картки угоди: шторка «Створити ТТН» з даними угоди й дефолтами акаунта; «Додати ТТН» — записати наявний номер.
- Кілька акаунтів-відправників, у кожного свій ключ API, відправник, дефолти форми і список людей з доступом.
- «Додаткова інформація», внутрішній номер, супровідні документи, тип отримання грошей, кількість місць і габарити — за налаштуваннями.
- «Пов'язані статуси»: статус відправлення → етап угоди; окремо — з огляду на тип оплати.
- «Пов'язані поля»: з яких полів угоди брати місто, відділення, одержувача й телефон.
- Довідник міст і відділень Нової Пошти у формі.
- Автоматична ТТН на етапі угоди — у налаштуваннях каналу продажів (Prom, Rozetka, сайти…).

## 1. Налаштування
Налаштовує адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Перевізники» → картка «Нова Пошта». Картка одразу відкриває вкладку «Налаштування»; поруч — «Підключення».

1. **Ключ.** Найпростіше — у «Налаштування» → «Акаунти» (розділ 2): кожен акаунт має свій «API ключ». Ключ береться в особистому кабінеті: my.novaposhta.ua → Налаштування → Безпека. У «Підключенні» є ще загальний «API ключ» картки — він діє, коли акаунтів нема.
2. **Перевірка.** «Перевірити» (у «Підключенні» або в картці акаунта) читає довідник відправників; успіх — «відправник: <назва>». У картці акаунта перевірка ще й підставляє знайденого відправника в порожні поля.
3. **Увімкнення.** Блок «Інтеграція» → «Увімкнути інтеграцію»: створювати ТТН і трекати відправлення цієї служби з угод.
4. **Зберегти.** Унизу липка панель «Скасувати зміни» / «Зберегти»; стан «Є незбережені зміни» / «Змін немає». Зберігати може лише адміністратор. Ключ акаунта зберігається окремо одразу кнопкою «Зберегти ключ».

Ключі зберігаються зашифрованими і назад не показуються — лише «задано (••••ca93)».

## 2. Акаунти відправників і доступи
1. «Акаунти» → «+ Додати акаунт» → «Назва акаунта (як підписати відправника)» → «Додати». Незбережені зміни сторінки перед цим зберігаються.
2. Натисніть рядок акаунта — він розгорнеться: перемикач «Увімкнено», «Перевірити», «Прибрати акаунт».
3. Групи полів акаунта:
   - «Акаунт» — «Назва»: як підписати відправника у списку акаунтів і формі ТТН (можна змінити будь-коли, потім «Зберегти»);
   - «Доступ до API» — «API ключ»;
   - «Відправник» — «Відправник» і «ПІБ відправника» вибираються зі списку кабінету Нової Пошти (список підтягується ключем акаунта сам, кнопка «Оновити список»; обрали ПІБ — «Телефон» підставляється), «Телефон», «Місто» (з довідника Нової Пошти), «Відділення відправки». Поки ключа нема або Нова Пошта не відповідає — поля вписуються вручну, під ними підказка чому;
   - «Відправлення за замовчуванням» — «Метод доставки» (Відділення-Відділення, Відділення-Двері, Двері-Відділення, Двері-Двері), «Тип вантажу», «Платник доставки», «Платник комісії за післяплату», «Опис вантажу», «Номер пакування», «Форма оплати», «Контроль оплати»;
   - «Додаткова інформація» — що писати у внутрішній номер ТТН саме цього відправника: «Як у налаштуваннях картки», «Не заповнювати внутрішній номер відправлення», «Розмістити ID угоди…», «Розмістити назву угоди…», «Розмістити інформацію з поля товару…»;
   - «Розмір і вага відправлення» — довжина, ширина, висота, загальна вага, «Загальний об'єм (м³)» (0 — рахується з габаритів).
4. **Доступи.** Блок «Доступи · <акаунт>»: після додавання акаунта доступу нема ні в кого. Поставте «Показати» тим, хто створює ТТН цим відправником. Без галочки акаунта не видно у формі ТТН; адміністратор бачить усі. ШІ-співробітники в списку позначені «ШІ».
5. «Прибрати акаунт» — ключі й дефолти форми зникають, угоди лишаються.

У рядку акаунта видно стан: «без ключа», «увімкнено» або «вимкнено».

## 3. Що писати в ТТН: додаткова інформація, місця, габарити
- «Додаткова інформація»: «Без автогенерації», «Назва товару», «Артикул і кількість», «Назва товару і кількість» або «Шаблон» (доступні `{deal.title}`, `{deal.id}`, `{items}`).
- «Внутрішній номер відправлення»: «Не заповнювати», «ID угоди», «Назва угоди» або «Поле товару». Акаунт може мати свій вибір («Додаткова інформація» в акаунті, розділ 2) — він головніший.
- «Супроводжуючі документи»: текст.
- «Тип отримання грошей» за замовчуванням: «Без зворотної доставки» або «У відділенні» (пов'язане поле угоди, розділ 4, головніше).
- «Кількість місць»: «На основі кількості товарів», «Фіксована кількість» або «З поля товару».
- «Вага й габарити з товарів»: галочка «Заповнювати вагу й габарити посилки з товарів угоди» — посилка рахується з товарів угоди й кількості, а не з акаунта ([Доставки і ТТН, 3а](shipping.md#3а-вага-й-габарити-з-товарів-угоди)).
- «Розмір відправлення»: «Загальні параметри відправлення» або «Заповнити кожне місце окремо»; галочки «Увімкнути параметри відправлень для вибору» (у формі ТТН — список збережених габаритів) і «Заповнити контроль оплати, якщо без зворотної доставки».

## 4. Пов'язані поля угоди
Блок «Пов'язані поля»: з яких полів угоди брати «Місто», «Відділення», «Одержувач», «Телефон» у форму ТТН (наприклад, з полів замовлення Prom чи Rozetka). Порожньо — з клієнта й адреси доставки угоди. Якщо в «Місто» чи «Відділення» обрано поле з повною адресою (наприклад, «Адреса доставки (prom)» — «Київ, Відділення №25 (до 30 кг): вул. …»), у форму йдуть розібрані місто й № відділення, а не весь рядок; адреса без номера відділення поле не заповнює. Поле може містити всю адресу маркетплейсу — як «Адреса доставки (prom)»: «м. Черкаси (Черкаська обл.), №7 (до 30 кг на одне місце): вул. Петра Дорошенка, 7». Тоді в «Місто» йде лише місто («Черкаси», з областю для вибору зі списку), у «Відділення» — номер («7»), і шторка одразу вибирає їх зі списку Нової Пошти. Так налаштовано й типово (як у KeepinCRM): «Місто» і «Відділення» ← «Адреса доставки (prom)». «Тип отримання грошей» — поле-список угоди і таблиця «Значення для типу отримання грошей» → «Тип оплати» (Без зворотної доставки / У відділенні / Накладений платіж), «+ Додати».

## 5. Статус доставки → етап угоди
- «Пов'язані статуси»: «Зовнішній статус» → «Етап» (наприклад, «Відправлення отримано» → «Виграно», «Відмова» → «Повернення»). Без рядка етап не змінюється. Статуси Нової Пошти з датою підтримують шаблони та «починається з». Тексти зі списку (з довідки API НП) зіставляються за **кодом статусу**: НП пише інакше («Прибув у відділення», «Відправлення прямує до м. Фастів.»), і рядок «Прибув на відділення» чи «Відправлення прямує до міста YYYY.» спрацьовує саме за кодом. Назви з KeepinCRM («Отримано», «Прибуло у відділення», «Відмова») теж спрацьовують — під рядком видно, на які статуси НП; рядок без відповідника позначено.
- **«Міняти етап, коли посилка»** (16.10): етап за статусом міняється лише на позначених станах посилки — типово «відправлена / в дорозі», «у відділенні», «отримана», «повернення». Поки посилка «створена, ще не відправлена», етап стоїть, навіть якщо для такого статусу є рядок; щоб і він діяв, позначте «створена, ще не відправлена».
- Той самий статус можна зв'язати з етапами різних воронок, як у KeepinCRM: «Відправлення отримано» → «Отримано [Продажі]» і → «Отримано Покупцем [Дропшипери продаж]». Угода переходить на етап своєї воронки. Якщо статус зв'язаний лише з етапами інших воронок (кількох) — угода не рухається. Двічі той самий статус з тим самим етапом — помилка «… з тим самим етапом вказано двічі».
- «Пов'язані типи оплат та статуси»: те саме з огляду на тип оплати («Накладений платіж» + «Відправлення отримано» → «Виграно»). Ці рядки головніші. Рядок можна лишити без етапу — тоді для цього статусу діють звичайні «Пов'язані статуси».

Етап змінюється, коли оновлюється статус ТТН — кнопкою «Оновити статус» у «⋮» рядка ТТН в угоді. Архівні угоди не рухаються; у журналі угоди автор — «трекінг доставки».

- **Автооновлення й архів отриманих** (над «Пов'язаними статусами»): «Оновлювати статуси ТТН автоматично» кожні N хв (типово так, 30 хв) — статуси відкритих угод оновлюються самі, без кнопки «Оновити статус»; «Посилку отримано → угода «Виграно» в архів» (типово так) — коли перевізник каже «отримано», угода переходить на етап «Виграно» своєї воронки й іде в архів навіть без рядка «Пов'язаних статусів». Відмови й повернення не архівуються.

## 6. Створити ТТН з угоди
Картка угоди → блок «Доставка» → «+» → шторка «Створити ТТН» → вкладка «Нова Пошта» → акаунт відправника → перевірте отримувача, місто, відділення, оплату й місця → «Створити ТТН». Режим «Додати ТТН» записує вже наявний номер. Покроково — стаття [Доставки і ТТН](shipping.md).

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): NP_API_KEY» | Ключ не введено | Введіть «API ключ» в акаунті або в «Підключенні» |
| Помилка Нової Пошти після «Перевірити» | Ключ недійсний | Створіть новий ключ у my.novaposhta.ua |
| «Нема доступу до акаунта «…» Нова Пошта — надайте його в картці перевізника → …» | Людині не поставлено «Показати» в «Доступах» | Адміністратор ставить галочку |
| «Акаунт «…» вимкнено в налаштуваннях Нова Пошта» | Перемикач акаунта вимкнено | Увімкніть акаунт |
| «Вкажіть назву акаунта» | Порожня назва при додаванні | Введіть назву |
| «Телефон отримувача «…» — потрібен формат +380XXXXXXXXX» | Неправильний телефон у формі ТТН | Виправте телефон |
| «Не вказано місто отримувача» / «Не вказано отримувача (ПІБ)» | Немає даних у формі | Заповніть або налаштуйте «Пов'язані поля» |
| «Кількість місць: від 1 до 50» | Завелике число | Вкажіть менше |
| «Список з Нової Пошти недоступний: …» під «Відправником» | Ключ акаунта не збережено або Нова Пошта його відхилила | Збережіть «API ключ», «Перевірити», «Оновити список»; або впишіть відправника вручну |
| «Пов'язані статуси: статус «…» з тим самим етапом вказано двічі» | Повтор рядка | Приберіть зайвий рядок |

## Для ШІ-співробітників
З доступами «Інтеграції» і «Налаштування інтеграцій» (вкладка «Доступи» пульта ШІ) ШІ читає ці налаштування (`integrations_carrier_get`, `integrations_carrier_statuses`), натискає «Перевірити» акаунт (`integrations_carrier_check`) і пропонує зміни (`integrations_carrier_update`, `integrations_carrier_account_add`, `integrations_carrier_account_delete`) — кожна чекає «Підтвердити» адміністратора. Ключі й токени ШІ не бачить (лише «задано» й `••••1234`) і не вводить. Докладно — [Інтеграції — вхід для ШІ](integrations.md). Відправників ключем акаунта ШІ бачить через `integrations_carrier_np_senders`. ТТН створює людина. ШІ бачить доставки угоди в `deals_get` (служба, ТТН, статус) і може отримати доступ до акаунта відправника (рядок «ШІ» в «Доступах») на майбутнє. Статтю ШІ читає інструментом `help("int-nova-poshta")`.

## Додаткова інформація
- Пов'язані статті: [Доставки і ТТН](shipping.md), [Угоди](deals.md), [Укрпошта](int-ukrposhta.md), [Meest](int-meest.md), [Rozetka Delivery](int-rozetka-delivery.md).


---

# Укрпошта

Інтеграція з Укрпоштою створює відправлення з угоди через eCom API, відстежує їх за API статусів і переводить угоду на етап за статусом доставки. Налаштування повторюють KeepinCRM: кілька акаунтів-відправників, адреси відправника, списки відправлень (реєстри) з формою ф.103А, додаткові послуги, зв'язок статусів і полів угоди.

## Можливості
- Створення відправлень з угоди: відділення або адреса, стандарт чи експрес, післяплата на рахунок або готівкою.
- Трекінг статусів і «Пов'язані статуси» → етап угоди; окремо — з огляду на тип оплати.
- Кілька акаунтів-відправників зі своїми ключами, дефолтами й доступами.
- Адреси відправника і списки відправлень (ф.103А).
- Додаткові послуги: рекомендоване, SMS інформування, крихке, огляд під час вручення, повідомлення ф. 119, що робити, якщо не вручено.

## 1. Налаштування
Налаштовує адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Перевізники» → картка «Укрпошта». Картка відкривається на вкладці «Налаштування»; поруч — «Підключення».

1. **Ключі.** Укрпошта видає окремо доступ до eCom API (створення відправлень) і до API статусів (трекінг). Їх вводять в акаунті (розділ 2: «Bearer», «Bearer StatusTracking», «Токен» контрагента) або у вкладці «Підключення»: «Токен статусів», «eCom токен», «eCom bearer» — діють, коли акаунтів нема. Ключі зберігаються зашифрованими й назад не показуються.
2. **Перевірка.** «Перевірити» в «Підключенні» запитує статус свідомо неіснуючого відправлення: «токен статусів прийнято» означає, що ключ працює. У картці акаунта «Перевірити» читає дані клієнта Укрпошти.
3. **Налаштування.** Блоки: «Інтеграція» («Увімкнути інтеграцію»), «Додаткова інформація» (що писати в полі відправлення: без автогенерації, назва товару, артикул і кількість, назва й кількість, шаблон), «Номер замовлення» (не заповнювати, ID угоди, назва угоди), «Акаунти», «Адреси відправника», «Списки відправлень», «Доступи», «Пов'язані статуси», «Пов'язані типи оплат та статуси», «Пов'язані поля», «Вага й габарити з товарів» (галочка: вага й розмір посилки — з товарів угоди й кількості, а не з акаунта; [докладно](shipping.md#3а-вага-й-габарити-з-товарів-угоди)). Унизу — «Скасувати зміни» / «Зберегти».

## 2. Акаунти, адреси відправника, списки відправлень
**Акаунт** — «Акаунти» → «+ Додати акаунт» → назва → «Додати». Розгорнутий акаунт: «Увімкнено», «Перевірити», «Прибрати акаунт» і групи:
- «Акаунт»: «Назва» — як підписати відправника у списку акаунтів і формі ТТН;
- «Відправник»: «Ім'я відправника», «Тип відправника» (Фізична особа підприємець, Фізична особа, Юридична особа), «Телефон», «Адреса відправника» (з блоку «Адреси відправника»; це клієнт-відправник у кабінеті Укрпошти — з нього беруться ПІБ, IBAN та ІПН, як у KeepinCRM), «Номер банківського рахунку (IBAN)», «ІПН»;
- «Доступ до API»: «Bearer» (eCom API), «Bearer StatusTracking» (API статусів), «Токен» (токен контрагента);
- «Відправлення за замовчуванням»: «Метод доставки» (Склад-Склад, Склад-Двері, Двері-Склад, Двері-Двері), «Тип відправлення» (Укрпошта стандарт / Укрпошта експрес), «Список відправлення», «Платник доставки», «Платник комісії за післяплату», «Післяплата» (На банківський рахунок (IBAN) / Готівкою), «Короткий опис» (опис у відправленні; порожньо — з назв товарів);
- «Додаткові послуги»: «Рекомендоване», «SMS інформування», «Крихке», «Огляд під час вручення», «Повідомлення про вручення ф. 119», «Повернення відправлень» (Повернути; Повернути через 7 календарних днів; Розглянути як відправлення, від якого відмовився відправник);
- «Розмір і вага відправлення».

**Доступи** — блок «Доступи · <акаунт>»: «Показати» тим, хто створює відправлення цим відправником; без галочки акаунта не видно у формі. Адміністратор бачить усі.

**Адреси відправника** — «+ Додати» → «Адреса відправника» (напр. «Україна, 03127, Київ, вул. …») → «Додати». Адреса акаунта вибирається з цього списку.

**Списки відправлень** — створити ТТН без списку неможливо; у списку до 500 ТТН, далі потрібен новий (як у KeepinCRM). «+ Додати» → «Назва списку відправлень» → «Додати». Таблиця: «Назва», «Тип», «ТТН», «Форма ф.103А» (друк, коли форму віддає API). Новий список додається в налаштування й зберігається кнопкою «Зберегти».

## 3. Статуси, типи оплат і поля угоди
- «Пов'язані статуси»: статус відправлення (назва події з API статусів Укрпошти: «Створено», «Відправлення прийняте», «Надходження на сортувальний центр», «Відправлення з сортувального центру», «Відправлення у точці видачі/доставки», «Відправлення вручено», «Відправлення вручено відправнику», «Повернення відправлення» тощо) → етап угоди; без рядка етап не змінюється. Укрпошта в трекінгу пише й інакше («Прийнято», «Прибуло до Логістичного центру», «Прибуло до Сортувального депо», «Прибуло до Відділення», «Вручено Одержувачу», «Повернення. Вручено Відправнику») — назви вище й назви з KeepinCRM («Отримано», «Надійшло у відділення») спрацьовують і на них; під рядком видно, на що саме, а рядок без відповідника позначено.
- **Кожна воронка — свої рядки** (17.10): рядок діє лише на угоди воронки свого етапу (воронку видно біля етапу: «Відправлено [Продажі Каста]»). Посилки цієї служби їздять у кількох воронках — додайте для кожної свої рядки з тими самими статусами.
- **«Скасовані угоди не чіпати»** і **«Не повертати угоду на етап до збірки»** (перемикачі над таблицею, типово ввімкнені, 17.10): скасовану угоду статус посилки не рухає й не закриває «Виграно»; коли посилка вже поїхала, рядки на етапи з роллю «Створено», «Прийнято», «Передали на збірку», «Зібрано», «Допомога» пропускаються — діє наступний рядок.
- **«Міняти етап, коли посилка»** (16.10): етап за статусом міняється лише на позначених станах посилки — типово «відправлена / в дорозі», «у відділенні», «отримана», «повернення». Поки посилка «створена, ще не відправлена», етап стоїть, навіть якщо для такого статусу є рядок; щоб і він діяв, позначте «створена, ще не відправлена».
- «Пов'язані типи оплат та статуси»: те саме з огляду на тип оплати; ці рядки головніші.
- «Пов'язані поля»: «Місто», «Поштовий індекс», «Одержувач», «Телефон» — з яких полів угоди брати дані у форму; «Тип отримання грошей» — поле-список угоди і відповідність значень типам оплати.

Етап змінюється, коли оновлюється статус ТТН: фоном (автооновлення нижче, крок ШІ Ростіка) і кнопкою «Оновити статус» у «⋮» рядка ТТН в угоді. ТТН замовлень маркетплейсу, записані службою «ukr_poshta», фон теж опитує (до 17.10 пропускав).

- **Автооновлення й архів отриманих** (над «Пов'язаними статусами»): «Оновлювати статуси ТТН автоматично» кожні N хв (типово так, 30 хв) — статуси відкритих угод оновлюються самі, без кнопки «Оновити статус»; «Посилку отримано → угода «Виграно» в архів» (типово так) — коли перевізник каже «отримано», угода переходить на етап «Виграно» своєї воронки й іде в архів навіть без рядка «Пов'язаних статусів». Відмови й повернення не архівуються.

## 4. Створити відправлення з угоди
Картка угоди → «Доставка» → «+» → «Створити ТТН» → вкладка «Укрпошта» → акаунт → одержувач, індекс відділення або адреса з індексом, вага → «Створити ТТН». Покроково — [Доставки і ТТН](shipping.md).

Щойно в полі «Поштовий індекс» 5 цифр (з замовлення чи вписані вручну), «Місто», «Район» і «Область» заповнюються самі з довідника Укрпошти, а відділення позначається «індекс». Якщо місто вже вибране і це те саме місто — воно не змінюється, лише дописується порожнє. Довідник недоступний — поля можна заповнити вручну, ТТН створюється за індексом.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): UKRPOSHTA_STATUS_TOKEN, …» | Ключі не введено | Введіть ключі в акаунті або в «Підключенні» |
| «HTTP 401» / «HTTP 403» після «Перевірити» | Токен статусів не прийнято | Перевірте токен |
| «Укрпошта: індекс відділення — 5 цифр (наприклад 79000)» | Неправильний індекс | Виправте індекс |
| «Укрпошта: для адресної доставки вкажіть індекс адреси (5 цифр)» | Адреса без індексу | Додайте індекс |
| «Укрпошта: одне відправлення — одне місце» | У формі кілька місць | Розбийте на кілька відправлень |
| «Укрпошта: нема eCom-кредів (UP_BEARER / UP_TOKEN) — список створити неможливо» | В акаунті нема eCom-ключів | Введіть «Bearer» і «Токен» |
| «Укрпошта не віддала форму ф.103А для цього списку» | API не повернув форму | Спробуйте пізніше або роздрукуйте в кабінеті |
| «Нема доступу до акаунта «…» Укрпошта — …» | Не поставлено «Показати» | Адміністратор дає доступ |

## Для ШІ-співробітників
З доступами «Інтеграції» і «Налаштування інтеграцій» (вкладка «Доступи» пульта ШІ) ШІ читає ці налаштування (`integrations_carrier_get`, `integrations_carrier_statuses`), натискає «Перевірити» акаунт (`integrations_carrier_check`) і пропонує зміни (`integrations_carrier_update`, `integrations_carrier_account_add`, `integrations_carrier_account_delete`) — кожна чекає «Підтвердити» адміністратора. Ключі й токени ШІ не бачить (лише «задано» й `••••1234`) і не вводить. Докладно — [Інтеграції — вхід для ШІ](integrations.md). Список відправлень ф.103А ШІ пропонує створити через `integrations_carrier_list_create` (теж із підтвердженням). Відправлення створює людина. ШІ бачить доставки угоди в `deals_get`. Статтю ШІ читає інструментом `help("int-ukrposhta")`.

## Додаткова інформація
- Пов'язані статті: [Доставки і ТТН](shipping.md), [Нова Пошта](int-nova-poshta.md), [Meest](int-meest.md).


---

# Meest

Інтеграція з Meest створює відправлення з угоди, друкує стікери, відстежує посилки й переводить угоду на етап за статусом доставки. Налаштування — як у KeepinCRM: кілька акаунтів-відправників зі своїм договором і токеном, дефолти форми ТТН, доступи, зв'язок статусів і полів угоди.

## Можливості
- Відправлення у відділення або поштомат з обох сторін, післяплата на розрахунковий рахунок.
- Кілька акаунтів-відправників, у кожного свій договір, токен, відправник і доступи.
- «Додаткова інформація» і «Номер замовлення» в ТТН за налаштуваннями.
- «Пов'язані статуси» і «Пов'язані типи оплат та статуси» → етап угоди.
- «Пов'язані поля»: місто, відділення, одержувач, телефон з полів угоди.

## 1. Налаштування
Налаштовує адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Перевізники» → картка «Meest». Відкривається вкладка «Налаштування»; поруч — «Підключення».

1. **Ключі.** «Contract ID» береться з договору з Meest, «Токен» — від Meest. Вводяться в акаунті (розділ 2) або в «Підключенні» («API токен», «ID договору») — останні діють, коли акаунтів нема. Зберігаються зашифрованими.
2. **Перевірка.** «Перевірити» в «Підключенні»: «токен прийнято» або «авторизація за логіном пройшла». «Перевірити» в картці акаунта перевіряє все, без чого ТТН не створиться: токен, «Contract ID» (заданий і має вигляд коду договору Meest) і відділення відправника в довіднику Meest. Успіх — «токен і Contract ID прийнято; відділення відправника: №1354: вул. …»; якщо прихований код відділення веде не на той №, що в полі «Відділення відправки», перевірка це скаже.
3. **Налаштування.** «Інтеграція» («Увімкнути інтеграцію»), «Додаткова інформація», «Номер замовлення» (не заповнювати, ID угоди, назва угоди), «Акаунти», «Доступи», «Пов'язані статуси», «Пов'язані типи оплат та статуси», «Пов'язані поля», «Вага й габарити з товарів» (галочка: вага й розмір посилки — з товарів угоди й кількості, а не з акаунта; [докладно](shipping.md#3а-вага-й-габарити-з-товарів-угоди)). Унизу — «Скасувати зміни» / «Зберегти».

## 2. Акаунти і доступи
«Акаунти» → «+ Додати акаунт» → назва → «Додати». Розгорнутий акаунт: «Увімкнено», «Перевірити», «Прибрати акаунт» і групи:
- «Відправник»: «Ім'я відправника», «Contract ID», «Токен», «Метод доставки відправника» і «Метод доставки отримувача» (Відділення / Поштомат; Meest приймає поштомат як відділення — його обирають у списку відділень), «ЄДРПОУ», «Телефон»;
- «Відправлення за замовчуванням»: «Платник доставки», «Місто» (зі списку Meest — почніть вводити назву), «Відділення відправки» (зі списку Meest міста; можна ввести №), «Форма оплати» (Готівка / Безготівка), «Післяплата» (На розрахунковий рахунок; зарахування на картку не дозволено);
- «Розмір і вага відправлення» — діють і для ТТН, які створює автоматика (Олесь, ШІ), коли в заявці розмірів нема; вага з карток товарів головніша.

Список міст і відділень з'являється, коли в акаунті збережено «Токен». Відділення, вибране зі списку, запам'ятовує свій код у Meest (під полем — «вибрано зі списку Meest»). Ручне введення або зміна міста цей код скидає — тоді відділення шукається за містом і №; опис із KeepinCRM («Партнерське №1354, посилки до 30кг… 108/1») теж працює — береться №1354.

«Доступи · <акаунт>»: «Показати» тим, хто створює ТТН цим відправником, і ШІ-співробітникам, які оформлюють замовлення (Олесь). Новий акаунт одразу відкритий тому, хто його додав. Без галочки акаунта не видно у формі; адміністратор бачить усі. Акаунт, відкритий нікому, картка позначає жовтим «нікому не відкрито».

**Що картка каже сама.** Над полями акаунта — «Щоб створювати ТТН, бракує: «Contract ID», місто й відділення відправника…» (поки чогось нема). Після «Зберегти» зі зміненим містом чи відділенням відправника «Перевірити» запускається саме, і помилку («відділення №… не знайдено») видно одразу в картці, а не при створенні ТТН.

**Без налаштувань сервера.** Усе для роботи — у картці: ключі, відправник, доступи, статуси. У новій організації ключі й відправник із налаштувань сервера не підставляються: поки акаунта нема, форма ТТН каже «додайте акаунт у «Інтеграції → Meest»». Стікер, трекінг і довідники міст/відділень ідуть ключем акаунта.

## 3. Статуси, типи оплат і поля угоди
- «Пов'язані статуси»: статус відправлення → етап угоди (без рядка етап не змінюється). **Статус має збігатися з текстом Meest дослівно** (великі й малі літери, апостроф і зайві пробіли не важать) — беріть зі списку. Meest надсилає: «Відправлення створено, але не передано на доставку», «Відправлення прийнято до перевезення», «Відправлення в дорозі», «Прибуття у транзитний сортувальний центр», «Відправлення з транзитного сортувального центру», «Відправлення прибуло в сортувальний центр», «Відправлення видане кур’єру і прямує у підрозділ отримання», «Надходження на підрозділ доручення», «Доручено», «Відправлення отримане», «Відправлення доставлене», «Прибуло на підрозділ повернення», «Відправлення повернуто відправнику», «Відправлення готове до видачі відправнику». Назви з KeepinCRM («Отримано», «Надійшло у відділення», «Оформлено для відправки», «Видано кур'єру»…) Meest не надсилає, але картка знає відповідники: «Отримано» спрацьовує на «Відправлення отримане», «Доручено» і «Відправлення доставлене», «Надійшло у відділення» — на «Надходження на підрозділ доручення»; під рядком написано, на що саме. Рядок, якому відповідника нема, позначено «такого тексту служба не надсилала». У випадайці — лише тексти, які Meest справді надсилала. Рядок із назвою KeepinCRM і рядок зі справжнім текстом можна мати обидва — збереження це не ламає.
- **«Міняти етап, коли посилка»** (16.10): етап за статусом міняється лише на позначених станах посилки — типово «відправлена / в дорозі», «у відділенні», «отримана», «повернення». Поки посилка «створена, ще не відправлена», етап стоїть, навіть якщо для такого статусу є рядок; щоб і він діяв, позначте «створена, ще не відправлена».
- «Пов'язані типи оплат та статуси»: з огляду на тип оплати; головніші.
- «Пов'язані поля»: «Місто», «Відділення», «Одержувач», «Телефон», «Тип отримання грошей». Поле з повною адресою (наприклад, «Адреса доставки (prom)») розбирається: у форму йдуть місто й № відділення, а не весь рядок.

**Звідки статус.** Meest через API віддає історію лише відправлень вашого договору (токен акаунта). ТТН, які створив маркетплейс під своїм договором («Meest ПОШТА» на Prom, Rozetka, Епіцентр, OLX), Meest так не показує (аудит 15.10: з 51 ТТН Meest в угодах історію дали 2 — обидві вашого договору). Для угод Prom статус береться із замовлення Prom («Доставлено (Prom)», «Повернення (Prom)»…; лише коли номер декларації в замовленні — саме ця ТТН), і отримана посилка так само веде угоду у «Виграно» й архів. ТТН Rozetka, Епіцентру й OLX під їхнім договором поки бачить лише дзеркало KeepinCRM.

Етап змінюється, коли оновлюється статус ТТН (кнопка «Оновити статус» у «⋮» рядка ТТН; уточнити: чи є автоматичне періодичне оновлення).

- **Автооновлення й архів отриманих** (над «Пов'язаними статусами»): «Оновлювати статуси ТТН автоматично» кожні N хв (типово так, 30 хв) — статуси відкритих угод оновлюються самі, без кнопки «Оновити статус»; «Посилку отримано → угода «Виграно» в архів» (типово так) — коли перевізник каже «отримано», угода переходить на етап «Виграно» своєї воронки й іде в архів навіть без рядка «Пов'язаних статусів». Відмови й повернення не архівуються.

## 4. Створити ТТН з угоди
Картка угоди → «Доставка» → «+» → «Створити ТТН» → вкладка «Meest» → акаунт → місто й відділення (або поштомат) відправника й одержувача → «Створити ТТН». Покроково — [Доставки і ТТН](shipping.md).

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): MEEST_API_TOKEN, MEEST_CONTRACT_ID» | Ключі не введено | Введіть ключі в акаунті або в «Підключенні» |
| «токен відхилено (HTTP 401)» | Meest не прийняв токен | Перевірте токен |
| «токен прийнято, але не задано Contract ID» / «Contract ID не схожий на код договору Meest» | Немає або хибний код договору | Введіть «Contract ID» з договору Meest (вигляд xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) |
| «… відділення №… у місті «…» не знайдено в довіднику Meest» / «прихований branch_id веде на відділення №…» | Відділення відправника введено текстом або змінено без вибору зі списку | Оберіть місто й відділення відправника зі списку Meest, «Зберегти», «Перевірити» |
| «Meest: не визначив відділення відправника» під час створення ТТН | Те саме | Те саме |
| Статус ТТН змінюється, а етап угоди — ні | Текст у «Пов'язаних статусах» не збігається з текстом Meest | Оберіть статус зі списку (розділ 3) |
| «Вкажіть № відділення/поштомата … або адресу доставки» | У формі нема відділення | Заповніть відділення або «Пов'язані поля» |
| «Нема доступу до акаунта «…» Meest — …» | Не поставлено «Показати» | Адміністратор дає доступ |
| «Акаунт «…» вимкнено в налаштуваннях Meest» | Акаунт вимкнено | Увімкніть акаунт |

## Для ШІ-співробітників
З доступами «Інтеграції» і «Налаштування інтеграцій» (вкладка «Доступи» пульта ШІ) ШІ читає ці налаштування (`integrations_carrier_get`, `integrations_carrier_statuses`), натискає «Перевірити» акаунт (`integrations_carrier_check`) і пропонує зміни (`integrations_carrier_update`, `integrations_carrier_account_add`, `integrations_carrier_account_delete`) — кожна чекає «Підтвердити» адміністратора. Ключі й токени ШІ не бачить (лише «задано» й `••••1234`) і не вводить. Докладно — [Інтеграції — вхід для ШІ](integrations.md). ТТН створює людина. ШІ бачить доставки угоди в `deals_get`. Статтю ШІ читає інструментом `help("int-meest")`.

## Додаткова інформація
- Пов'язані статті: [Доставки і ТТН](shipping.md), [Нова Пошта](int-nova-poshta.md), [Укрпошта](int-ukrposhta.md).


---

# Rozetka Delivery

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

## Можливості
- Накладні Rozetka Delivery з угоди, зокрема в «Магазини Rozetka».
- Кілька акаунтів-відправників зі своїм входом у кабінет, відправником і доступами.
- «Додаткова інформація» (опис у накладній) і «Номер замовлення» за налаштуваннями.
- «Пов'язані статуси» і «Пов'язані типи оплат та статуси» → етап угоди, «Пов'язані поля».

## 1. Налаштування
Налаштовує адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Перевізники» → картка «Rozetka Delivery». Відкривається вкладка «Налаштування»; поруч — «Підключення».

1. **Вхід у кабінет.** Логін і пароль кабінету Rozetka вводяться в акаунті (група «Доступ до кабінету») або в «Підключенні» («Логін», «Пароль») — останні діють, коли акаунтів нема. Зберігаються зашифрованими.
2. **Перевірка.** У «Підключенні» безпечної перевірки нема — дивіться стан ключів і журнал. У картці акаунта «Перевірити» входить у кабінет логіном акаунта.
3. **Налаштування.** «Інтеграція» («Увімкнути інтеграцію»), «Додаткова інформація», «Номер замовлення», «Акаунти», «Доступи», «Пов'язані статуси», «Пов'язані типи оплат та статуси», «Пов'язані поля», «Вага й габарити з товарів» (галочка: вага й розмір посилки — з товарів угоди й кількості, а не з акаунта; [докладно](shipping.md#3а-вага-й-габарити-з-товарів-угоди)). Унизу — «Скасувати зміни» / «Зберегти».
4. **Значки в шапці картки.** «Приєднано» — вхід у кабінет задано. «увімкнено» / «вимкнено» — головний перемикач картки у вкладці «Підключення». Для перевізника він нічого не вмикає й не вимикає: накладні й автооновлення статусів залежать від «Увімкнути інтеграцію» у «Налаштуваннях» і від «Увімкнено» в самому акаунті. Щоб шапка не плутала, увімкніть і перемикач у «Підключенні».
5. **Вкладки над «Підключення / Налаштування».** «Основний» — відправник із налаштувань сервера, діє лише тоді, коли акаунтів нема. Далі — акаунти (наприклад, «ФОП …») з крапкою: зелена — увімкнено, жовта — бракує входу чи відправника, сіра — вимкнено.

Відправник і параметри відправлення для «Магазинів Rozetka» задаються також у картці Rozetka → «Налаштування продажів» → «Магазини Rozetka» ([стаття](int-rozetka.md#5-магазини-rozetka-ттн-у-точки-видачі)).

## 2. Акаунти і доступи
«Акаунти» → «+ Додати акаунт» → назва → «Додати». Розгорнутий акаунт: «Увімкнено», «Перевірити», «Прибрати акаунт» і групи:
- «Доступ до кабінету»: «Логін», «Пароль»;
- «Відправник»: «Ім'я відправника», «Перевізник» (назва перевізника в кабінеті Rozetka), «Телефон», «Місто», «Відділення» (адреса або № точки видачі);
  - «Перевізник» — точно як у кабінеті Rozetka Delivery: «Самовивіз з магазинів Розетки» (точки видачі Rozetka), «Нова Пошта», «Meest Пошта» або «Укрпошта». Назва, якої в кабінеті нема, дає помилку «Rozetka: перевізника не знайдено» — накладна не піде іншим перевізником;
  - «Відділення» магазину Rozetka — адреса, як у кабінеті: номерів у магазинів нема, тож шукається збіг будинку й вулиці («Голосіївський просп., 108/1» = «м. Київ, Голосіївський пр-т, 108/1»). Кнопка «Перевірити» перевіряє лише вхід; чи знайшлось відділення, видно в прев'ю «Створити ТТН»;
- «Відправлення за замовчуванням»: «Платник доставки», «Опис» (короткий опис у накладній);
- «Розмір і вага відправлення».

«Доступи · <акаунт>»: «Показати» тим, хто створює накладні цим відправником; адміністратор бачить усі.

- **Автооновлення й архів отриманих** (над «Пов'язаними статусами»): «Оновлювати статуси ТТН автоматично» кожні N хв (типово так, 30 хв) — статуси відкритих угод оновлюються самі, без кнопки «Оновити статус»; «Посилку отримано → угода «Виграно» в архів» (типово так) — коли перевізник каже «отримано», угода переходить на етап «Виграно» своєї воронки й іде в архів навіть без рядка «Пов'язаних статусів». Відмови й повернення не архівуються. Скасовані ТТН не опитуються.
- **«Пов'язані статуси»** — назва статусу має збігатися дослівно (без регістру). Rozetka Delivery пише, наприклад, «В дорозі», «У відділенні», «Видано», «Відмова від одержання», «Створено рахунок», «Прийнято від продавця», «Помістили в контейнер», «Готово до видачі», «Клієнт відмовився на точці видачі» — список підказує їх у формі. Назви з KeepinCRM («Створено», «Прийнято», «У дорозі», «Очікує в пункті видачі», «Відмова») спрацьовують на ці тексти; під рядком видно, на які, а рядок без відповідника позначено. Типовий набір: «В дорозі» → «Відправлено», «У відділенні» → «У відділенні», «Видано» → «Отримано», «Відмова від одержання» → «Повернення». ТТН замовлень Rozetka, записані службою «rozetka_delivery», фон теж опитує (до 17.10 пропускав).
- **Кожна воронка — свої рядки** (17.10): рядок діє лише на угоди воронки свого етапу (воронку видно біля етапу: «Відправлено [Продажі Каста]»). Посилки цієї служби їздять у кількох воронках — додайте для кожної свої рядки з тими самими статусами.
- **«Скасовані угоди не чіпати»** і **«Не повертати угоду на етап до збірки»** (перемикачі над таблицею, типово ввімкнені, 17.10): скасовану угоду статус посилки не рухає й не закриває «Виграно»; коли посилка вже поїхала, рядки на етапи з роллю «Створено», «Прийнято», «Передали на збірку», «Зібрано», «Допомога» пропускаються — діє наступний рядок.
- **«Міняти етап, коли посилка»** (16.10): етап за статусом міняється лише на позначених станах посилки — типово «відправлена / в дорозі», «у відділенні», «отримана», «повернення». Поки посилка «створена, ще не відправлена», етап стоїть, навіть якщо для такого статусу є рядок; щоб і він діяв, позначте «створена, ще не відправлена».

## 3. Створити накладну з угоди
Картка угоди з Rozetka → «Доставка» → «+» → «Створити ТТН» → вкладка Rozetka → акаунт → точка видачі → «Створити ТТН». Вага товарів угоди, якщо вона є, головніша за дефолтну. Покроково — [Доставки і ТТН](shipping.md).

Для «Магазинів Rozetka» на Prom накладна створюється лише через кабінет Prom; якщо на сервері це вимкнено — створіть її в кабінеті Prom вручну.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Помилка валідації даних: одержувач → телефон — …» (поле і причина) при «Створити ТТН» | Rozetka не прийняла значення поля ЕН | Виправте назване поле у шторці |
| «Помилка валідації даних» без назви поля | Rozetka відмовила, не назвавши поле (так буває через опис чи номер замовлення з налаштувань акаунта) | Helomi сам повторює запит без номера замовлення і з коротким описом «Угода <id>» — ЕН створюється; якщо й це не допомогло, у дужках — відповідь Rozetka як є; напишіть її в підтримку |
| У «Підключенні» замість «Перевірити» — «Для цього каналу безпечної перевірки нема — …» | Перевірка картки не передбачена | Перевірте акаунт у вкладці «Налаштування» |
| ««Магазини Rozetka» на Prom: ЕН створюється ЛИШЕ через кабінет Prom, …» | Магазин працює через Prom, а створення через кабінет Prom вимкнено | Створіть ЕН у кабінеті Prom вручну |
| ««Магазини Rozetka»: в угоді нема prom_order_id — …» | Угода не з Prom | Створіть ЕН у кабінеті Prom вручну |
| «Нема доступу до створення ТТН у магазини Rozetka — …» | Немає галочки в «Доступ до доставки» картки Rozetka | Адміністратор дає доступ |
| «Нема доступу до акаунта «…» Rozetka Delivery — …» | Не поставлено «Показати» в «Доступах» | Адміністратор дає доступ |
| «Rozetka: перевізника не знайдено» | Назва в полі «Перевізник» акаунта не збігається з кабінетом | Впишіть одну з назв: «Самовивіз з магазинів Розетки», «Нова Пошта», «Meest Пошта», «Укрпошта» |
| «Rozetka: відділення відправника не знайдено» | Адреса у «Відділення» не збіглась із точкою Rozetka в місті | Візьміть адресу точки з кабінету Rozetka Delivery: будинок і вулиця мають збігатися |
| «Rozetka: магазин/відділення не знайдено: …» | Адреса одержувача з замовлення не збіглась із жодною точкою міста | Оберіть точку зі списку у формі «Створити ТТН» |
| У шапці «вимкнено», хоча накладні створюються | Вимкнено головний перемикач у «Підключенні» — для перевізника він ні на що не впливає | Увімкніть перемикач у «Підключенні» |
| Статус ТТН давно не змінюється | Вимкнено «Оновлювати статуси ТТН автоматично», угода в архіві або ТТН скасована | Перевірте перемикач над «Пов'язаними статусами»; разово — «Оновити статус» у рядку ТТН |

## Для ШІ-співробітників
З доступами «Інтеграції» і «Налаштування інтеграцій» (вкладка «Доступи» пульта ШІ) ШІ читає ці налаштування (`integrations_carrier_get`, `integrations_carrier_statuses`), натискає «Перевірити» акаунт (`integrations_carrier_check`) і пропонує зміни (`integrations_carrier_update`, `integrations_carrier_account_add`, `integrations_carrier_account_delete`) — кожна чекає «Підтвердити» адміністратора. Ключі й токени ШІ не бачить (лише «задано» й `••••1234`) і не вводить. Докладно — [Інтеграції — вхід для ШІ](integrations.md). Накладні створює людина. ШІ бачить доставки угоди в `deals_get`. Статтю ШІ читає інструментом `help("int-rozetka-delivery")`.

## Додаткова інформація
- Пов'язані статті: [Rozetka](int-rozetka.md), [Доставки і ТТН](shipping.md), [Prom](int-prom.md).


---

# Kasta hub

Kasta hub — кабінет постачальника hub.kasta.ua, через який створюються ТТН для замовлень Kasta. Це єдиний дозволений шлях: у кабінеті платник доставки — Kasta, а ТТН, створена напряму в службі доставки повз кабінет, стала б платною для вас. Картка в «Перевізниках» тримає логін і пароль кабінету.

## Можливості
- ТТН для угоди Kasta через кабінет hub.kasta.ua (за номером замовлення Kasta); якщо ТТН у кабінеті вже є — береться наявна.
- Створення ТТН у кабінеті одночасно підтверджує замовлення.
- Захист: для угоди Kasta CRM не дасть створити ТТН іншою службою.

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Перевізники» → картка «Kasta hub» → «Підключення».

1. «Логін» і «Пароль» кабінету hub.kasta.ua → «Ввести» → «Зберегти ключ». Зберігаються зашифрованими.
2. Перевірки кнопкою нема: вхід у кабінет іде через браузер на сервері, тож дивіться стан ключів і журнал.
3. Кабінет працює окремим скриптом на сервері; його має бути ввімкнено.

## 2. Створити ТТН для угоди Kasta
Картка угоди з Kasta → «Доставка» → «+» → «Створити ТТН» → служба «Kasta (hub.kasta.ua)» → «Створити ТТН». CRM відкриє кабінет hub.kasta.ua, створить (або візьме наявну) ТТН за номером замовлення Kasta і запише її в угоду. Далі ТТН можна передати на Kasta з блоку «Kasta» в угоді або автоматично етапом ([Kasta](int-kasta.md#4-статус-і-ттн-назад-на-kasta)).

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Kasta: ТТН створюється ЛИШЕ через кабінет hub.kasta.ua, а кабінет вимкнено або нема KASTA_HUB_LOGIN/KASTA_HUB_PASSWORD …» | Не введено логін/пароль або кабінет вимкнено на сервері | Введіть логін і пароль; інакше створіть ТТН у hub.kasta.ua вручну |
| «Kasta-угода: ТТН створюється ЛИШЕ через кабінет hub.kasta.ua (оберіть службу «Kasta»); пряма ТТН буде платною для нас.» | Для угоди Kasta вибрано іншу службу | Оберіть службу «Kasta (hub.kasta.ua)» |
| «Kasta (hub.kasta.ua): …» | Кабінет відповів помилкою | Подивіться причину, за потреби створіть ТТН у кабінеті вручну |

## Для ШІ-співробітників
5`). ШІ не пропонує створювати ТТН Kasta напряму в Новій Пошті — лише через кабінет. Статтю ШІ читає інструментом `help("int-kasta-hub")`.

## Додаткова інформація
- Пов'язані статті: [Kasta](int-kasta.md), [Доставки і ТТН](shipping.md).


---

# Checkbox (фіскальні чеки)

Інтеграція з Checkbox фіскалізує продажі з угод: менеджер у картці угоди натискає «+ Створити чек», і програмний РРО Checkbox видає фіскальний чек з товарами угоди, способом оплати та email покупця. Підтримується кілька організацій (профілів) і касирів, доступи на створення чеків, повернення, перегляд і друк чеків; усі чеки зібрані у «Фінанси → Фіскальні чеки».

## Можливості
- До 10 профілів (організацій ФОП/ТОВ), у кожному до 20 касирів: вхід ПІН-кодом із ключем ліцензії каси або логіном і паролем.
- «Авторизація» касира: ПІБ підтягується з Checkbox.
- «Доступи»: хто може створювати чеки цього профілю; дивитися й друкувати можуть усі з доступом до угод.
- «Пов'язані поля»: назва товару для чека, поле угоди зі способом оплати і мапа «спосіб оплати → Готівка / Картка / Своя назва для Безготівки», коментар до чека.
- Чек з угоди: вибір позицій, тип оплати, email, коментар; якщо зміну не відкрито — CRM відкриває її сама (типово) і створює чек.
- Позиція, пробита в чеку, позначається галочкою і не редагується, доки не зроблено повернення.
- Переглянути, PDF, PNG, надіслати на email, оновити стан, повернення.
- Список усіх чеків з пошуком і підсумками.

## 1. Налаштування
Налаштовує адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Оплати» → картка «Checkbox».

**Вкладка «Підключення».** Перемикач «Інтеграція» має бути ввімкнений — інакше чеки не створюються. Ключів у цій вкладці нема: дані касирів вводяться у вкладці «Налаштування». «Перевірити» входить першим увімкненим касиром і читає стан зміни (нічого не пише в касу). «Стан роботи» показує профілі з кількістю касирів, «Касир авторизований» і «Чеків створено».

**Вкладка «Налаштування».**
1. «+ Додати профіль» → «Назва» (ні на що не впливає, лише для вас; напр. назва ФОП). Профілі показуються вкладками.
2. Блок «Касири» → «+ Додати касира» → шторка «Checkbox касир»:
   - «ПІН-код»: «ПІН-код *» (Checkbox → Касири → колонка «ПІН-код») і «Ключ ліцензії *» (Checkbox → Каси → колонка «Ключ ліцензії»);
   - або «Логін/Пароль»: «Логін *», «Пароль *» і «Ключ ліцензії (щоб відкривати зміну з CRM)».

«Зберегти», потім «Авторизація» — ПІБ касира підтягнеться з Checkbox («Стан», «ПІБ»). «змінити…» — нові дані входу; «Видалити касира». Значення зберігаються зашифрованими й більше не показуються.
3. Блок «Доступи»: таблиця «Користувач» / «Створити» — позначте, хто може створювати чеки цього профілю. Адміністратор може завжди.
4. Блок «Пов'язані поля»:
   - «Надсилання»: «Відправка Email», «Відправка ставки ПДВ», «Відправка УКТЗЕД коду» (розділи 3–4);
   - «Коментар до чеку»: «Без коментарів до чеку», «Відправляти коментар з користувацького поля» (вибрати поле угоди або «Коментар до угоди»), «Відправляти зазначений коментар» (текст);
   - «Назва товару»: «Назва товару (стандартне поле)» або інше текстове поле товару — назва має збігатися з назвою товару в Checkbox;
   - «Спосіб оплати»: поле-список угоди, з якого береться тип оплати (типово «Тип оплати checkbox»);
   - таблиця «Способи оплати» → «Тип оплати»: значення поля угоди → «Готівка», «Картка» або «Своя назва для Безготівки» з полем «Вкажіть назву способу оплати» (напр. «Rozetkapay», «NovaPay»). «Додати спосіб оплати»; без мапи чек не знатиме, готівка це чи картка.
5. «Зберегти» / «Скасувати зміни» в панелі внизу. «Видалити профіль» — чеки, створені раніше, лишаються у «Фінанси → Фіскальні чеки».

Кілька організацій — кілька профілів, кожен зі своїми касирами, доступами й способами оплати. Каса офлайн-магазину (розділ «Каса») бере касира окремо, з налаштувань сервера.

## 2. Генерація чеків (ручний та автоматичний режим)
**Вручну.**
1. Картка угоди → блок «Документи» → «Фіскальні чеки Checkbox» → «+ Створити чек».
2. Шторка «Створити фіскальний чек»: «Організація» (профіль), «Касир», «Позиції (N з M)» — галочками, лише ті, що ще не в чеку, «Тип оплати (з поля угоди; змінити можна тут)», «Email для чека (через кому; порожньо — не надсилати)», «Коментар до чеку (порожньо — за налаштуваннями профілю)». Унизу — «До фіскалізації: <сума>».
3. «Створити чек». Якщо зміну не відкрито, CRM відкриє її сама (у профілі ввімкнено «Відкривати зміну автоматично, коли створюється чек»). Якщо це вимкнено — з'явиться «Зміну в Checkbox не відкрито. Відкрити зміну і створити чек?» — підтвердіть.
4. Чек з'являється в списку блоку: фіскальний №, «продаж» і тип оплати, стан, сума, дата, касир. Позиції чека позначаються галочкою і більше не редагуються; в списку угод угода отримує позначку «чек».

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

**Автоматично** (за етапом угоди чи статусом ТТН) — поки не зроблено, чек створює людина.

## 3. Відправка чеку на email і по SMS
- «Пов'язані поля» → «Відправка Email»: Checkbox сам надсилає чек на перший email клієнта з картки.
- Вручну: «⋮» біля чека → «Надіслати на email».
- По SMS — поки не зроблено: змінної з адресою чека в шаблонах SMS ще нема.

## 4. Налаштування ПДВ і УКТЗЕД
- «Відправка ставки ПДВ» → поле з кодом або літерою ставки з Checkbox (кабінет Checkbox → Податкові ставки). У кожен товар чека піде ця ставка; ставки мають збігатися.
- «Відправка УКТЗЕД коду» → поле товару складу з кодом УКТ ЗЕД; код передається в чек.

## 5. Повернення, перегляд, друк
«⋮» біля чека в угоді: «Переглянути» (чек у вікні), «Завантажити PDF», «Завантажити PNG», «Надіслати на email», «Оновити стан» (доки чек фіскалізується), «Повернення» — лише для проведеного чека продажу, один раз. Якщо зміну не відкрито — CRM відкриє її сама (або спитає, якщо автоматичне відкриття вимкнено) і зробить повернення. Після повернення позиції знову можна змінювати.

Зміна відкривається з CRM автоматично при першому чеку; закривається в кабінеті Checkbox.

## 6. Розділ з чеками
«Фінанси» → вкладка «Фіскальні чеки»: пошук (фіскальний №, угода, касир), період, «Усі організації», «Продаж і повернення», «Усі стани» (Проведено, Фіскалізується, Помилка); підсумки «Чеків», «Продажі», «Повернення», «Разом»; таблиця з датою, фіскальним №, типом, сумою, оплатою, угодою й організацією.

## Що змінилося 14.10 (C14B–C14D)

- **Підключення каси у три кроки на одній сторінці:** 1) ключ ліцензії справжньої каси; 2) ПІН-код касира або логін і пароль касира з кабінету Checkbox (email кабінету не підходить); 3) «Підключити касу» — ПІБ підтягується, касир створюється, інтеграція вмикається сама.
- **Каса на кожну юрособу:** у профілі поле «Юрособа»; угода пробивається касою своєї юрособи, у блоці «Документи» видно «Чек пробиває: …».
- **Чек у «Документах» угоди:** «+ → Фіскальний чек: касир» створює одразу; рядок чека зі знаком «C»; «⋮» — PDF, URL, друк TXT/PNG, повернути, email. По угоді не більше одного чинного чека.
- **Назва в чеку** — поле «Назва Checkbox (латиницею)» позиції прайс-листа; у списку угод знак «C» і фільтр «Чек».
- **Автоматичний чек** — дія тригера «Фіскальний чек Checkbox» (пресет «при “Отримано”»), вмикається з налаштувань Checkbox.

Докладно — стаття «Фіскальні чеки Checkbox» (`checkbox`).

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Інтеграцію Checkbox вимкнено — увімкніть її в «Інтеграції → Checkbox»» | Перемикач вимкнено | «Підключення» → «Інтеграція» |
| «Профіль Checkbox не налаштовано — додайте його в «Інтеграції → Checkbox»» | Немає профілю | «+ Додати профіль» |
| «Нема увімкненого касира з ПІН-кодом / паролем» | Касир не доданий або без даних входу | Додайте касира й «Авторизація» |
| «У профілі нема увімкненого касира — додайте в «Інтеграції → Checkbox»» | У шторці чека немає касира | Додайте касира в профіль |
| «У вас нема доступу створювати чеки цього профілю (Налаштування Checkbox → Доступи)» | Вас не позначено в «Доступах» | Попросіть адміністратора |
| «Касир: не задано ключ ліцензії каси» | Для входу ПІН-кодом бракує ключа ліцензії | Введіть «Ключ ліцензії» |
| «Відкрити зміну можна лише касиру з ключем ліцензії каси» | Касир з логіном без ключа ліцензії | Додайте касиру ключ ліцензії |
| «HTTP 422: Помилка валідації: <поле> — <причина>» | Checkbox не прийняв поле чека (наприклад, email клієнта не схожий на адресу) | Текст називає поле; виправте дані в угоді чи клієнті й повторіть. Номер угоди в чеку йде рядком «Замовлення …» у підвалі (окремого поля в Checkbox нема) |
| «Не вдалося розшифрувати дані касира — введіть ПІН-код і ключ ліцензії ще раз» | Змінився ключ шифрування на сервері | Введіть дані касира заново |
| «Усі позиції угоди вже в чеку (або позицій нема)» | Нема що фіскалізувати | Додайте позицію або зробіть повернення |
| «Сума чека 0» | Позиції без ціни | Вкажіть ціни позицій |
| «По цьому чеку повернення вже зроблено» | Повторне повернення | Нічого не треба |
| «Позиція «…» уже у фіскальному чеку — спершу зробіть повернення чека» | Спроба змінити пробиту позицію | Зробіть повернення чека |

## Для ШІ-співробітників
5`). ШІ бачить в угоді (`deals_get`) поле «Тип оплати checkbox» (`tip_oplaty_checkbox`) і може заповнити його значенням з мапи способів оплати, щоб людина створила правильний чек. Позиції з чеком змінювати не можна — помилка це підкаже. Статтю ШІ читає інструментом `help("int-checkbox")`.

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


---

# Monobank

Інтеграція з Monobank тягне виписку рахунку ФОП чи картки через особистий API банку в «Фінанси»: кожна операція проходить правила імпорту, надходження з номером угоди в призначенні саме стає оплатою по угоді, а решта чекає перевірки у «Вхідних». Рахунків може бути скільки завгодно — кожен підключається окремим акаунтом зі своїм токеном, гаманцем і налаштуваннями, а з увімкненими миттєвими операціями платіж з'являється у «Фінансах» за хвилину. Повторний імпорт дублів не створює.

## Можливості
- Скільки завгодно акаунтів Monobank: свій токен, свій рахунок банку, свій гаманець, свій журнал подій.
- Налаштування кожного акаунта мишкою, без розробника: рахунок, гаманець, хто бачить операції, вікно імпорту, холди, прив'язка до угод, миттєві операції.
- Імпорт кнопкою за період (до 31 доби за раз) і автоматично кроком ШІ Марії Йосипівни.
- Миттєві операції: банк повідомляє про кожен платіж, CRM одразу перечитує виписку.
- Надходження з «№50000123», «sg-50000123», номером рахунку чи ТТН у призначенні — оплата по несплаченій угоді без ручної роботи.
- Правила імпорту, звірка з уже внесеними операціями, «Вхідні» для решти — той самий шлях, що в ПриватБанку й NovaPay.
- Без дублів: повтор за id операції банку пропускається, хоч би звідки прийшов рядок (кнопка, Марія, вебхук).

## 1. Налаштування
Підключає адміністратор. Дорога: «Інтеграції» (головне меню) → «Оплати» → картка «Monobank».

**Токен.** Вкладка «Підключення» → рядок «Токен» → «Ввести» → вставте особистий токен → «Зберегти ключ» → «Перевірити» (успіх — «рахунків: N»). Токен береться на сайті api.monobank.ua (вхід через застосунок monobank). Він зберігається зашифрованим і більше ніде не показується — лише останні символи.

**Акаунти.** Основна картка — теж акаунт («Основний»; назву можна змінити в рядку «Назва акаунта»). Ще один рахунок — «+» у правому нижньому куті картки («Додати ще один Monobank») → «Назва» і токен → «Додати акаунт». Акаунти перемикаються під шапкою картки. Один акаунт — один токен і один рахунок банку: другий рахунок того самого клієнта (наприклад, ФОП і чорна картка) — це другий акаунт з тим самим токеном. Акаунт без токена нічого не імпортує: токен основної картки чи сервера він не позичає. Токен читається з картки в будь-якій організації Helomi, не лише в першій.

**Вкладка «Налаштування»** акаунта. Угорі — «Стан акаунта» (рахунок банку з балансом, гаманець, миттєві операції з адресою, останній імпорт) і кнопка «Оновити рахунки» (список рахунків з банку оновлюється сам раз на 10 хвилин). Нижче — форма; змінює її адміністратор, решта бачить без збереження. Зберегли — імпорт, Марія і вебхук беруть нове одразу.

| Поле | Що робить | Типово |
| --- | --- | --- |
| «Рахунок у банку (картка чи ФОП)» | з якого рахунку береться виписка; у підписі — вид, валюта, кінець IBAN і залишок | ФОП у гривні з найбільшим залишком, інакше гривневий із залишком, інакше перший |
| «Гаманець у «Фінансах»» | куди лягають операції | гаманець акаунта (створиться з назвою акаунта; для основної картки — «Монобанк») |
| «Хто бачить операції рахунку» | розділ 5 | усі з доступом до «Фінансів» |
| «Тягнути виписку автоматично (крок ШІ Марії)» | автоімпорт цього акаунта | так |
| «Скільки останніх днів виписки перечитувати щоразу» | вікно автоімпорту, 1–31 | 3 |
| «Не заносити операції, старші за дату» | нижня межа автоімпорту | без межі |
| «Заносити холди… в автоматичному імпорті» | незавершені операції карткою | ні |
| «Прив'язувати надходження до угоди за призначенням платежу» | розділ 4 | «номер угоди у призначенні» |
| «Миттєві операції» → «Вебхук банку» | розділ 3 | вимкнено |

Автоімпорт тягне лише **увімкнені** акаунти (перемикач «Інтеграція» на вкладці «Підключення»). Щоб після переходу на акаунти виписка не зупинилася мовчки, основна картка з токеном, яку ніхто ніколи не вимикав, один раз увімкнулася сама — у журналі подій картки є запис «увімкнено автоматично: виписку тепер тягнуть лише увімкнені акаунти Monobank». Вимкнете — більше сама не ввімкнеться.

## 2. Імпорт виписки
1. «Фінанси» → «Операції» → «Імпорт виписки» (кнопку бачать ті, хто може проводити платежі).
2. Блок «Monobank»: «Акаунт» (поле є, коли акаунтів більше одного), «Рахунок» і «Гаманець» — «з налаштувань акаунта» або
   інший («Показати рахунки»), «Від» і «До».
3. «Імпортувати з Monobank». Під кнопкою — підсумок: «нових N, за правилами N, прив'язано до угод N, звірено з внесеними N,
   у «Вхідні» N, пропущено N».

Кнопка заносить і холди (як раніше); поле «Заносити холди» діє на автоімпорт Марії й вебхук. Автоматично виписку тягне крок ШІ Марії Йосипівни по кожному увімкненому акаунту з «Тягнути виписку автоматично»; загальний вимикач — пульт Марії → «Налаштування» → «Виписки банків» → «Заносити виписку Monobank у «Фінанси»». Пропустив імпорт якісь дні (сервер стояв, банк не відповідав) — наступний крок сам перечитує виписку від останнього вдалого імпорту мінус 5 хв, не далі 31 доби (22.10). Кожен рядок проходить правила імпорту («Налаштування → Фінанси → Правила імпорту»), звіряється з уже внесеними операціями (та сама сума й напрямок за ±3 дні), а без правила й угоди — потрапляє у «Фінанси → Звірка → Вхідні» з підказкою категорії. Докладно — стаття [Фінанси](finance.md), розділ 7. Операції акаунта підписані ним: журнал подій картки показує, хто й коли імпортував.

## 3. Миттєві операції (вебхук)
Вкладка «Налаштування» → «Вебхук банку…» → «Зберегти». CRM реєструє в банку свою адресу `…/api/crm/finance/bank/webhook/monobank/<секрет акаунта>` (у кількох організаціях — ще й `?org=<компанія>`). Банк перевіряє її запитом і далі на кожну операцію надсилає подію; CRM відповідає одразу, а виписку акаунта за останні хвилини перечитує у тлі — тілу події не вірить, джерело правди лише виписка. Стан видно в «Стані акаунта» і в «Стан роботи» → «Миттєві операції» («увімкнено · останнє надходження …», адреса з кнопкою «Скопіювати»).

- Банк тримає одну адресу на токен, і ліміт виписки (1 запит на хвилину) теж на токен: два акаунти з одним токеном ділять
  ліміт, а подія для одного перечитує всі увімкнені акаунти з цим токеном.
- Для рахунків ФОП, до яких вас додали «бухгалтером» (доступ до чужого рахунку), банк подій не надсилає — такі рахунки
  тягнуться лише імпортом.
- Адреса містить секрет: не публікуйте її. Чужий секрет — «не знайдено»; частіше 60 запитів на хвилину — відмова.
- Банк не прийняв адресу — «Вебхук не ввімкнено: … Інші налаштування збережено»: решту форми записано, вебхук лишився вимкненим.

## 4. Прив'язка надходжень до угоди
Поле «Прив'язувати надходження до угоди за призначенням платежу» (лише доходи, лише **несплачена** угода):
- «номер угоди у призначенні» — «№50000123», «#50000123», «sg-50000123», «угода 50000123», «замовлення 50000123»;
- «номер рахунку (документа)» — номер документа угоди, напр. «РФ-ZK-2026-0012»;
- «ТТН» — номер накладної доставки угоди;
- «усе разом» або «не прив'язувати».

Знайдено угоду — рядок одразу стає оплатою по ній: клієнт і підстава з угоди, «Сплачено» перераховується, у картці угоди біля суми платежу — пігулка «банк»; у «Вхідні» він не йде. Не знайдено — рядок у «Вхідних»: відкрийте його, у полі «Угода (№)» впишіть номер з картки угоди → «Так, усе вірно».

## 5. Хто бачить операції рахунку
Доступ іде через гаманець акаунта: поле «Хто бачить операції рахунку» — це «Доступ до гаманця» у «Фінансах» (порожньо — усі з доступом до розділу). Хто не має гаманця, не бачить ні його операцій, ні балансу. На відміну від KeepinCRM, окремого «лише доходи / лише витрати» нема: людина бачить усі операції рахунку або жодної.

## Особисті картки окремими акаунтами («Картки цього токена»)
Один токен Monobank бачить усі рахунки й картки власника: ФОП, білу, чорну, валютні. У «Налаштуваннях» акаунта є блок **«Картки цього токена»**: біля кожної — залишок (у кредитки ще кредитний ліміт) і позначка: «рахунок цього акаунта», «акаунт «…»» (уже підключена) або кнопка **«Підключити як акаунт»** (лише адміністратору).
1. Відкрийте «Інтеграції → Monobank → Налаштування» основного акаунта (того, чий токен бачить картку).
2. Біля потрібної картки натисніть «Підключити як акаунт».
3. CRM створює акаунт «Біла картка Monobank …3229» з тим самим токеном. Його «Рахунок банку» — ця картка, «Тягнути виписку
   автоматично» увімкнено, «Не заносити операції, старші за дату» — сьогодні, щоб старі особисті покупки не потрапили в журнал.
4. Гаманець — виду **«Особистий»**: наявний особистий гаманець з кінцем номера картки в назві (наприклад, заведений раніше
   вручну «Біла картка Monobank …3229»), а якщо такого немає — новий. Він показується у «Фінанси → Гаманці → Картки фізосіб»
   і в «гроші бізнесу» не входить. Виписку тягне крок Марії звичайними правилами імпорту.
5. Баланс гаманця одразу дорівнює залишку картки в банку: CRM ставить **звірену точку** із залишку картки на момент підключення
   (подія «Звірена точка … залишок картки на момент підключення» в журналі акаунта). Витрати, внесені вручну до підключення, у
   баланс уже не входять — вони сидять у залишку банку; стартовий залишок вгадувати не треба. Докладно — стаття
   [Фінанси](finance.md), розділ «6а. Звірка з банком».
Підключену картку вдруге не підключити («Цю картку вже підключено як акаунт …»). Вимкнути — перемикачем акаунта.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Monobank не налаштовано: додайте токен (MONOBANK_TOKEN) у картці «Інтеграції → Monobank»» | в акаунта нема токена | «Підключення» → «Токен» → «Ввести» |
| «Monobank: токен не прийнято (403) — перевірте MONOBANK_TOKEN» | токен відкликано чи з помилкою | новий токен на api.monobank.ua |
| «Monobank: не частіше 1 запиту на хвилину — зачекайте хвилину і повторіть» | ліміт банку на токен | повторіть за хвилину |
| «Monobank: за один запит банк віддає не більше 31 доби — зменште період» | вікно більше 31 доби | імпортуйте частинами |
| «Monobank: рахунок із налаштувань акаунта банк не показує — оберіть інший» | рахунок закрито чи це інший токен | «Оновити рахунки», оберіть рахунок |
| «Вебхук не ввімкнено: … Інші налаштування збережено» | банк не зміг відкрити адресу CRM | перевірте, що сайт доступний ззовні, збережіть ще раз |
| Миттєві операції увімкнено, а подій нема | рахунок «бухгалтера» або банк вимкнув вебхук після трьох невдач | імпорт кнопкою; вимкніть і знову ввімкніть вебхук |
| Надходження не прив'язалось до угоди | угоду вже сплачено, номера нема в призначенні або вибрано «не прив'язувати» | «Вхідні» → «Угода (№)» |
| «Імпорт виписки …: нових 0 (за N дн. по рахунку … операцій нема…)», у журналі акаунта червона подія «Увага: …» раз на добу | у «Налаштуваннях» обрано рахунок без руху (другий ФОП, закрита картка) — виписка читається з нього | «Оновити рахунки», оберіть у «Рахунок у банку» той, де є залишок (він у підписі), «Імпорт виписки» за потрібні дні |
| У журналі акаунта «Звірка залишку: у банку … у гаманці … різниця …; холди …; нез'ясовано …» | нез'ясована різниця з банком тримається довше, ніж «Через скільки днів» у «Налаштування → Фінанси → Звірка з банком» (типово 2; раз на добу, від 100 ₴ — червоним) | «Фінанси → Гаманці» → «Розібрати» на картці гаманця: холди, внесені вручну без пари в банку; якщо банк правий — «Прийняти залишок банку» |
| Автоімпорт не тягне акаунт | акаунт вимкнено, без токена або вимкнено «Тягнути виписку автоматично» | увімкніть у картці |

## Для ШІ-співробітників
Картка `describe_section("int-monobank")` — поля імпорту, дії, приклади і довідники (`monobank_accounts` — акаунти, `purses` — гаманці); доступ — розділ «Фінанси» у «Доступах» ШІ, імпорт — ще й «Фінанси: проводити й змінювати платежі». Ті самі маршрути й перевірки, що в людини; у журналі подій акаунта імпорт підписано ШІ.
- `monobank_accounts` (`kind`) — рахунки й банки акаунта з банку: id, тип, валюта, баланс, IBAN (для `account`).
- `monobank_import` (`values`: `kind`, `from`, `to`; `account`, `purse_id`, `holds` — за потреби) — імпорт виписки;
  **чекає підтвердження людини** (вид `bulk`), повтор дублів не створює.
- Що не прив'язалось — `finance_inbox`; прив'язати дохід до угоди — `finance_review` з `values={action: ok, deal_id: …}`
  (картка `finance`, вид `payments`).

ШІ **не може** змінювати налаштування акаунтів, вмикати вебхук, вводити чи читати токени — інструментів для цього нема, маршрут налаштувань ШІ відмовляє; це робить адміністратор у картці. Не імпортуйте без прохання людини, не повторюйте дію з `pending_id` і не вигадуйте `kind` — беріть з `monobank_accounts` у картці.


---

# Monobank для бізнесу (ТОВ, ФОП)

Інтеграція «Monobank для бізнесу» дає платити з рахунку компанії чи ФОП прямо з CRM: ви готуєте платіж постачальнику, перевізнику чи партнеру, CRM надсилає його в банк чернеткою, а директор підписує в застосунку monobank. Після підпису платіж сам стає витратою у «Фінансах» з підставою — оплатою партії чи виплатою партнеру; без підпису людини в банку гроші не йдуть ніколи. Це бізнес-API monobank (кабінет компанії або ФОП у web.monobank.ua), окремий від особистого API, яким CRM читає виписку (стаття «Monobank»): для одного рахунку ФОП у вас може бути дві картки — «Monobank» (виписка) і «Monobank для бізнесу» (платежі). Гаманець без такого ключа (особиста картка, готівка) теж платить з CRM — у режимі «до сплати» (стаття «Фінанси», §7д).

## Можливості
- Вкладка «Фінанси → Платежі»: усі платежі зі станом «Чернетка», «Чекає підпису», «До сплати», «Проведено», «Відхилено», «Помилка».
- Рахунок ТОВ і рахунок ФОП — однаково (ключ з кабінету ФОП); гаманець без ключа — платіж «до сплати».
- Платіж з будь-якого місця: довільний, оплата партії закупівлі (сума «ще винні» й отримувач з картки), виплата партнеру.
- Перевірки до банку: IBAN (UA і 27 цифр), ЄДРПОУ (8 цифр) чи РНОКПП (10 цифр), сума, призначення.
- Підписаний платіж — витрата у «Фінансах» сама: з гаманцем акаунта, підставою, контрагентом; партія — «сплачено», виплата — «виплачено».
- Повтор безпечний: повторне надсилання не створює в банку другу чернетку; виписка дубля не дає.
- Кілька акаунтів (кілька компаній чи токенів), у журналі подій — хто що надіслав, IBAN лише хвостом «…1234».

## 1. Налаштування
Підключає адміністратор. Дорога: «Інтеграції» (головне меню) → «Оплати» → картка «Monobank для бізнесу (ТОВ)».

1. Токен: увійдіть у web.monobank.ua у кабінет компанії (ТОВ) **або ФОП** з правами директора / власника → «Мої токени»
   (`web.monobank.ua/?modal=tokens`) → створіть токен. Для ФОП це той самий бізнес-API: ключ береться в кабінеті ФОП, а не в
   особистому застосунку; якщо пункту «Мої токени» в кабінеті ФОП нема — замовте доступ до бізнес-API у підтримці monobank для
   бізнесу. Поле ключа в картці підписано «Токен бізнес-API (кабінет ТОВ або ФОП)», підказка під ним — та сама дорога.
2. Вкладка «Підключення» → «Токен» → «Ввести» → вставте → «Зберегти ключ» → «Перевірити» (успіх — «рахунків: N»).
   Один кабінет — один акаунт картки: основна картка — ваш ФОП (чи ТОВ), другий кабінет — «+» → «Додати акаунт».
3. Увімкніть перемикач «Інтеграція»: вимкнений акаунт не приймає нових платежів і не надсилає їх у банк.
4. Ще одна компанія чи токен — «+» у правому нижньому куті картки → «Назва», токен → «Додати акаунт».

Гаманець платежів за замовчуванням — «Monobank бізнес» (створиться сам); інший обирається в шторці платежу. Якщо рахунок ФОП у CRM уже є гаманцем «Монобанк ФОП» (виписка через особистий API) — у шторці платежу оберіть цей гаманець і в «Акаунт» — акаунт бізнес-API: CRM запам'ятає пару і далі платитиме з нього через банк без запитань. IBAN і ЄДРПОУ постачальника чи перевізника можна вписати заздалегідь: «Закупівлі» → «Довідники» → постачальник / перевізник → «IBAN», «ЄДРПОУ / РНОКПП».

## 2. Платіж з CRM
1. «Фінанси» → «Платежі» → «Новий платіж банку». Відкривається шторка платежу.
2. «Гаманець» (підписано «через банк» або «до сплати») → «Акаунт» → «Рахунок-відправник» (лише гривневі рахунки; порожньо —
   перший гривневий) → «Отримувач» (почніть писати — з'являться підказки: ваші юрособи, постачальники й перевізники з IBAN,
   попередні отримувачі) → «IBAN», «ЄДРПОУ / РНОКПП» → «Сума, ₴» → «Призначення». Гаманець «до сплати» (картка, готівка) —
   без рахунку-відправника, зате зі строком і категорією: платіж стане плановою в «Планових», а закриє його кнопка «Оплачено»
   або рядок виписки (стаття «Фінанси», §7д).
3. «Надіслати в банк» — платіж іде в банк і стає «Чекає підпису»; «Зберегти чернетку» — лише в CRM (банк її не бачить).
4. Директор відкриває застосунок monobank (чи web-кабінет) і підписує або відхиляє чернетку.
5. CRM дізнається про це сама: кнопка «Перевірити» в рядку, «Перевірити все» над списком або крок ШІ Марії Йосипівни (з
   кожним її кроком — типово раз на 30 хвилин — лише коли є платежі «Чекає підпису»). Підписано й з'явилося у виписці —
   «Проведено» і витрата у «Фінансах»; відхилено — «Відхилено».

Фільтр над списком — «Усі», «Чекає підпису», «До сплати», «Проведено», «Відхилено», «Чернетки». У рядку — «Перевірити», «Надіслати в банк» (для чернетки й помилки), «Оплачено» (для «До сплати»), «Прибрати» (чернетка, помилка чи «до сплати»; чернетку, вже надіслану в банк, приберіть ще й у застосунку банку). Платіж «Чекає підпису» понад тиждень стає «Помилка» з текстом «не підписано за тиждень». Банк не прийняв платіж під час надсилання — платіж лишається зі станом «Помилка» і текстом банку; «Надіслати в банк» ще раз безпечно. Платіж лише в гривні. Платіж без підстави й без категорії стає витратою у «Вхідних» — розберіть його там.

## 3. Оплата партії закупівлі
«Закупівлі» → партія → «Оплати партії» → «Оплатити через Monobank» (біля «+ Оплата», поки частина не сплачена). Шторка заповнюється сама: сума «ще винні» частини, призначення «Оплата за товар, партія №…» (доставка — «Оплата доставки…»), отримувач з картки постачальника чи перевізника. Після «Проведено» оплата з'являється в оплатах партії зі «звірено», борг падає. IBAN і ЄДРПОУ, вписані в шторці, після першого проведеного платежу запам'ятовуються в картці постачальника чи перевізника, якщо там було порожньо.

## 4. Виплата партнеру
«Фінанси» → «Партнери» → «Виплати» → затверджена виплата → «Оплатити через Monobank». Сума й призначення («Виплата партнеру №…») — з виплати, отримувач — партнер; IBAN і ЄДРПОУ / РНОКПП партнера впишіть у шторці (у картці партнера IBAN поки не зберігається, шторка підкаже «вкажіть IBAN партнера»). Після «Проведено» виплата стає виплаченою з операцією «Виплата партнеру»; кнопкою «Виплатити» другий раз її проводити не треба.

## 5. Виписка рахунку ТОВ
Виписка рахунку компанії заводиться тим самим шляхом, що Monobank ФОП: правила імпорту → звірка з уже внесеним → «Вхідні». Операція платежу, проведеного кнопкою «Перевірити», другим рядком не з'являється (той самий id банку); і навпаки — якщо виписку імпортували раніше за перевірку, перевірка бере вже наявний рядок. Кнопки в «Імпорті виписки» для ТОВ поки нема: імпорт — маршрутом `POST /api/crm/finance/import/monobiz` або дорученням ШІ (`monobiz_import`); за раз — до 500 рядків. 10).

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «IBAN отримувача: потрібно UA і 27 цифр…» | IBAN з помилкою | перевірте IBAN у рахунку отримувача |
| «ЄДРПОУ / РНОКПП отримувача: 8 цифр (юрособа) або 10 цифр (ФОП, фізособа)» | код неповний | впишіть код повністю |
| «акаунт «…» вимкнено — увімкніть його в «Інтеграції → Оплати»» | перемикач «Інтеграція» вимкнено | увімкніть акаунт |
| «у акаунта «…» не задано токен (MONOBIZ_TOKEN)…» | нема токена | «Підключення» → «Токен» |
| «Monobank бізнес: токен не прийнято (HTTP 401/403)…» | токен відкликано | новий токен у «Мої токени» |
| «Monobank бізнес: забагато запитів — зачекайте…» | ліміт банку | повторіть пізніше |
| «платежі з CRM — лише в гривні (UAH)» | інша валюта | оберіть гривневий рахунок |
| Стан «Відхилено» | директор відхилив у застосунку або банк відхилив операцію | створіть новий платіж |
| Стан «Помилка», «не підписано за тиждень» | чернетку ніхто не підписав | приберіть чернетку в банку або «Надіслати в банк» знову |
| «платити через банк нема чим…» у шторці | у гаманця нема акаунта бізнес-API | оберіть акаунт (ключ ТОВ чи ФОП) або гаманець «до сплати» |
| Стан «Відхилено», «планову прибрано з журналу» | платіж «до сплати», а його планову видалили в «Планових» | створіть платіж знову |

## Для ШІ-співробітників
Картка `describe_section("int-monobiz")` — поля платежу, дії, приклади; доступ — розділ «Фінанси» у «Доступах» ШІ, запис — ще й «Фінанси: проводити й змінювати платежі» і доступ до гаманця (як у людини).
- `bank_payments_list` (`state`, `kind`, `page`, `per_page`) — платежі зі станом; `bank_payments_refs` (`refresh`) — акаунти з
  рахунками банку, отримувачі, гаманці.
- `bank_payment_for_purchase` (`purchase_id`, `part`) — готова заготовка платежу за партію; нічого не пише.
- `bank_payment_create` (`values` — як у шторці; `send: true` — одразу в банк) — **чекає підтвердження людини** (вид
  `payments`); після «Підтвердити» платіж ще чекає підпису директора в застосунку банку. Повтор з тим самим
  `idempotency_key` другого платежу не створює.
- `bank_payment_send` (`payment_id`) — надіслати чернетку в банк; теж вид `payments`.
- `bank_payment_check` (`payment_id`) і `bank_payments_check_all` — без кошика: лише читають стан у банку й проводять витрату,
  яку людина вже підписала.
- `monobiz_import` (`values`: `kind`, `from`, `to`, `iban`) — виписка ТОВ; вид `bulk`.

ШІ **не може** підписати платіж (це робить лише людина в банку), прибрати чернетку, змінити токен чи налаштування акаунта. Не створюйте платіж без прямого прохання людини, не повторюйте дію з `pending_id`, реквізити беріть з `bank_payment_for_purchase` чи `bank_payments_refs`, а не вигадуйте.

## Додаткова інформація
- Пов'язані статті: [Monobank (виписка ФОП)](int-monobank.md), [Фінанси](finance.md), [Закупівлі](procurement.md).
- Застереження: офіційна документація бізнес-API з хмари не відкрилася, поля запитів узято з неофіційного опису; перший
  платіж на живому токені перевірте на малій сумі.


---

# ПриватБанк

Інтеграція з ПриватБанком імпортує виписку рахунку ФОП чи юрособи через API «Автоклієнт» Приват24 для бізнесу в «Фінанси». Беруться лише проведені банком операції, категорія підбирається за призначенням платежу, а повторний імпорт дублів не створює.

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

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Оплати» → картка «ПриватБанк» → «Підключення».

1. Токен: Приват24 для бізнесу → Каталог послуг → Інтеграція (Автоклієнт) → токен. У картці — рядок `PRIVATBANK_TOKEN` → «Ввести» → «Зберегти ключ».
2. Рахунок за замовчуванням (необов'язково): рядок `PRIVATBANK_ACCOUNT` — IBAN рахунку.
3. «Перевірити» читає залишки: успіх — «рахунків: N».

Ключі зберігаються зашифрованими й назад не показуються. Одна картка — один токен; кількох токенів (кількох клієнтів банку) поки нема. У режимі кількох організацій імпорт читає токен лише зі змінних сервера.

## 2. Імпортувати виписку
1. «Фінанси» → «Операції» → «Імпорт виписки».
2. Блок «ПриватБанк»: «Рахунок» («перший у гривні» або інший після «Показати рахунки»), «Гаманець» (вибраний або «ПриватБанк» (створиться)), «Від» і «До».
3. «Імпортувати з ПриватБанку».

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

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Не налаштовано: додайте PRIVATBANK_TOKEN …» в «Імпорті виписки» | Токен не задано | Введіть токен у картці ПриватБанку |
| «не задано (у картці чи .env): PRIVATBANK_TOKEN, PRIVATBANK_ACCOUNT» | «Перевірити» без ключів | Введіть токен і IBAN |
| Повідомлення банку після «Перевірити» | Токен недійсний | Створіть новий токен в «Автоклієнті» |

## Для ШІ-співробітників
5`). Операції з виписки ШІ бачить у «Фінансах» (коли є доступ). Статтю ШІ читає інструментом `help("int-privatbank")`.

## Додаткова інформація
- Пов'язані статті: [Фінанси](finance.md), [Monobank](int-monobank.md).


---

# NovaPay

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

## Можливості
- Скільки завгодно акаунтів NovaPay: у кожного ФОП чи ТОВ — свої логін, Refresh Token і сертифікат, свій гаманець, свій журнал подій.
- Виписка кабінету у «Фінанси»: кнопкою за період і автоматично кроком ШІ Марії Йосипівни; беруться лише проведені платежі.
- «Автоматичні платежі» як у KeepinCRM: проводити платежі (дохід — до угоди за ТТН чи номером у призначенні, інакше у вибрану
  категорію; витрата — у свою категорію) або не проводити (усе у «Вхідні» на ручний розбір).
- Реєстри NovaPay: щодня після 9:00 за вчора — ТТН, сума, комісія, ПІБ клієнта, номер замовлення; оплата — дохід по угоді з цією
  ТТН, комісія — витрата з підставою «угода» (угоди за останні 60 днів, число налаштовується).
- Виплата реєстру на рахунок («Переказ коштів по платежам, прийнятим від населення … згідно реєстру № …») — переказ з
  транзитного гаманця, не другий дохід; реєстру ще нема — рядок чекає у «Вхідних» і стає переказом сам.
- Залишок рахунку з кабінету — у «Стані роботи» поруч з балансом гаманця.
- Правила імпорту, звірка з уже внесеними операціями, «Вхідні» для решти — той самий шлях, що в Monobank і ПриватБанку.
- Без дублів: повтор за ключем платежу пропускається, рядок, що вже приїхав з KeepinCRM того самого дня й суми, — теж.

## 1. Налаштування
Підключає адміністратор. Дорога: «Інтеграції» (головне меню) → «Оплати» → картка «NovaPay».

**Ключі.** У бізнес-кабінеті NovaPay: «Система → Налаштування → API» — там видаються логін, Refresh Token (Токен) і Public Certificate (Сертифікат). У картці, вкладка «Підключення»: «Логін» → «Ввести» → «Зберегти ключ»; так само «Refresh-токен» і «Сертифікат (PEM)» (сертифікат вставляється повністю, у багаторядкове поле). «Перевірити» заходить у кабінет і показує «кабінет NovaPay: рахунків N».

Важливо про токен: він **одноразовий**. Кожен вхід у кабінет повертає новий токен і сертифікат, старі одразу недійсні — CRM зберігає нову пару сама, тож у картці після «Перевірити» видно вже інші останні символи. Один кабінет NovaPay підключається лише до однієї системи: щойно ви згенерували токен і ввели його тут, KeepinCRM цим кабінетом більше не користується (і навпаки — новий токен у KeepinCRM зламає доступ CRM; тоді згенеруйте ще один і впишіть сюди). Ключі зберігаються зашифрованими й назад не показуються.

**Акаунти.** Основна картка — теж акаунт («Основний»; назву можна змінити в рядку «Назва акаунта»). Ще один кабінет (другий ФОП, ТОВ) — «+» у правому нижньому куті картки → «Назва» і три ключі → «Додати акаунт». Акаунти перемикаються під шапкою картки; кожен має свої ключі (чужих не позичає), гаманець і налаштування.

**Вкладка «Налаштування»** акаунта. Угорі — «Стан акаунта» (ключі, рахунок у NovaPay з балансом, гаманець, останній імпорт, реєстри з останніми рядками) і кнопка «Оновити рахунки» (вхід у кабінет і свіжий список рахунків з балансами). Нижче — форма; змінює її адміністратор, решта бачить без збереження. Зберегли — імпорт і крок Марії беруть нове одразу.

**«Стан роботи»** на вкладці «Підключення»: рядок «Рахунок у NovaPay» — рахунок, залишок у банку на час останнього імпорту й баланс гаманця: «… · залишок у банку 25 850,81 ₴ (20.10 01:10), у гаманці 25 850,81 ₴». Не збігаються — дописано «не збігається: перевірте «Вхідні» і стартовий залишок» (розділ 3б); банк залишку не віддав — «залишок: банк не віддає — введіть його в картці гаманця».

| Поле | Що робить | Типово |
| --- | --- | --- |
| «Рахунок у NovaPay» | з якого рахунку береться виписка; порожньо — усі активні гривневі рахунки кабінету | усі гривневі |
| «Гаманець у «Фінансах»» | куди лягають операції виписки | гаманець акаунта (створиться; основна картка — «NovaPay») |
| «Хто бачить операції рахунку» | розділ 5 | усі з доступом до «Фінансів» |
| «Тягнути виписку автоматично (крок ШІ Марії)» | автоімпорт цього акаунта | так |
| «Що робити з новими платежами» | розділ 2 | проводити |
| «Дохід…», «Приєднати дохід до угоди…», «Категорія доходу без угоди» | розділ 2 | так · усе разом · у «Вхідні» |
| «Витрата…», «Категорія витрати» | розділ 2 | ні · у «Вхідні» |
| «Скільки останніх днів виписки перечитувати щоразу» | вікно автоімпорту, 1–31 | 3 |
| «Не заносити операції, старші за дату» | нижня межа автоімпорту | без межі |
| «Завантажувати реєстри NovaPay», «Проводити оплати як дохід…», «Проводити комісію…», «Гаманець для оплат і комісій з реєстру», «Категорія комісії», «Шукати угоди… за останні днів» | розділ 3 | ні · ні · ні · транзитний · «Комісія NovaPay» · 60 |

Автоімпорт тягне лише **увімкнені** акаунти (перемикач «Інтеграція» на вкладці «Підключення»). Раніше виписку NovaPay тягнув старий синк Марії з ключів сервера, хоч би який був перемикач; щоб вона не зупинилася мовчки, основна картка з ключами, яку ніхто ніколи не вимикав, один раз увімкнулася сама — у журналі подій картки є запис «увімкнено автоматично». Вимкнете — більше сама не ввімкнеться. Ключі, що жили в старому синку чи в `.env` сервера, після першого входу переїжджають у картку (запис «ключі NovaPay перенесено в картку»).

## 2. Автоматичні платежі
Поле «Що робити з новими платежами»:
- **Проводити платежі.** Кожен рядок спершу проходить правила імпорту («Налаштування → Фінанси → Правила імпорту») і звірку з
  уже внесеними операціями. Далі дохід: якщо «Дохід: проводити надходження» увімкнено, CRM шукає **несплачену** угоду за
  призначенням платежу — «Приєднати дохід до угоди»: «ТТН» (номер накладної в призначенні, як у накладеному платежі), «номер
  угоди у призначенні» («№50000123», «sg-50000123», «угода 50000123»), «номер рахунку (документа)» («РФ-ZK-2026-0012»), «усе
  разом» або «не приєднувати». Знайшли — рядок одразу стає оплатою по угоді. Не знайшли — операція з «Категорією доходу без
  угоди» проводиться без перевірки; категорія порожня — рядок у «Вхідні» з підказкою. Витрата: «Витрата: проводити списання»
  і «Категорія витрати» — так само; вимкнено — у «Вхідні».
- **Не проводити платежі.** Усі рядки заводяться у «Вхідні» («Фінанси → Звірка») на ручний розбір; правила імпорту діють і тут.

У «Вхідних» рядок відкривається, у полі «Угода (№)» вписується номер з картки угоди → «Так, усе вірно»; «Запам'ятати правило» створює правило імпорту з цього рядка. Докладно — стаття [Фінанси](finance.md), розділи 7 і 7а.

## 3. Реєстри NovaPay
Реєстр переказів накладеного платежу — список оплат за доставками: назва реєстру, дата, номер ТТН, сума переказу, комісія, ПІБ клієнта, номер замовлення. Увімкніть «Завантажувати реєстри NovaPay» — крок Марії щодня після 9:00 за Києвом замовляє в кабінеті реєстр за вчора по кожному підприємству акаунта, чекає, доки NovaPay підготує файл (іноді до наступного кроку), і заносить рядки у список акаунта (повтор того самого рядка не дублюється). Завантажені рядки видно у «Стані акаунта».

Файл реєстру NovaPay (CSV) має колонки «Дата перерахунку коштів», «Номер реєстру» (`BO019263634`), «Сума принятих коштів» (скільки заплатив клієнт), «Сума утриманої винагороди» (комісія NovaPay, 0,5 %), «Сума перерахованих коштів», «ПІБ Покупця», «№ ЕН НП», «Номер замовлення». Один реєстр — одна виплата на рахунок (розділ 3а).

Проведення (кожне окремо вмикається):
- «Проводити оплати як дохід по угоді з цією ТТН» — угода, створена за останні N днів («Шукати угоди… за останні днів», типово
  60), отримує дохід на «Суму принятих коштів». Одна посилка на кілька угод (одна ТТН) — сума розкладається: кожна угода, від
  старшої, отримує свій несплачений залишок (у рядку позначка «одна посилка на угоди …»). Угоду вже сплачено повністю —
  дохід не дублюється («угоду вже сплачено»). Угоду з ТТН не знайдено — дохід без угоди лягає у «Вхідні» («Фінанси →
  Звірка») з поясненням: впишіть «Угода (№)» і «Так, усе вірно». Гроші ж прийшли — так гаманець реєстрів сходиться з виплатою.
- «Проводити комісію як витрату по угоді з цією ТТН» — витрата на «Суму утриманої винагороди» з категорією «Категорія комісії»
  (типово «Комісія NovaPay», створюється) з підставою «угода» — як комісія майданчика: бізнес і юрособа — угоди, а «Сплачено»
  угоди вона не зменшує (з 20.10; раніше угода лишалась «винною» ці 0,5 %).

Обидві операції лягають у «Гаманець для оплат і комісій з реєстру» — типово транзитний «NovaPay: накладені платежі» (тип «Транзитний»): його баланс = скільки NovaPay ще має перерахувати. Після виплати (розділ 3а) він повертається до нуля.

**Межа з KeepinCRM.** До 14.10 виплати NovaPay заносив KeepinCRM — доходом «Переказ коштів по платежам…» без угод. Рядки реєстру, чию виплату вже вніс KeepinCRM (або людина провела рядок «Вхідних» доходом), не проводяться: позначка «виплату реєстру № … уже внесено доходом (KeepinCRM) — тут не проводиться». Інакше той самий дохід був би двічі.

## 3а. Виплати накладених платежів з виписки
NovaPay перераховує зібрані накладені платежі на рахунок одним платежем на реєстр: «Переказ коштів по платежам, прийнятим від населення за товари/послуги згідно реєстру № 19263634 від 17.10.2026 …». Сума — «Сума перерахованих коштів» усіх рядків цього реєстру.

- **Реєстри й «Проводити оплати як дохід» увімкнено.** Виплата — **переказ** з гаманця реєстрів у гаманець рахунку: дві
  операції без категорії (у гаманці рахунку надходження, у транзитному — списання), у звітах це не дохід і не витрата.
  Дохід бізнесу — лише рядки реєстру по угодах. Номер реєстру з призначення шукається серед завантажених рядків реєстру.
- **Реєстру ще нема** (виплата прийшла сьогодні, реєстр за день буде завтра після 9:00) — виплата лягає у «Вхідні» з
  підказкою «виплата накладених платежів: реєстру № … ще нема — щойно він завантажиться…». Нічого робити не треба: щойно
  реєстр завантажиться, рядок сам стане переказом (крок Марії, кнопка «Завантажити реєстри» чи «Імпортувати виписку»).
  Якщо реєстр дня завантажився без цієї виплати, крок Марії після 9:00 перезамовляє його (не частіше раз на 6 годин,
  3 дні). Провели такий рядок доходом самі — рядки його реєстру по угодах уже не проводяться (дохід один).
- **Реєстри вимкнено.** Виплата — надходження у «Вхідні», як раніше (до угоди за «№ …» у призначенні вона не чіпляється:
  це номер реєстру, а не угоди).

У підсумку імпорту видно «переказів N», «виплат → переказ з реєстру N», «виплат чекають реєстр N»; сума виплати не збіглася з реєстром — «розбіжність з реєстром: …» (перевірте рядки реєстру в «Стані акаунта»).

## 3б. Залишок рахунку і стартовий залишок гаманця
Кожен імпорт виписки читає залишок рахунку в кабінеті (`GetAccountRest`) — він у «Стані роботи» поруч з балансом гаманця. Баланс гаманця = стартовий залишок + усі операції гаманця. Щоб він дорівнював банку, стартовий залишок виставляється один раз: стартовий = залишок у банку − поточний баланс без стартового («Фінанси → Гаманці» → гаманець → «Стартовий залишок»; або скриптом розробника, тоді в журналі подій акаунта — «стартовий залишок гаманця …: старе → нове»). Далі баланс сходиться сам, поки виписка тягнеться щодня (надходження й списання; списання без категорії — у «Вхідних», але в балансі вже враховані).

Стартовий може бути від'ємним: KeepinCRM до 14.10 заносив у гаманець лише виплати накладених платежів, а виведення з рахунку (на картку, готівкою) — ні; від'ємний стартовий і є цією різницею. Історію до 14.10 не переносимо — «Не заносити операції, старші за дату» стоїть на 14.10.

## 4. Імпорт виписки й реєстрів кнопкою
1. «Фінанси» → «Операції» → «Імпорт виписки» (кнопку бачать ті, хто може проводити платежі).
2. Блок «NovaPay»: «Акаунт» (поле є, коли акаунтів більше одного), «Гаманець» («з налаштувань акаунта» або інший), «Від» і
   «До».
3. «Імпортувати виписку NovaPay» — проведені платежі рахунку (чи всіх гривневих рахунків) за дні; підсумок: «нових N, за
   правилами N, прив'язано до угод N, звірено з внесеними N, у «Вхідні» N, пропущено N, уже є з KeepinCRM N».
4. «Завантажити реєстри» — реєстри за ті самі дні: «рядків N нових з M, угод знайдено N, доходів N, комісій N»; «файлів ще
   готується N» — NovaPay ще готує файл, його підтягне наступний крок Марії (або повторне натискання).
5. «Перекласти з реєстру Марії» — старий шлях: рядки, які старий синк Марії поклав у свій реєстр до переходу на акаунти.

Загальний вимикач автоімпорту — пульт Марії → «Налаштування» → «Виписки банків» → «Заносити виписку й реєстри NovaPay у «Фінанси»». Операції підписані акаунтом: журнал подій картки показує, хто й коли імпортував.

## 5. Хто бачить операції рахунку
Доступ іде через гаманець акаунта: поле «Хто бачить операції рахунку» — це «Доступ до гаманця» у «Фінансах» (порожньо — усі з доступом до розділу). Хто не має гаманця, не бачить ні його операцій, ні балансу. Реєстрові оплати й комісії лежать у гаманці реєстрів — доступ до них задається в «Фінанси → Гаманці» окремо.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «NovaPay не налаштовано: введіть логін, Refresh Token і сертифікат…» | в акаунта нема одного з трьох ключів | «Підключення» → «Ввести» кожен ключ |
| «NovaPay UserAuthenticationJWT: … Invalid token» | токен уже використано деінде (KeepinCRM чи другий сервер) або введено з помилкою | згенеруйте новий токен і сертифікат у кабінеті NovaPay, впишіть у картку |
| «NovaPay UserAuthenticationJWT: … Refresh token does not apply to login — токен одноразовий: введіть нову пару…» | токен уже використано (той самий кабінет підключено ще десь, у кабінет входив другий процес чи скрипт) або токен не від цього логіна й сертифіката (ввели новий токен, а сертифікат лишили старий) | згенеруйте в кабінеті NovaPay нову пару і введіть **і токен, і сертифікат** разом; якщо повторюється — подивіться журнал картки: запис «нову пару ключів NovaPay не вдалося записати в базу» означає, що база була зайнята в мить ротації (пара до запису в базу лежить у пам'яті й у зашифрованому файлі поруч із базою, тож наступний вхід її підхопить сам; нова з кабінету потрібна, лише якщо помилка не минає) |
| «NovaPay: рахунок із налаштувань акаунта кабінет не показує — оберіть інший» | рахунок закрито або це інший кабінет | «Оновити рахунки», оберіть рахунок |
| «NovaPay: дата «від» пізніша за «до»» | переплутано дати | поправте період |
| «у реєстрі не знайдено колонку суми (колонки: …)» | NovaPay змінив формат файлу реєстру | напишіть розробнику з назвами колонок із повідомлення |
| «реєстр … так і не підготувався в NovaPay» | кабінет не віддав файл за 3 дні | замовте ще раз кнопкою «Завантажити реєстри» |
| Оплата з реєстру не стала доходом по угоді | угоду вже сплачено повністю | у «Стані акаунта» рядок «угоду вже сплачено»; перевірте, чим її сплачено |
| Дохід з реєстру у «Вхідних»: «угоду з цією ТТН не знайдено» | угода старша за N днів, без ТТН або ТТН записано інакше | у «Вхідних» впишіть «Угода (№)» → «Так, усе вірно» |
| «виплату реєстру № … уже внесено доходом (KeepinCRM) — тут не проводиться» | виплату цього реєстру вже вніс KeepinCRM (до 14.10) чи людина провела її доходом | нічого — дохід один; по угодах проведіть вручну, лише якщо приберете той дохід |
| Виплата у «Вхідних» з підказкою «реєстру № … ще нема» | реєстр за день NovaPay віддає наступного дня після 9:00 | нічого — рядок стане переказом сам, щойно реєстр завантажиться |
| «розбіжність з реєстром: виплата X, за реєстром Y» | у реєстрі не всі рядки (NovaPay дописав пізніше) або змінився формат | «Завантажити реєстри» за той день; не допомогло — напишіть розробнику |
| У «Стані роботи» «залишок: банк не віддає — введіть його в картці гаманця» | кабінет не повернув залишок рахунку | впишіть «Стартовий залишок» у картці гаманця так, щоб баланс = залишку в кабінеті NovaPay |
| «… у гаманці X — не збігається: перевірте «Вхідні» і стартовий залишок» | виписку тягнули не за всі дні або стартовий залишок не задано | «Імпортувати виписку» за пропущені дні; стартовий = банк − баланс без стартового (розділ 3б) |
| Автоімпорт не тягне акаунт | акаунт вимкнено, без ключів або вимкнено «Тягнути виписку автоматично» | увімкніть у картці |

## Для ШІ-співробітників
Картка `describe_section("int-novapay")` — поля імпорту, дії, приклади і довідники (`novapay_accounts` — акаунти, `purses` — гаманці); доступ — розділ «Фінанси» у «Доступах» ШІ, імпорт — ще й «Фінанси: проводити й змінювати платежі». Ті самі маршрути й перевірки, що в людини; у журналі подій акаунта імпорт підписано ШІ.
- `novapay_import` (`values`: `kind`, `from`, `to`; `account`, `purse_id` — за потреби) — виписка кабінету за дні через
  «Автоматичні платежі» акаунта; **чекає підтвердження людини** (вид `bulk`), повтор дублів не створює.
- `novapay_registers` (`values`: `kind`, `from`, `to`) — реєстри накладених платежів за дні → рядки, дохід і комісія по
  угодах з ТТН; теж через кошик `bulk`.
- Що не прив'язалось — `finance_inbox`; прив'язати дохід до угоди — `finance_review` з `values={action: ok, deal_id: …}`
  (картка `finance`, вид `payments`).

ШІ **не може** вводити чи читати ключі, змінювати «Автоматичні платежі» й реєстри — інструментів для цього нема, маршрут налаштувань ШІ відмовляє; це робить адміністратор у картці. Не імпортуйте без прохання людини, не повторюйте дію з `pending_id` і не вигадуйте `kind` — беріть з `novapay_accounts` у картці. Статтю ШІ читає інструментом `help("int-novapay")`.


---

# LiqPay

Інтеграція з LiqPay створює посилання на оплату угоди, яке менеджер надсилає клієнту. Коли клієнт сплатив, оплата сама проводиться доходом по угоді в «Фінансах» — один раз, без дублів.

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

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Оплати» → картка «LiqPay» → «Підключення».

1. Рядки `LIQPAY_PUBLIC_KEY` і `LIQPAY_PRIVATE_KEY` → «Ввести» → «Зберегти ключ». Публічний і приватний ключі — у кабінеті LiqPay вашого магазину. Ключі зберігаються зашифрованими.
2. Перевірки кнопкою нема — дивіться стан ключів і журнал; перша спроба створити посилання покаже, чи ключі правильні.

Одна картка — один магазин LiqPay; кількох поки нема. У режимі кількох організацій ключі читаються лише зі змінних сервера.

## 2. Створити посилання на оплату
1. Картка угоди → блок «Фінанси» → «Посилання на оплату».
2. Провайдер «LiqPay», «Сума посилання» (порожньо — несплачений залишок), «Гаманець зарахування» (порожньо — перший гаманець) → «Створити посилання».
3. Посилання скопіюється — надішліть його клієнту. У списку посилань: сума, стан, «Скопіювати».

Блок не показується в архівній угоді. Якщо LiqPay і MonoPay не підключені, у блоці підказка «Посилання на оплату: підключіть LiqPay або MonoPay …».

## 3. Як фіксується оплата
- Автоматично: LiqPay повідомляє Helomi про оплату; CRM перепитує статус у LiqPay (тілу повідомлення не вірить) і проводить дохід по угоді.
- Вручну: «Перевірити оплату» біля посилання → «Оплачено — платіж додано в угоду» або стан лишається «очікує».

Платіж з'являється в блоці «Фінанси» угоди і в «Фінанси → Операції»; «Сплачено» і «Очікується» перераховуються.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «LiqPay не налаштовано: додайте LIQPAY_PUBLIC_KEY і LIQPAY_PRIVATE_KEY …» | Ключі не введено | Введіть обидва ключі в картці |
| «сума має бути більшою за нуль» | Нульова сума | Вкажіть суму |
| «LiqPay: …» | LiqPay відхилив запит | Перевірте ключі й налаштування магазину |

## Для ШІ-співробітників
5`). Оплату, що прийшла, ШІ бачить у платежах угоди (`deals_get`). Статтю ШІ читає інструментом `help("int-liqpay")`.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Фінанси](finance.md), [MonoPay](int-monopay.md).


---

# MonoPay (Plata by mono)

Інтеграція з MonoPay (еквайринг Plata by mono) створює посилання на оплату угоди через monobank. Клієнт сплачує карткою за посиланням, а оплата сама проводиться доходом по угоді в «Фінансах» — один раз, без дублів.

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

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Оплати» → картка «MonoPay (Plata by mono)» → «Підключення».

1. Рядок `MONOPAY_TOKEN` → «Ввести» → «Зберегти ключ». Токен еквайрингу — у кабінеті Plata by mono. Зберігається зашифрованим.
2. «Перевірити» читає дані мерчанта: успіх — його назва.

Одна картка — один мерчант; кількох поки нема. У режимі кількох організацій токен читається лише зі змінних сервера.

## 2. Створити посилання на оплату
Картка угоди → блок «Фінанси» → «Посилання на оплату» → провайдер «MonoPay», «Сума посилання», «Гаманець зарахування» → «Створити посилання». Посилання скопіюється — надішліть клієнту. Стан: «очікує оплати», «оплачено», «не вдалося», «прострочено».

## 3. Як фіксується оплата
Автоматично — за повідомленням monobank (CRM перепитує статус у банку) — або кнопкою «Перевірити оплату». Оплата стає платежем угоди: блок «Фінанси», «Фінанси → Операції», перерахунок «Сплачено» і «Очікується».

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «MonoPay не налаштовано: додайте MONOPAY_TOKEN (еквайринг Plata by mono) …» | Токен не введено | Введіть токен у картці |
| «MonoPay: валюта … не підтримується» | Угода не в гривні чи іншій підтримуваній валюті | Виставте посилання в підтримуваній валюті |
| «MonoPay: …» | Банк відхилив запит | Перевірте токен і стан мерчанта |
| «сума має бути більшою за нуль» | Нульова сума | Вкажіть суму |

## Для ШІ-співробітників
5`). Оплату ШІ бачить у платежах угоди (`deals_get`). Статтю ШІ читає інструментом `help("int-monopay")`.

## Додаткова інформація
- Пов'язані статті: [LiqPay](int-liqpay.md), [Monobank](int-monobank.md), [Фінанси](finance.md).


---

# RozetkaPay

Інтеграція з RozetkaPay тягне оплати покупців у «Фінанси» без людини: кожна оплата стає доходом по угоді за номером замовлення, комісія RozetkaPay видно в кожному платежі, повернення — витратою по угоді. Платежі приходять двома шляхами: звіт транзакцій API кожні 30 хвилин і миттєвий вебхук з підписом. Якщо дохід угоди вже нарахувало правило каналу (Prom, Rozetka), другого доходу не буде — угода лише позначається «оплачено через RozetkaPay». Повтор того самого платежу (вебхук і звіт, повторний вебхук) нічого не дублює.

## Можливості
- Картка з логіном і паролем (секретом) мерчанта RozetkaPay — зашифровано, назад у браузер не віддається.
- «Перевірити» — запит до API RozetkaPay: ключі прийнято чи ні; після вдалої перевірки картка вмикається сама.
- Автоімпорт зі звіту транзакцій API кожні 30 хвилин за останні 3 дні (число налаштовується, до 14) і кнопка «Підтягнути зараз».
- Вебхук: адреса з секретом для `callback_url`, перевірка підпису `X-ROZETKAPAY-SIGNATURE`, платіж у журналі за секунди.
- Дохід по угоді за номером замовлення (Prom, Rozetka, Kasta, Епіцентр, сайт — поле номера замовлення або назва угоди; номер
  угоди чи рахунку в описі платежу).
- Один дохід на угоду: нарахування правила каналу, накладений платіж чи оплата вручну — уже дохід, RozetkaPay його не дублює.
- Комісія RozetkaPay з даних платежу — витрата з підставою «угода» (або з виплати, якщо так рахує транзит каналу).
- Повернення покупцям — витрата по угоді; без знайденої оплати — у «Вхідні» на перевірку.
- Останні платежі з угодою й тим, що проведено, — у вкладці «Налаштування» картки; кожен імпорт і вебхук — у журналі подій картки.

## 1. Налаштування
Підключає адміністратор. Дорога: «Інтеграції» (головне меню) → «Оплати» → картка «RozetkaPay».

1. Вкладка «Підключення»: «Логін» → «Ввести» → «Зберегти ключ»; так само «Пароль» (секрет API). Де їх узяти — §2.
2. «Перевірити». Відповідь «ключі прийнято (мерчант: activated)» — готово: картка вмикається сама (якщо її ніхто раніше не
   вимикав), і за 5–30 хвилин перший звіт принесе платежі останніх 3 днів. «RozetkaPay не прийняв ключі» — логін чи пароль не ті.
3. Вкладка «Налаштування» (необов'язково):
   - **Гаманець у «Фінансах»** — порожньо: «Транзит · RozetkaPay (Prom, Rozetka)» (той самий транзит, куди правила каналів Prom і
     Rozetka кладуть продажі, а виплата «ТОВ РОЗЕТКА ПЕЙ» з виписки Monobank знімає гроші переказом). Нема такого — створиться
     транзитний «RozetkaPay: платежі». Транзит — бо оплата покупця через RozetkaPay — це гроші, які RozetkaPay винен вам до виплати.
   - **Категорія доходу** — порожньо: категорія доходу правила каналу на цьому транзиті або «Продаж товарів».
   - **Комісія RozetkaPay з платежу** — §5; **Категорія комісії** — порожньо: «Комісія RozetkaPay».
   - **Проводити повернення покупцям** — §6.
   - **Тягнути платежі зі звіту автоматично**, **Скільки останніх днів звіту перечитувати** (1–14), **Не заносити платежі, старші за дату**.
   - **Приймати вебхуки RozetkaPay** — адреса вебхука у блоці «Стан акаунта» (кнопка копіювання).
   - «Зберегти».

Кілька кабінетів RozetkaPay (різні юрособи) — «+» на картці: у кожного акаунта свої ключі, гаманець, налаштування і журнал.

## 2. Як узяти ключі в кабінеті RozetkaPay
- Кабінет мерчанта — business.rozetkapay.com (заявка, договір, підключення). Логін і пароль API надсилає RozetkaPay листом після
  підключення або показує в кабінеті в розділі інтеграцій / API; якщо їх там нема — попросіть у підтримці RozetkaPay «логін і
  пароль для API Gateway (Basic Auth)».
- Якщо у вас уже є старі ключі RozetkaPay `API_KEY` і `API_SECRET` (плагін сайту, KeyCRM, SalesDrive) — вони підходять: `API_KEY` —
  у «Логін», `API_SECRET` — у «Пароль».
- Пароль — той самий, яким RozetkaPay підписує вебхуки. Змінили пароль у кабінеті — змініть і в картці, інакше вебхуки
  відхилятимуться (§«Можливі помилки»).
- Оплати Пром-оплати й Rozetka (договір з «ТОВ РОЗЕТКА ПЕЙ») видно звітом лише під ключами мерчанта, на якого оформлено
  договір. Якщо звіт порожній, а оплати в кабінеті є — спитайте підтримку, чи бачать ці ключі ваші оплати Prom/Rozetka.

## 3. Звідки приходять платежі
- **Звіт транзакцій API** — кожні 30 хвилин (крок планувальника CRM) за останні 3 дні: успішні оплати (списання, платіж,
  підтвердження двостадійної оплати) і повернення. Звіт RozetkaPay віддає не більше 14 днів за запит і не старше 90 днів —
  CRM ділить період сама. «Підтягнути зараз» у вкладці «Налаштування» — те саме за 3 дні без очікування.
- **Вебхук** — RozetkaPay шле його на `callback_url` платежу. Тому миттєво приходять оплати, створені з адресою CRM (ваш сайт,
  посилання на оплату — вставте туди адресу з картки). Оплати, які створює Prom чи Rozetka, шлють вебхук їм, а не вам — їх
  приносить звіт за 30 хвилин. Холд (кошти лише заблоковано), скасування й невдалі оплати пропускаються.
- Вебхук і звіт про ту саму оплату дають один рядок (ключ — номер замовлення); повторний вебхук нічого не створює.

## 4. Що відбувається з платежем
1. **Угода** — за номером замовлення з платежу: поле номера замовлення каналу в угоді (Prom, Rozetka, Kasta, Епіцентр, ОЛХ,
   сайт), потім назва угоди (угоди маркетплейсів названі номером замовлення), потім номер угоди чи рахунку в описі платежу.
2. **Дохід уже є?** Якщо угоду вже сплачено іншим доходом — правило каналу нарахувало продаж у транзит, прийшов накладений
   платіж, оплату внесли вручну — другого доходу нема. Рядок платежу посилається на той дохід, а в угоді з'являється нотатка
   «Оплачено через RozetkaPay: … Дохід по угоді вже є в журналі (операція №…, правило каналу) — другого не проводимо».
3. **Інакше — дохід по угоді** в гаманець акаунта (типово транзит), категорія «Продаж товарів», дата — час оплати, контрагент —
   платник. «Сплачено» угоди росте; правило каналу, коли угода стане виграною, бачить сплачене й свого доходу не нараховує.
4. **Угода до дати переходу** (на транзиті каналів) — без доходу: такі гроші вже в стартовому рядку «Майданчик винен на 14.10».
5. **Угоду не знайдено** — дохід без угоди у «Вхідних» транзиту з підказкою «вкажіть «Угода (№)» і «Так, усе вірно»».
6. Виплата RozetkaPay на рахунок (з виписки Monobank) — переказ з транзиту за правилом імпорту, не другий дохід.

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

## 6. Повернення
- Повернення оплати, дохід якої провела RozetkaPay-інтеграція, — витрата по угоді («Сплачено» зменшується).
- Дохід угоди нараховувало правило каналу — повернення нічого не проводить: дохід сторнує правило, коли угоду скасують (у
  угоді — нотатка про повернення).
- Оплати серед наших не знайдено — витрата у «Вхідні» на перевірку.
- Вимкнути — «Проводити повернення покупцям витратою по угоді» у «Налаштуваннях».

## 7. Оплата RozetkaPay в угоді й чеку
Тип оплати замовлення Rozetka приходить у поле угоди разом із замовленням ([Rozetka](int-rozetka.md)). Щоб фіскальний чек мав правильну назву безготівкової оплати, у картці Checkbox → «Пов'язані поля» → «Способи оплати» зіставте значення поля угоди з «Своя назва для Безготівки» — «Rozetkapay» ([Checkbox](int-checkbox.md)).

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «RozetkaPay не прийняв ключі (authorization_failed…)» | Логін чи пароль не ті, або ключі не для API Gateway | Перевірте §2; старі `API_KEY`/`API_SECRET` — у «Логін»/«Пароль» |
| «RozetkaPay: забагато запитів (429)» | Ліміт API | Нічого: наступний крок за 30 хв; «Підтягнути зараз» — за хвилину |
| Звіт «транзакцій 0», а оплати в кабінеті є | Ключі іншого мерчанта (проєкту), оплати Prom/Rozetka на іншому договорі | §2, останній пункт |
| У журналі події «вебхук: підпис … не збігся» | Пароль у картці не той, яким підписує RozetkaPay | Впишіть актуальний пароль; подія — не частіше разу на 10 хв |
| Дохід RozetkaPay у «Вхідних» без угоди | Номер замовлення з платежу не збігся з жодною угодою | Вкажіть «Угода (№)» → «Так, усе вірно» |
| Платіж є в рядках, а доходу нема | Угоду вже сплачено (дохід каналу) або угода до дати переходу | Так і має бути — дивіться «Проведено» в таблиці й нотатку в угоді |
| Картка вимкнена, платежі не йдуть | Перемикач «Інтеграція» вимкнено (вручну) | Увімкніть у «Підключенні» |

## Для ШІ-співробітників
ШІ бачить картку RozetkaPay і її журнал через інструменти інтеграцій, але ключів не вводить і не читає (ключі вписує людина). Платежі RozetkaPay у журналі «Фінансів» — з джерелом «RozetkaPay» (`source=rozetkapay`). Статтю ШІ читає інструментом `help("int-rozetkapay")`.

## Додаткова інформація
- Пов'язані статті: [Фінанси](finance.md) (правила каналів, транзит RozetkaPay, «Вхідні»), [Prom](int-prom.md),
  [Rozetka](int-rozetka.md), [Monobank](int-monobank.md) (виплата «РОЗЕТКА ПЕЙ» з виписки), [Checkbox](int-checkbox.md).
- Документація API RozetkaPay: docs.rozetkapay.com (звіти — «Reports API», вебхуки — «Callbacks»).


---

# Telegram

Інтеграція з Telegram підключає акаунти брендів, через які ШІ Люда веде переписки з клієнтами, надсилає вітальні повідомлення й нагадування; розмови видно в «Переписках». Замовлення з Telegram, які оформлює ШІ Едуард, з 15.10.2026 стають угодами в Helomi напряму — через сумісний із KeepinCRM вхід, тож код Едуарда не змінювався.

## Можливості
- Кілька акаунтів Telegram (по одному на бренд) — переписки з клієнтами в «Переписках».
- Перевірка, що для кожного акаунта є сесія на сервері.
- Стан полера «Переписок» у картці.
- Угоди з Telegram-замовлень (ШІ Едуард) напряму в CRM: клієнт за телефоном, позиції за артикулом, доставка й післяплата, дод. поля «Адреса доставки», «Спосіб доставки», «Спосіб Оплати», «Тип оплати checkbox», реквізити клієнта («Код ЄДРПОУ», «Юридична адреса») з витягів, нотатки й файли (накладні OLX, PDF витягів), зміна й видалення угоди командами Едуарда («зміни N», «видали N» — у «Видалену інформацію» на 30 днів).
- Джерело угоди — те, що визначив Едуард (Telegram, ОЛХ, Prom, ДРОПЕРИ…: id джерел KeepinCRM збережено при імпорті); якщо в картці обрано «Джерело угод» — воно головніше. Дроп-замовлення (ДРОПЕРИ) потрапляють на етап «Необроблені» воронки «Дропшипери продаж», як і раніше.
- Кнопка «Відкрити в CRM» під угодою в Telegram веде в картку угоди Helomi.

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Повідомлення» → картка «Telegram» → «Підключення».

1. Рядок «Акаунти (назва:api_id:api_hash, через кому)» → «Ввести» → список акаунтів у форматі `назва:api_id:api_hash`, кілька — через кому → «Зберегти ключ». `api_id` і `api_hash` видає Telegram для застосунку на my.telegram.org.
2. Для кожного акаунта на сервері має бути файл сесії (вхід у Telegram цим акаунтом).
3. «Перевірити» дивиться, чи є сесії на диску: «сесій на диску: N» або «нема сесій: <назви>». У мережу перевірка не ходить, щоб не заважати Люді.
4. «Стан роботи»: «Акаунти», «Сесій на диску», «Полер «Переписок»» (час останнього циклу або помилка).

## 2. Замовлення з Telegram в угоди (ШІ Едуард)
1. Вкладка «Налаштування продажів»: «Основне» («Увімкнути інтеграцію», «Джерело угод», «Відповідальний»), «Нові замовлення» («Автоприйняття», «Зв'язувати товари по»), «Чати», «Автоматична відправка ТТН». «Пов'язаних статусів» нема. «Зберегти».
2. Перемикач «Увімкнути інтеграцію» = приймання угод від Едуарда. Увімкнений — угоди, які створює Едуард, стають угодами Helomi; вимкнений — вхід відповідає Едуарду помилкою «канал Telegram вимкнено», і Едуард показує її в чаті (замовлення не губиться мовчки, менеджер бачить текст). Вибір із картки переживає перезапуск сервера.
3. «Джерело угод» порожнє — джерело береться з того, що визначив Едуард (Telegram / ОЛХ / ДРОПЕРИ…); обране — ставиться всім угодам Едуарда.
4. Зміни Едуарда видно в журналі угоди й клієнта з підписом «Едуард»; нотатки й файли — у блоках «Нотатки» і «Файли».

## 3. Переключити Едуарда або повернути на KeepinCRM

| Що треба | Заявка / команда | Що робить |
| --- | --- | --- |

Після переключення в KeepinCRM для Едуарда вимикати нічого не треба (він писав туди лише через API і більше туди не ходить), але старий ключ API KeepinCRM, зашитий у коді Едуарда, варто відкликати в кабінеті KeepinCRM.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «INBOX_TG_ACCOUNTS порожній» | Акаунти не введено | Введіть рядок «Акаунти» |
| «нема сесій: …» | Для акаунта нема файлу сесії на сервері | Створіть сесію (через розробника) |
| В Telegram від Едуарда: «канал Telegram вимкнено (CRM_INTAKE_TELEGRAM=false) — угоди Едуарда ще йдуть у KeepinCRM» | Перемикач «Увімкнути інтеграцію» вимкнено, а Едуард уже шле сюди | Увімкніть інтеграцію в картці |
| У відповіді входу `ignored_fields` | Едуард надіслав поле з назвою, якого в Helomi нема | Створіть поле з такою назвою в «Налаштуваннях полів» угоди/клієнта або лишіть як є (KeepinCRM теж ігнорувала) |
| «Полер «Переписок»: помилка …» | Збій отримання переписок | Подивіться текст помилки, перевірте сесію |

## Для ШІ-співробітників
5`). Угоди з Telegram ШІ бачить у «Угодах» (`deals_list`, `deals_get`) за джерелом і за дод. полем `telegram_order_id`. Інші ШІ-агенти (Роман, Денис, Олександр), які шлють замовлення Едуарду на його вебхук, автоматично пишуть у Helomi разом із ним. Статтю ШІ читає інструментом `help("int-telegram")`.

## Додаткова інформація
- Пов'язані статті: [Переписки](chats.md), [Угоди](deals.md), [Viber](int-viber.md).


---

# Viber

Інтеграція Viber показує в «Переписках» розмови з клієнтами з Viber, які збирає зовнішній полер. У картці «Інтеграцій» видно, чи працює полер і коли був останній цикл; ключів у самій картці нема.

## Можливості
- Переписки Viber у розділі «Переписки».
- Стан полера в картці: час останнього циклу і помилка, якщо була.
- Відправка повідомлень у Viber з тригерів через сервіси розсилок — дією Webhook (шаблон Viber (TurboSMS), див. [Webhook](int-webhook.md)).

## 1. Налаштування
Дорога: «Налаштування» → «Інтеграції» → вкладка «Повідомлення» → картка «Viber». У «Підключенні» в рядку ключа написано «Не потрібен.»; перемикач «Інтеграція» — лише позначка «працює». Сам полер, що надсилає переписки, налаштовується поза CRM. Картка вважається приєднаною, щойно полер хоч раз звітував.

## 2. Стан каналу
«Підключення» → «Стан роботи» → «Полер «Переписок»»: «останній цикл <час>» або «помилка: …». Безпечної перевірки кнопкою нема — дивіться стан і «Журнал подій».

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| Картка «Не налаштовано» | Полер жодного разу не звітував | Перевірте зовнішній полер |
| «Полер «Переписок»: помилка …» | Збій полера | Подивіться текст помилки |

## Для ШІ-співробітників
5`). Статтю ШІ читає інструментом `help("int-viber")`.

## Додаткова інформація
- Пов'язані статті: [Переписки](chats.md), [Telegram](int-telegram.md), [Webhook](int-webhook.md).


---

# Пошта

Інтеграція «Пошта» підключає скриньки компаній (IMAP/SMTP) до розділу «Пошта» Helomi: листи приходять у програму, їх видно в картці клієнта, і з програми можна відповідати. Картка в «Інтеграціях» показує, скільки скриньок підключено, і вмикає або вимикає синхронізацію.

## Можливості
- Кілька скриньок компаній у розділі «Пошта».
- Синхронізація листів (перемикач у картці).
- Листи клієнта — у картці клієнта і на вкладці «Email» картки угоди.
- Лист у списку «Пошти» відкривається в новій вкладці: Ctrl-клік (на Mac — ⌘), середня кнопка миші або правий клік →
  «Відкрити посилання в новій вкладці» (у кожного листа своя адреса `/mail/<номер>`).

## 1. Налаштування
Підключає адміністратор.
1. Скриньки (адреса, сервери IMAP/SMTP, пароль) додаються в розділі «Пошта».
2. «Налаштування» → «Інтеграції» → вкладка «Повідомлення» → картка «Пошта» → «Підключення» → рядок «Синк пошти (true / false)» → «Ввести» → `true`, щоб синхронізувати, або `false`, щоб зупинити → «Зберегти ключ».
3. «Стан роботи»: «Скриньок у «Пошті»» і «Синк пошти» (увімкнено / вимкнено). Перевірки кнопкою нема.

## 2. Листи в картці клієнта
Листи, адресовані клієнту чи від нього, видно в картці клієнта, а в угоді — на вкладці «Email» праворуч.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| Картка «Не налаштовано» | «Синк пошти» не задано | Введіть `true` у рядок «Синк пошти» |
| «Скриньок у «Пошті»: 0» | Скриньки не додано | Додайте скриньку в розділі «Пошта» |

## Для ШІ-співробітників
5`). Статтю ШІ читає інструментом `help("int-email")`.

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


---

# SMS (TurboSMS)

Інтеграція з TurboSMS надсилає клієнтам SMS — як у KeepinCRM: автоматично, коли угода переходить на вибраний етап (шаблон зі змінними — ТТН, сума, ім'я, посилання на чек), вручну з картки угоди, масово з вибраних угод і з тригера. Підписи відправника, шаблони, баланс, тестова SMS і журнал відправок зі статусом доставки — в одній картці; кабінетів TurboSMS можна підключити кілька, і все налаштовується вручну, без розробника. ШІ-співробітники працюють з тими самими налаштуваннями своїми інструментами.

## Можливості
- Кілька кабінетів TurboSMS (акаунтів): у кожного свій токен, підписи, шаблони, перемикач автовідправки й журнал.
- Підписи відправника (альфа-імена) з перемикачем «Увімкнено»; один — основний. «Підтягнути з TurboSMS» показує імена, зареєстровані в кабінеті.
- Шаблони «етап угоди (+ лише для вибраних джерел) → текст зі змінними»: один раз на угоду або щоразу, коли угода знову приходить на етап; лічильник «Надіслано».
- Змінні групами, як у KeepinCRM: системні, по угоді, по клієнту, по документах (посилання на чек Checkbox), по доставці.
- Ручна відправка з угоди, масова з вибраних угод, з тригера (шаблон, підпис, акаунт, затримка).
- Журнал відправок: дата, клієнт, угода, від кого, текст, статус доставки з TurboSMS («доставлено», «не доставлено»…), який оновлюється сам.
- Тестова SMS і баланс кабінету («кредити»).

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → «Повідомлення» → картка «SMS (TurboSMS)».

1. Вкладка «Підключення» → «API токен» → «Ввести» → «Зберегти ключ». Токен — у кабінеті TurboSMS: «Шлюз (API)» → «Налаштування API» (увімкніть HTTP API). Зберігається зашифрованим і назад не показується.
2. «Перевірити» читає баланс: «баланс: N».
3. «Назва акаунта» — як підписати цей кабінет у перемикачі акаунтів (напр. Semenchenko); порожньо — «Основний».
4. Вкладка «Шаблони SMS» → «Підписи відправника» → «Підтягнути з TurboSMS» або впишіть альфа-ім'я → «Додати підпис» (розділ 2).
5. Там само — «+ Додати SMS шаблон» (розділ 3).
6. Блок «TurboSMS» → «Тестова SMS»: телефон і текст → «Надіслати», щоб перевірити ключ і підпис.
7. Перемикач «Інтеграція» у «Підключенні» = автовідправка за шаблонами цього кабінету. Поки SMS-шаблони працюють у KeepinCRM, лишайте вимкненим — інакше клієнт отримає два SMS. Ручна, масова й тригерна відправка працюють і з вимкненим перемикачем.

Усі зміни на вкладці «Шаблони SMS» зберігаються одразу (як у KeepinCRM); змінювати може лише адміністратор, інші бачать налаштування для читання.

## 2. Підписи відправника
Альфа-ім'я (до 20 символів) має бути зареєстроване у вашому кабінеті TurboSMS — інакше TurboSMS не прийме SMS.

1. «Підтягнути з TurboSMS» показує імена з кабінету зі станом: «активний» — можна додати кліком; «на модерації», «потребує змін», «відхилено» — ще ні.
2. Або впишіть ім'я в поле «новий підпис» → «Додати підпис» (Enter теж додає).
3. Перемикач у рядку: «Увімкнено» / «Вимкнено». Вимкненим підписом SMS не надсилаються (і з угоди, і за шаблонами).
4. «основний» — підпис для шаблонів і ручних SMS без свого підпису; «Зробити основним» — в іншому рядку. Основним може бути лише ввімкнений.
5. Кошик прибирає підпис. Підпис, що стоїть у шаблонах, не прибирається, поки в тих шаблонах не оберете інший.

## 3. Шаблони на етапи угоди (автовідправка)
Таблиця «Шаблони»: «Шаблон», «Етап угоди», «Джерело», «Текст SMS повідомлення», «Надіслано», перемикач, олівець і кошик.

1. «+ Додати SMS шаблон» (або олівець / клік по назві існуючого) — відкривається шторка «SMS шаблон».
2. «Назва» (напр. «Відправлено»), перемикач «Активний» / «Вимкнено».
3. «Етап угоди — коли надсилати»: один або кілька етапів (з усіх воронок). Без етапу шаблон надсилається лише вручну — з угоди, тригером чи масово.
4. «Джерело — лише для вибраних»: окремі шаблони для різних сайтів і маркетплейсів; порожньо — для всіх.
5. «Один раз на угоду» / «Щоразу, коли угода знову приходить на етап».
6. «Підпис відправника»: за замовчуванням (основний) або інший увімкнений.
7. «Текст SMS повідомлення» — до 1000 символів; під полем лічильник «N / 1000 симв. · M SMS» (кирилиця — 70 символів на одну SMS, довші йдуть частинами по 67).
8. Кнопки «Системні змінні», «Змінні по угоді», «Змінні по клієнту», «Змінні по документах», «Змінні по доставці» відкривають список змінних — клік вставляє змінну туди, де курсор (розділ 4).
9. «Перевірити на угоді»: впишіть № угоди — побачите, який текст і на який телефон піде, і чи є невідомі змінні.
10. «Зберегти».

Коли угода переходить на етап шаблону і кабінет увімкнено перемикачем, клієнт отримує SMS. Телефон — отримувача з останньої доставки, інакше основний телефон клієнта. Кожна SMS пишеться в журнал угоди («SMS «Відправлено» на 380…: текст»).

## 4. Змінні в тексті
Запис — як у KeepinCRM: `{{.група.поле}}`. Невідома змінна стає порожньою, у перевірці — попередження.

| Група | Змінні |
| --- | --- |
| Системні | `{{.now.date}}` — сьогодні, `{{.now.time}}` — зараз (Київ) |
| По угоді | `{{.agreement.id}}`, `{{.agreement.title}}` (№ замовлення), `{{.agreement.total}}`, `{{.agreement.paid}}`, `{{.agreement.credit}}` (до сплати), `{{.agreement.stage}}`, `{{.agreement.source}}`, `{{.agreement.responsible}}`, `{{.agreement.created_at}}`, `{{.agreement.items}}` (товари: назва × кількість) |
| По клієнту | `{{.client.name}}` (ПІБ або назва), `{{.client.person}}`, `{{.client.company}}`, `{{.client.phone}}`, `{{.client.email}}` |
| По документах | `{{.agreement.last_checkbox_receipt_url}}` — посилання на останній чек Checkbox угоди, `{{.agreement.last_checkbox_fiscal_code}}` — його фіскальний номер |
| По доставці | `{{.agreement.delivery_ttns}}` (усі ТТН), `{{.last_delivery.ttn}}`, `{{.last_delivery.service}}`, `{{.last_delivery.address}}`, `{{.last_delivery.recipient}}`, `{{.last_delivery.cod}}` (накладений платіж), `{{.last_delivery.cost}}`, `{{.last_delivery.status}}` |

Приклад: «Вітаємо {{.client.person}}, ваша ТТН: {{.last_delivery.ttn}}. Дякуємо!» → «Вітаємо Іван Тестовий, ваша ТТН: 20450000000001. Дякуємо!».

## 5. Надіслати SMS з угоди вручну
Картка угоди → «⋮» → «Надіслати SMS» → шторка: «Акаунт TurboSMS» (коли кабінетів з токеном кілька), «Шаблон» або «Текст (змінні угоди підставляться)», перегляд «Клієнт отримає…», «Інший телефон (необов'язково)», «Підпис» (коли ввімкнених кілька) → «Надіслати».

## 6. SMS клієнтам вибраних угод
У списку угод позначте угоди → панель «Вибрано: N» → «SMS» → шторка: «Акаунт TurboSMS» (коли кілька), «Шаблон» або свій текст зі змінними (кнопки над полем; старі `{client.name}`, `{deal.title}`, `{deal.total}` теж працюють) → «Надіслати» → підтвердження. Текст іде на основний телефон клієнта кожної угоди підписом за замовчуванням; угоди без клієнта чи телефону — у списку помилок. Кожна SMS — у журналі SMS і журналі угоди. Кнопка «SMS» сіра з підказкою, поки не задано токен або підпис.

## 7. SMS з тригера (складні умови й затримка)
Прості умови (етап, джерело) — шаблоном (розділ 3). Складніші — «Налаштування» → «Автоматизація» → «Тригери» → дія «Відправити SMS»: «Акаунт TurboSMS» (коли кілька), «SMS-шаблон» (або «— свій текст —» і текст зі змінними тригера `{{title}}`), «Підпис відправника», «Телефон» (порожньо — з доставки чи клієнта угоди); умова й затримка — у тригері (напр. «Прибув у відділення» + 4320 хв = нагадування через 3 дні). Як писати умови — [Тригери](settings-triggers.md).

## 8. Журнал відправок, статуси доставки й баланс
«Шаблони SMS» → «Журнал відправок»: «Дата», «Клієнт» і «Угода» (клік відкриває картку), «Від» (підпис; під ним — шаблон або «вручну · хто»), «Повідомлення», «Статус». Статус доставки береться з TurboSMS: «у черзі», «надіслано оператору», «доставлено», «прочитано», «не доставлено», «відхилено», «термін минув», «скасовано, кошти повернуто»; «не надіслано: …» — TurboSMS відмовив одразу (причина поруч).

- «Статуси доставки» → «Перевіряти автоматично»: сервер сам питає TurboSMS кожні 5 хвилин про SMS за останні 3 доби, доки статус не стане кінцевим. Вимкнено — «Лише кнопкою «Оновити статуси»».
- «Оновити статуси» — перевірити зараз.
- «Показати ще» — старіші записи.
- Баланс — блок «TurboSMS» → «Баланс» (кредити), кружечок поруч оновлює.

## 9. Кілька кабінетів TurboSMS
«+» унизу праворуч картки → назва і токен → новий кабінет у перемикачі під шапкою (поруч з основним). У кожного кабінету — своя вкладка «Підключення» (токен, перемикач автовідправки, «Перевірити», журнал подій) і «Шаблони SMS» (свої підписи, шаблони, журнал відправок). Автовідправка йде з кожного ввімкненого кабінету за його шаблонами. Вручну, масово й тригером — з вибраного кабінету (типово — основного).

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Не задано TURBOSMS_TOKEN — введіть токен TurboSMS у картці інтеграції «SMS»» | Токен не введено (для додаткового кабінету — «… акаунта «назва»») | «Підключення» → «API токен» |
| «Ключ TurboSMS не задано — «Інтеграції → SMS (TurboSMS) → Підключення».» | Те саме, у шторці угоди | Введіть токен |
| «Не задано підпис відправника — додайте його в «Підписи відправника»» | Немає жодного ввімкненого підпису | Додайте альфа-ім'я |
| «Підпис «…» вимкнено в «Підписах відправника»» | Підпис вимкнено перемикачем | Увімкніть або оберіть інший |
| «Підпис «…» не додано в «Підписи відправника» цього акаунта» | Підпис з іншого кабінету чи вписаний вручну | Додайте його в цей кабінет |
| «Шаблон «…»: підпис «…» не додано в «Підписи відправника»» | Шаблон посилається на прибраний підпис | Оберіть у шаблоні інший |
| «Підпис «…» стоїть у шаблонах … — спершу оберіть там інший» | Прибираєте підпис, який використовують шаблони | Змініть підпис у шаблонах |
| «Нема телефону для SMS (у доставці чи клієнта угоди)» | В угоді нема телефону | Додайте телефон клієнту чи в доставку |
| «Невірний телефон «…» — потрібен український номер, напр. 0671234567» | Неправильний номер у полі «Інший телефон» | Виправте номер |
| «Шаблон не знайдено в цьому акаунті SMS» | Шаблон з іншого кабінету або видалений | Оберіть шаблон цього кабінету |
| «Текст довший за 1000 символів» / «Шаблон «…»: порожній текст» | Задовгий або порожній текст | Скоротіть / впишіть текст |
| «TurboSMS не прийняв SMS: REQUIRED_BALANCE» (або інший код) | Відмова TurboSMS: баланс, стоп-лист, дубль за 90 с | Поповніть баланс / перевірте номер |
| Статус «не доставлено» | Оператор не доставив (телефон вимкнено, номер неіснуючий) | Перевірте номер клієнта |

## Для ШІ-співробітників
Розділ у каталозі — `describe_section("sms")`, картка `/api/ai/sections/sms` (поля: акаунт, підписи, шаблони, змінні; приклади викликів). Читати можна з доступом «Угоди» або «Інтеграції».

- `sms_state` — налаштування кабінету: акаунти, підписи, шаблони з етапами й джерелами, лічильники, змінні за групами, воронки з етапами, джерела (`account` — інший кабінет).
- `sms_preview` — текст зі змінними угоди і телефон, без відправки.
- `sms_send` — надіслати SMS клієнту угоди шаблоном або своїм текстом (доступ «Угоди»). Це «відправка назовні»: типово чекає «Підтвердити» людини («Доступи → Спочатку запитати → Відправка назовні»); передавайте `idempotency_key` — повтор не надішле вдруге.
- `sms_messages` — журнал: що й коли надсилали, статус доставки; `sms_refresh_statuses` — оновити статуси з TurboSMS.
- `sms_balance`, `sms_senders_remote` — баланс і зареєстровані імена кабінету (доступ «Інтеграції»).
- `sms_settings_save` — змінити підписи й шаблони (налаштування цілком, як у `sms_state.settings`). Лише з доступом «Налаштування інтеграцій», який видає адміністратор у «Доступах» пульта ШІ, і завжди після «Підтвердити» адміністратора: картка показує, які підписи й шаблони додано, прибрано чи змінено. У журналі — «ШІ <ім'я> · підтвердив <адміністратор>».
- Токен TurboSMS ШІ не вводить і не бачить; перемикач автовідправки вмикає людина.
- Не вигадуйте id шаблонів і етапів — беріть з `sms_state`; не надсилайте вільний текст замість шаблону без потреби.

Статтю ШІ читає інструментом `help("int-sms")`.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [Налаштування: тригери](settings-triggers.md), [Інтеграції](integrations.md), [Checkbox](int-checkbox.md), [ШІ-співробітники](ai-employees.md), [BlackBox](int-blackbox.md).


---

# BlackBox

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

## Можливості
- Автоперевірка кожної угоди (з сайтів, Prom, Rozetka, Епіцентру, OLX, вручну) за телефоном: нова — одразу, а пропущені (телефон додали пізніше, BlackBox не відповів) — фоном протягом 5 хвилин.
- Вікно «за останні N днів» — щоб старі угоди з імпорту не витратили денний ліміт.
- Смуга в угоді: «покупця в базі нема», «покупця знайдено в базі несумлінних» з деталями, «перевірка в черзі», «не вдалося перевірити» з причиною, «у угоді нема телефону».
- «Перевірити ще раз» у смузі та в «⋮» угоди — навіть коли автоперевірку вимкнено.
- Стан угод у налаштуваннях: скільки перевірено, знайдено, чекає, без телефону.
- «Додати в BlackBox» з угоди: ТТН і телефон з доставки, коментар обов'язковий.
- Історія перевірок і залишок запитів на сьогодні.

## 1. Налаштування
Підключає адміністратор. Дорога: «Налаштування» → «Інтеграції» → вкладка «Повідомлення» → картка «BlackBox».

1. «Підключення» → «API ключ» → «Ввести» → «Зберегти ключ». Ключ — у вашому кабінеті BlackBox. Зберігається зашифрованим. Перевірки кнопкою нема: запити платні, тож дивіться стан ключа й журнал.
2. Вкладка «Перевірки» → «Перевірка покупців» → «Автоматична перевірка»: «Увімкнено» / «Вимкнено». Перемикач показує, чи перевірка справді працює. Увімкнули його — вмикається й перемикач «Інтеграція» у вкладці «Підключення» (це той самий головний вимикач; вимкнули «Інтеграцію» — автоперевірка зупиняється). Підказка під перемикачем каже, чого бракує: «Спершу введіть API ключ BlackBox у вкладці «Підключення».», «Інтеграцію вимкнено у вкладці «Підключення». Увімкніть перемикач тут — запрацює й картка.» або «Працює.».
3. «Які угоди» → «за останні … дн.» → «Зберегти». Типово 7 днів, можна від 1 до 90. Перевіряються відкриті угоди (не в архіві, без «Виграно»/«Програно»), оформлені за ці дні.
4. «Стан угод» — за вікном: «перевірено X з Y», «знайдено в базі», «чекають перевірки», «не вдалося», «без телефону».
5. «Залишок запитів» — на сьогодні, за останньою відповіддю BlackBox.

## 2. Автоматична перевірка кожної угоди
Коли «Автоматична перевірка» увімкнена:
- нова угода перевіряється одразу у фоні (за кілька секунд після створення);
- кожні 5 хвилин CRM дочищає решту: відкриті угоди з вікна «за останні N днів», які ще не перевірено, — наприклад, телефон додали пізніше або BlackBox тоді не відповів. За раз — до 20 угод, найновіші першими;
- якщо перевірка не вдалася, причина записується в угоду, а повтор буде не раніше ніж за годину. Коли денний ліміт BlackBox вичерпано, дочищення чекає наступної доби.

Номер береться з доставки угоди (отримувач), інакше — головний телефон клієнта. Перевірка йде через збережений результат (14 днів): той самий номер не витрачає запит удруге.

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

## 3. Перевірити вручну з угоди
Смуга BlackBox під етапами в картці угоди:
| Смуга | Що означає | Кнопка |
| --- | --- | --- |
| «BlackBox: покупця в базі нема» (зелена) | Перевірено, у базі нема | «Перевірити ще раз» |
| «BlackBox: покупця знайдено в базі несумлінних» (червона) | Знайдено; «Детальніше» / «Сховати» — інциденти | «Перевірити ще раз» |
| «BlackBox: перевірка в черзі» | Автоперевірка візьме угоду сама протягом кількох хвилин; смуга оновиться без перезавантаження | «Перевірити зараз» |
| «BlackBox: не вдалося перевірити» | Причина й час останньої спроби; повтор автоматично | «Перевірити ще раз» |
| «BlackBox: ще не перевірено» | Автоперевірку вимкнено або угода поза вікном днів | «Перевірити» |
| «BlackBox: у угоді нема телефону — перевірити не можна» | Нема номера ні в доставці, ні в клієнта | — |

Те саме — «⋮» → «Перевірити в BlackBox». Ручна перевірка йде повз збережений результат і витрачає запит.

## 4. Додати покупця в BlackBox
1. Картка угоди → «⋮» → «Додати в BlackBox».
2. Шторка «Додати в BlackBox»: номер ТТН і телефон беруться з доставки угоди; «Що сталося (обов'язково)» — опис, його бачать інші продавці.
3. «Додати в базу».

Масово додати не можна — коментар потрібен до кожного покупця.

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

## Для ШІ-співробітників
- `deals_blackbox(deal_id)` — результат угоди: `checked`, `checked_at`, `found`, `detail`, `phone`, `queued` (перевіриться сама), `error` і `tried_at` (чому не вдалася автоперевірка).
- `deals_blackbox_check(deal_id)` — «Перевірити ще раз» (повз збережений результат, витрачає запит денного ліміту); результат і підпис ШІ — у смузі й журналі угоди.
- Те саме видно в додаткових полях угоди (`blackbox_*`) через `deals_get`: ШІ може попередити людину перед відправкою з накладним платежем.
- Налаштування автоперевірки (`/api/crm/blackbox/settings`) змінює лише адміністратор — інструментів для них у ШІ нема.

Статтю ШІ читає інструментом `help("int-blackbox")`.

## Додаткова інформація
- Пов'язані статті: [Угоди](deals.md), [SMS (TurboSMS)](int-sms.md).


---

# Ключі моделей (Anthropic, OpenAI, Kimi, Gemini)

Вкладка «ШІ» в «Інтеграціях» — місце, де організація підключає своїх ШІ-співробітників і ключі мовних моделей: Anthropic (Claude), OpenAI (ChatGPT), Moonshot (Kimi), Google (Gemini). Платформа своїх ключів не позичає: запити йдуть вашим ключем і за ваш рахунок, а використання видно в пульті кожного ШІ. Без ключа API теж можна працювати — підключити свій чат за підпискою через файл сесії.

## Можливості
- Картка кожного ШІ-співробітника організації: стан, вид («Мозок», «Програма», «Агент»), модель, хто підключив; три дії — «Увімкнено», «Відкрити», «WIKI».
- Шаблони каталогу, яких ще нема в організації (напр. «Ломі», якщо її прибрали), — «Додати» і «WIKI».
- «Остап — ваш Claude, ChatGPT, Kimi чи Gemini у CRM» — підключити свій ШІ за файлом сесії чи токеном («Підключити» і «WIKI»).
- Чотири картки ключів моделей; ключ зберігається зашифрованим і назад не віддається.
- «Перевірити» показує список доступних моделей — без запиту до самої моделі й без витрат.
- «Підключити свій чат — без ключа API»: ключ сесії і файл для Claude, ChatGPT, Kimi чи Gemini.

## 1. Налаштування
Дорога: «Налаштування» → «Інтеграції» → вкладка «ШІ». Угорі — блок «ШІ-співробітники · N», нижче — «Ключі моделей · N/4» з картками «Anthropic (Claude)», «OpenAI (ChatGPT)», «Moonshot (Kimi)», «Google (Gemini)». У вкладці «Усі» ті самі блоки йдуть у групі «ШІ».

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

Де взяти ключ: у консолі розробника відповідного сервісу (Anthropic Console, OpenAI Platform, Moonshot, Google AI Studio) — розділ ключів API. Для Claude за підпискою Max чи Team ключ можна отримати з кредитами API — розділ 5.

## 2. Блок «ШІ-співробітники»
- **Картка співробітника**: аватар в ореолі, ім'я, роль, пігулки стану й виду, модель (або «модель — ваш ШІ (Claude, ChatGPT, Kimi…)» для зовнішнього), «підключив …». Дій рівно три: перемикач «Увімкнено» (вимкнений ШІ не робить нічого), «Відкрити» (вікно ШІ: програма чи агент на весь екран, Ломі — її віконце, Остап і свій ШІ — налаштування на вкладці «API») і «WIKI» (стаття ШІ шторкою). Налаштування й підключення — у вікні, кружечок «Налаштування» праворуч угорі.
- **Шаблон каталогу** з пігулкою «не додано» → «Додати» → та сама шторка, що в «Налаштування → Команда → ШІ-співробітники», з вибраним шаблоном. Після додавання відкриваються налаштування на вкладці «API»; «WIKI» — стаття шаблону.
- **«Остап — ваш Claude, ChatGPT, Kimi чи Gemini у CRM»** → «Підключити» → шторка «Остап — свій ШІ», далі — налаштування Остапа на вкладці «API» з чорною «Створити ключ і завантажити файл».

Докладно про картку, вікно, налаштування, доступи, «спочатку запитати» й ліміти — [ШІ-співробітники](ai-employees.md); про підключення свого чату — [Остап](ai-ostap.md); про Ломі — [Ломі](kamila.md).

## 3. Ввести й перевірити ключ моделі
1. Відкрийте картку моделі, напр. «Anthropic (Claude)» → «Підключення».
2. Рядок ключа (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `MOONSHOT_API_KEY` або `GOOGLE_AI_KEY`) → «Ввести» → вставте ключ («показати» — побачити, що вставили) → «Зберегти ключ».
3. Ключ зберігається зашифрованим; далі показується лише «задано (••••1234)». Повністю він більше ніде не з'являється й назад через API не віддається. «Змінити» — замінити, «Прибрати» — стерти з CRM.
4. «Перевірити» → «Зв'язок є: моделей: N (перші назви…)». Це лише список моделей, запиту до моделі й витрат нема.
5. У налаштуваннях ШІ-співробітника, вкладка «API» → «Модель», оберіть провайдера й модель — співробітник почне ходити цим ключем.

Перемикач «Інтеграція» на картці моделі — лише позначка; працює ключ. Ключ не вставляйте в чат і не пересилайте — лише в картку.

## 4. Підключити свій чат — без ключа API
На кожній із чотирьох карток є блок «Підключити свій чат — без ключа API»: ваша підписка Claude, ChatGPT, Kimi чи Gemini керує Helomi через чат.
1. «Ключ і файл» → «Створити ключ і завантажити файл».
2. З'явиться ШІ-співробітник «<Провайдер> · сесія» (напр. «Claude · сесія») зі своїми доступами, і завантажиться файл:
   - Claude — пакет навички (.zip): у Claude «Налаштування → Можливості → Навички → Завантажити», або в теку сесії Claude Code / Cowork;
   - ChatGPT — файл-інструкція (.md): прикріпіть у чат або в інструкції свого GPT;
   - Kimi — файл-інструкція (.md) у чат Kimi;
   - Gemini — файл-інструкція (.md) у чат або в Gem.
3. Пишіть у чат: «покажи прострочені угоди», «створи задачу», «зроби розділ Ремонти».

Під кнопкою — «Файл «…» завантажено (ключ …)» і посилання на співробітника: там його «Доступи й ліміти» (вкладка «Налаштування»), а ключ відкликається на вкладці «API». Ключ сесії діє як пароль — не пересилайте файл стороннім.

## 5. Кредити API для підписок Claude Max і Team
Власники підписок Claude отримують кредити API додатково до ліміту підписки: Max 5x — 100 $ на місяць, Max 20x — 200 $ на місяць, Team — до 500 $. Кредити діють лише на API і згоряють у кінці циклу підписки.

Як забрати:
1. claude.ai → Settings → Billing → «API credits».
2. Прив'яжіть організацію Claude Console (потрібно бути на плані 7 днів; прив'язка одна).
3. Кредити видно в Console → Settings → Billing → Promotional credits.
4. Там же, у Console, створіть ключ API і вставте його в картку «Anthropic (Claude)» (розділ 3).

Джерело: https://platform.claude.com/docs/en/about-claude/api-credits-for-subscribers

## Платформні ключі для Ломі
Адміністратор платформи може задати в консолі платформи → «Ломі» один ключ Google (голос) і один ключ Anthropic (мозок) для всіх компаній одразу, з перемикачами «ділитися». Компанія зі своїм ключем у цій картці завжди бере свій; без свого — платформний, якщо ділення дозволено. Платформний ключ Google працює лише для голосу Ломі, платформний ключ Anthropic — лише для її мозку; інші ШІ-співробітники компанії платформних ключів не бачать.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): ANTHROPIC_API_KEY» | «Перевірити» без ключа | Введіть ключ |
| «Помилка: LlmError: Ключ не прийнято» | Ключ недійсний або відкликаний | Створіть новий ключ у консолі сервісу |
| «Немає ключа моделі: додайте його в «Інтеграції → ШІ → …»» | ШІ-співробітник обрав провайдера без ключа | Введіть ключ у відповідну картку |
| «Для цього ШІ не обрано модель з ключем — оберіть провайдера у вкладці «Підключення»» | У налаштуваннях ШІ не вибрано провайдера | Налаштування ШІ → «API» → «Модель» → провайдер і модель |
| «На сервері не встановлено бібліотеку anthropic» | Проблема сервера | Зверніться до підтримки Helomi |
| Кнопки «Додати», «Підключити» сірі | Ви не адміністратор | Попросіть адміністратора |

## Для ШІ-співробітників
5`). ШІ-співробітник не просить вставити ключ у чат — лише в картку «Інтеграції → ШІ». Свій стан і витрати ШІ бачить у пульті. Статтю ШІ читає інструментом `help("int-ai-keys")`.

## Додаткова інформація
- Пов'язані статті: [ШІ-співробітники](ai-employees.md), [Остап — ваш Claude, ChatGPT, Kimi чи Gemini у CRM](ai-ostap.md), [Ломі](kamila.md).


---

# KeepinCRM (перехід)

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

## Можливості
- Перевірка ключа KeepinCRM.
- Дзеркало кожні 5 хвилин: лише нове й змінене, повтор не дублює.
- Ручний імпорт з дати — «Налаштування → Система → Імпорт із KeepinCRM».
- Показ «бекенду CRM для ШІ» — куди зараз ходять ШІ-агенти.

## 1. Налаштування
Дорога: «Налаштування» → «Інтеграції» → вкладка «Інше» → картка «KeepinCRM» → «Підключення».

1. «API ключ» → «Ввести» → «Зберегти ключ». Ключ — у налаштуваннях вашого акаунта KeepinCRM. Зберігається зашифрованим.
2. «Перевірити» → «користувачів у CRM: N».
3. «Стан роботи» → «Бекенд CRM для ШІ»: `keepin` (ШІ-агенти працюють з KeepinCRM), `both` або `local`. Те саме видно в шапці каталогу «Інтеграцій». Змінює його розробник на сервері.

## 2. Дзеркало KeepinCRM
Дзеркало працює саме: кожні 5 хвилин бере з KeepinCRM записи, змінені з попереднього прогону (із запасом 10 хвилин), і оновлює їх у Helomi. Нові угоди з'являються з подією «створено» від «дзеркало KeepinCRM». Час останньої синхронізації — у картці (стан і «Журнал подій»: записи лише тоді, коли щось змінилося або сталася помилка). Щодня до повного переходу варто дивитися, що остання синхронізація не старша за 10 хвилин.

Тригери Webhook на записи з дзеркала не спрацьовують — у KeepinCRM спрацювали свої.

**Що саме тягнути — вирішуєте ви.** У картці KeepinCRM блок «Дзеркало KeepinCRM»: головний перемикач «Дзеркало» (без вибору — як у `.env`) і перемикачі «Клієнти», «Угоди (з доставками й платежами)», «Товари складу», «Завдання». Вимкнена сутність більше не оновлюється з KeepinCRM — записи в Helomi стають основними. Зміна діє на наступному колі дзеркала (до 5 хвилин), без перезапуску; хто і коли змінив — у «Журналі подій» картки. З 14.10 (перехід на свою CRM) увімкнено лише «Клієнти»: угоди, завдання й товари складу живуть у Helomi, а замовлення з маркетплейсів і сайтів приходять напряму (див. розділ 4). Міняти може лише адміністратор.

## 3. Імпорт із KeepinCRM
«Налаштування → Система → Імпорт із KeepinCRM»: «Лише записи, оновлені з дати» → «Запустити». Імпорт іде у фоні: «Імпорт запущено у фоні — журнал оновиться». Таблиця прогонів: «Початок», «Кінець», «Джерело», «З дати», «Стан», «Лічильники».

## 4. Перемикання каналів
Канал продажів (Prom, Rozetka, Kasta, Епіцентр, сайти…) перемикається на Helomi у своїй картці перемикачем або кнопкою «Підключити … одним натиском». **Того ж дня** вимкніть цей канал у KeepinCRM — інакше замовлення прийде двічі: напряму і дзеркалом. Наступного дня звірте кількість угод каналу за добу з кабінетом маркетплейсу.

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «не задано (у картці чи .env): KEEPINCRM_API_KEY» | Ключ не введено | Введіть «API ключ» |
| «HTTP 401» після «Перевірити» | Ключ KeepinCRM недійсний | Створіть новий ключ у KeepinCRM |
| Синхронізація старша за 10 хвилин | Дзеркало зупинилося або KeepinCRM недоступна | Подивіться «Журнал подій» картки |
| Угода прийшла двічі | Канал увімкнено і тут, і в KeepinCRM | Вимкніть канал у KeepinCRM |
| Угода з KeepinCRM не з'явилась у Helomi | У «Дзеркалі KeepinCRM» вимкнено «Угоди» (так і задумано з 14.10) | Замовлення приходять напряму з каналу; якщо треба — увімкніть «Угоди» |
| «Невідома сутність дзеркала» | У запиті PUT /api/crm/mirror/settings чужий ключ | Ключі: clients, agreements, materials, tasks |

## Для ШІ-співробітників
5`). Записи з дзеркала — звичайні угоди, клієнти й товари, ШІ працює з ними своїми інструментами. Статтю ШІ читає інструментом `help("int-keepincrm")`.

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


---

# Вчасно

«Вчасно» — сервіс електронного документообігу: підписання й обмін документами з контрагентами онлайн. Інтеграцію з ним заплановано, щоб документи Helomi потрапляли в електронний документообіг без ручного перенесення.

Зараз у «Інтеграціях» → вкладка «Інше» є лише картка «Вчасно» з позначкою «Пізніше»: ключів, налаштувань і перевірки в ній нема, і з документами вона поки не працює. Документи формуються й друкуються в Helomi як завжди, розділ «Документи» від «Вчасно» не залежить.

Коли інтеграцію буде зроблено, ця стаття отримає повну будову: підключення акаунта, відправку документа з угоди, статуси підписання, можливі помилки й розділ для ШІ-співробітників. 5`). Пов'язані статті: [Документи](documents.md).