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

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

Розділ «Інтеграції» з'єднує 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).