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

# Ключі API та вебхуки

Щоб сайт, сервіс автоматизації (Zapier, Make, n8n), облікова програма чи ваш власний код працювали з Helomi, підключіть їх як «Зовнішню програму»: у неї свій ключ API, свої права й свій підпис у журналі. Спільного ключа на всю компанію в Helomi немає навмисно — так кожну інтеграцію видно окремо і кожну можна відкликати, не зачепивши решту. Якщо сервіс уміє лише надсилати заявки на адресу, замість ключа візьміть вхідний вебхук.

## Можливості
- «Зовнішня програма» на кожну інтеграцію: «Сайт магазину», «Zapier», «1С» — кожна зі своїм ключем.
- Кілька ключів на одну програму (наприклад, робочий і запасний), кожен відкликається окремо й миттєво.
- Ті самі дії, що й у людини: знайти, створити й змінити угоду, клієнта, задачу, товар — з перевіркою обов'язкових полів, воронок і доступів.
- Права програми — лише розділи, які ви відкрили в «Доступах і лімітах»; гроші, видалення й масові дії можна поставити на «Спочатку запитати».
- Ліміт викликів на хвилину й на добу, щоб помилка в чужому коді не завалила CRM.
- Кожна дія підписана іменем програми в журналі угод і клієнтів.
- Три способи підключення: REST (звичайні запити з JSON), MCP (для клієнтів ШІ) і опис OpenAPI (імпорт у GPT Actions, Postman, генератори коду).
- Вхідні вебхуки — для сервісів, які лише надсилають заявку чи замовлення на адресу і не вміють ставити ключ.

## 1. Налаштування
Ключі API та вебхуки створює адміністратор компанії.

Усе зібрано на одній картці: «Налаштування → Загальні параметри → Ключі API та вебхуки». Там видно всі програми з ключем, скільки в кожної живих токенів і коли ними користувались востаннє. Ту саму програму можна додати й з «Налаштування → Інтеграції → ШІ» карткою «Зовнішня програма» → «Додати».

> [!NOTE]
> Ключі моделей ШІ (Anthropic, OpenAI, Google) — це інше: ними Helomi сам звертається до моделей. Про них — стаття [Ключі моделей](int-ai-keys.md).

## 2. Створити ключ API для своєї програми
Ключ API — це токен, з яким ваша програма звертається до Helomi. Його видає «Зовнішня програма», а не компанія в цілому.

1. Відкрийте «Налаштування → Загальні параметри» і в картці «Ключі API та вебхуки» натисніть «Нова програма».
2. Впишіть «Ім'я в CRM» за тим, що підключаєте: «Сайт магазину», «Zapier», «1С».
3. Прочитайте «Відповідальність», поставте галочку «Розумію» і натисніть «Підключити».
4. Відкриється вкладка «API» нової програми. Впишіть назву токена (наприклад, «Робочий сервер») і натисніть «Новий токен».
5. Скопіюйте токен одразу кнопкою «Скопіювати»: він показується один раз. У таблиці «Токени» далі видно лише його початок.
6. Вставте токен у свою програму чи сервіс. Нижче, у блоці «Адреси й інструкція», скопіюйте адресу REST, MCP або OpenAPI.

> [!WARNING]
> Токен — як пароль від CRM з правами цієї програми. Не надсилайте його в чати й листи і не кладіть у відкритий код сайту.

## 3. Дати програмі потрібні права
Нова програма бачить лише основні розділи: угоди, клієнтів, задачі й склад. Розширте чи звузьте їх під свою інтеграцію.

1. Відкрийте програму: «Налаштування → Загальні параметри → Ключі API та вебхуки» → рядок програми.
2. Перейдіть на вкладку «Налаштування» і розгорніть «Доступи й ліміти» внизу.
3. Поставте галочки лише тих розділів, з якими програма працює. Сайту, що створює замовлення, досить «Угоди», «Клієнти» і «Склад».
4. У «Спочатку запитати» залиште увімкненими гроші й видалення, якщо програма не повинна робити це сама.
5. За потреби змініть ліміт викликів на хвилину й на добу. Типово — 60 на хвилину і 5000 на добу.
6. Натисніть «Зберегти доступи». Нові права діють з наступного запиту програми, токен міняти не треба.

## 4. Звернутися до Helomi з програми
Кожна дія Helomi — інструмент з назвою й описом полів. Програма викликає інструмент запитом з JSON-аргументами і токеном у заголовку.

1. Отримайте перелік інструментів і їхніх полів: запит `GET <адреса сайту>/api/ai/tools` з заголовком `Authorization: Bearer <токен>`.
3. Для сервісів, які читають опис API, дайте адресу `<адреса сайту>/api/ai/openapi.json`: у ній лише інструменти, відкриті цьому токену.
4. Для клієнтів ШІ (Claude Code, Cursor, Kimi) додайте сервер MCP за адресою `<адреса сайту>/mcp` з тим самим заголовком.

> [!TIP]
> Точні адреси вашої компанії з кнопками «Скопіювати» — на вкладці «API» програми, у блоці «Адреси й інструкція» → «Своя програма».

## 5. Приймати заявки з сайту без ключа — вхідний вебхук
Вхідний вебхук — адреса, на яку сайт чи форма надсилає заявку, а Helomi сам створює з неї клієнта, угоду й задачу. Ключ API тут не потрібен: захист — у самій адресі.

1. Відкрийте «Налаштування → Загальні параметри → Ключі API та вебхуки» і натисніть «Вхідні вебхуки».
2. Натисніть «+ Новий вебхук» і виберіть шаблон сервісу (WooCommerce, Contact Form 7, Weblium, WIX) або «Webhook без налаштувань».
3. Скопіюйте «URL вебхука» і вставте його в налаштуваннях сервісу.
4. Перевірте мапінг полів і натисніть «Зберегти».

Докладно про мапінг і «Історію запитів» — у статті [Вебхуки](settings-webhooks.md).

## 6. Відкликати ключ або вимкнути програму
Відкликайте токен, якщо він міг потрапити до чужих людей або програму більше не використовують.

1. Відкрийте програму з картки «Ключі API та вебхуки» — одразу відкриється вкладка «API».
2. У таблиці «Токени» натисніть «Відкликати» біля потрібного токена і підтвердіть. Програма з ним втрачає доступ миттєво.
3. Щоб тимчасово зупинити всі токени програми, вимкніть її перемикачем «Увімкнено» в «Налаштування → Інтеграції → ШІ».

> [!CAUTION]
> Відкликаний токен не повернути. Спершу створіть новий токен і підставте його в програму, а потім відкликайте старий.

## Можливі помилки
| Що бачить програма | Чому | Що зробити |
| --- | --- | --- |
| «Потрібен токен ШІ: Authorization: Bearer sgai_…» | Запит прийшов без заголовка з токеном | Додайте заголовок `Authorization: Bearer <токен>` |
| «Токен ШІ недійсний або відкликаний» | Токен відкликано, програму видалено або токен вставлено з помилкою | Створіть новий токен на вкладці «API» |
| «ШІ-співробітника «…» вимкнено» | Програму вимкнено перемикачем «Увімкнено» | Увімкніть її в «Налаштування → Інтеграції → ШІ» |
| «Забагато запитів: ліміт … на хвилину» | Програма перевищила ліміт викликів | Зачекайте вказані секунди або підніміть ліміт у «Доступах і лімітах» |
| «Інструмент «…» недоступний: розділ закрито у «Доступах» цього ШІ» | Інструмент належить розділу, якого програмі не відкрили | Поставте галочку розділу в «Доступах і лімітах» |
| Дія повернула `pending_id` | Дія стоїть на «Спочатку запитати» | Підтвердіть її в Helomi або вимкніть «Спочатку запитати» для цього виду дій |

## Для ШІ-співробітників
- Ключ API належить конкретній «Зовнішній програмі»; спільного ключа компанії немає. Людині, яка питає «де ключ API», порадьте «Налаштування → Загальні параметри → Ключі API та вебхуки → Нова програма».
- Створити програму чи токен ШІ не може: токени видає лише людина-адміністратор на вкладці «API».
- Токени, їхні початки й адреси вебхуків нікому не показуйте і не вставляйте у відповіді.
- Для сервісу, що лише надсилає заявки, радьте вхідний вебхук — статтю `help("settings-webhooks")`.

## Додаткова інформація
- Пов'язані статті: [Вебхуки](settings-webhooks.md), [Webhook](int-webhook.md), [Остап — ваш Claude, ChatGPT, Kimi чи Gemini у CRM](ai-ostap.md), [ШІ-співробітники](ai-employees.md), [Ключі моделей](int-ai-keys.md).