# API-ключі й публічний API: що автоматизувати першим

https://krokul.com/uk/blog/api-kliuchi-publichne-api/ · Команда Krokul · Оновлено 2026-11-19

Krokul CRM — B2B CRM для компаній, що працюють за договорами: угоди, проєкти й прибуток кожного клієнта в одній системі; впроваджують партнери-інтегратори. Публічний API й ключі з обмеженими правами дають вашим системам читати й писати дані CRM, а цей посібник розставляє перші задачі від найбезпечнішої до найризикованішої.

**Коротка відповідь.** Автоматизуйте через API CRM у такому порядку: спершу ключ лише на читання, що вивантажує угоди чи оплати в таблицю або BI, потім записи, що створюють картки з ваших форм чи продукту, потім оплати з бухгалтерії. Давайте кожному ключу лише ті scope й роль, які потрібні задачі, робіть кожен запис безпечним до повтору й стежте за журналом викликів ключа.

## Коли брати API-ключі замість готової інтеграції

Ключ і API підходять, коли жодна готова інтеграція не закриває задачу або коли ваш продукт мусить говорити з CRM. Посібник про [безпечне підключення AI-агентів та інших сервісів до CRM](https://krokul.com/uk/blog/topics/crm-ai-agents-integrations/) порівнює канали, а цей іде вглиб прямого.

- BI-інструмент чи таблиця мусять показувати угоди й оплати без ручного вивантаження.
- Ваш продукт чи форма на сайті мусять створювати клієнта або заявку в CRM.
- Бухгалтерія мусить повідомити CRM, що рахунок оплачено.
- Розробник чи партнер-інтегратор будує зʼєднання для клієнта.

- **API-ключ** — API-ключ означає секрет, що дозволяє стороннім системам викликати CRM від власного імені з обмеженими правами.
- **Scope** — Scope означає названу групу роутів, які ключ може викликати, наприклад cards.read для читання угод чи contacts.write для створення контактів.
- **Ключ ідемпотентності** — Ключ ідемпотентності означає унікальне значення, що йде із записом, щоб повтор повертав першу відповідь і картка записувалась один раз.

## Що автоматизувати першим через API CRM за шість кроків

Найбезпечніший порядок такий: спершу читання, потім створення, потім зміна, і кожен ключ отримує найменші права для своєї роботи. Кроки нижче веде інтегратор, якому потрібні угоди в BI-інструменті, а згодом заявки з власного сайту в CRM.

### 1. Перелічіть задачі й упорядкуйте їх за ризиком

Запишіть кожну задачу одним рядком із напрямом: читати з CRM, створювати в CRM чи змінювати в CRM. Читання не може зашкодити даним, створення може додати дублі, а зміна може затерти те, що ввела людина.

Почніть із найменшого ризику, що все одно економить справжній час, зазвичай це експорт лише на читання.

### 2. Прочитайте документацію роутів, які вам потрібні

Сторінка документації API згенерована з коду, а приклади в ній записано з живого прогону, тож роут і його поля збігаються з продуктом. Кожен роут є POST-запитом на адресу виду обʼєкт, коса риска, дія, із заголовком Bearer-ключа й JSON-тілом.

Помилки мають стабільний код, тож обробляйте їх за кодом. Повідомлення типово українською, а заголовок Accept-Language зі значенням en повертає англійські.

### 3. Створіть ключ з найменшими scope й найнижчою роллю

Адміністратор відкриває блок ключів API під каталогом «Маркетплейсу», натискає «Створити ключ», називає ключ за задачею, позначає лише потрібні scope, а тоді обирає роль і строк дії. Для BI-експорту позначте scope читання угод і компаній та нічого з закінченням write.

Роль є межею поверх scope й іде за тією самою матрицею, що й люди. Ключ може мати роль адміністратора, менеджера чи лише перегляду, типова роль менеджера, а ключ лише для перегляду писати не може.

### 4. Скопіюйте секрет один раз і перевірте пробою

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

Кнопка «Проба» біля ключа надсилає один справжній запит. Це не пісочниця, тож роут із правом на запис створить справжній запис у вашій компанії.

### 5. Зробіть кожен запис безпечним до повтору

Надсилайте заголовок Idempotency-Key із кожним записом. Повтор із тим самим ключем і тілом повертає першу відповідь із позначкою повтору й не створює другої картки. Той самий ключ з іншим тілом відбивається конфліктом.

Для зміни передавайте час оновлення, який ви читали останнім, і CRM відповість конфліктом, якщо запис тим часом змінився.

### 6. Стежте за журналом викликів і поважайте ліміт

Відкрийте «Журнал» ключа, щоб побачити його виклики. Ключ, що кличе надто часто, отримує відповідь 429 із заголовком Retry-After, тож зачекайте стільки секунд, перш ніж кликати знову.

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

![Діалог нового ключа API з назвою, правами, роллю, строком дії й перемикачем руйнівних дій AI](https://krokul.com/img/uk/blog/api-kliuchi-publichne-api-novyi-kliuch.webp)

## Яка задача потребує яких scope

Таблиця задач, scope й ризику робить порядок роботи видимим для всіх. Рядки нижче є прикладом для інтегратора, тож замініть їх власними задачами.

Приклад: задачі від найбезпечнішої до найризикованішої:

| Задача | Scope | Ризик |
|---|---|---|
| Вивантажити угоди й компанії в BI-інструмент | cards.read, companies.read | Лише читання |
| Створювати контакти й заявки з вашого сайту | contacts.write, cards.write | Дублі, якщо запис не безпечний до повтору |
| Записувати оплати з бухгалтерії | payments.write | Хибні суми потрапляють у перелік боргів |
| Підписатися на події замість опитування | webhooks.read, webhooks.write | Приймач, що не працює |

## Яких помилок з API-ключами уникати

- Ключ з усіма scope для зручності дозволяє витеклому секрету зробити все, тож давайте лише потрібне задачі.
- Перевірка роуту запису на живій компанії створює справжні записи, тож перевіряйте спершу читання й прибирайте після кожного запису.
- Повтор запису без ключа ідемпотентності створює дублі, тож надсилайте заголовок із кожним записом.
- Опитування переліку щохвилини марнує виклики, тож підпишіться на події через вебхуки і читайте повний запис, лише коли подія прийшла.
- Ключі завершених проєктів, що лишились активними, лишають двері відчиненими, тож задайте строк і відкликайте ключ, коли задача закінчилась.

## Чек-лист перед запуском ключа

- Задачу записано з напрямом: читання, створення чи зміна.
- Ключ має найменше scope й найнижчу роль, за яких усе працює.
- Секрет лежить у сховищі секретів і більше ніде.
- Кожен запис надсилає ключ ідемпотентності.
- Ключ має строк дії й власника, що читає його журнал.

## Як працюють публічний API й ключі в Krokul

Кожен роут є POST-запитом із JSON-тілом, HTTP-статус справжній, а успіх відповідає success true з даними, тоді як збій відповідає переліком помилок, кожна з яких має код. Переліки приймають зсув і кількість, а без них перелік віддає до 1000 рядків. Створення ключем іде за правилами вище, зі scope для угод, контактів, компаній, задач, активностей, документів, оплат, товарів, складу, прайсів, проєктів, звернень, звітів, вебхуків і файлів.

Кожен ключ має роль, що працює межею поверх scope, і строк дії: без строку, 30 днів, 90 днів чи рік. У діалозі є окремий перемикач, що дозволяє AI-клієнтам скасовувати й видаляти записи, і змінити його потім не можна, лише відкликати ключ. Кожен ключ може спитати, хто він, тож конектор перевіряє зʼєднання. Правила автоматизації ключам не відкриті, тож створюйте їх у вікні [правил автоматизації](https://krokul.com/uk/blog/stvoryty-pravylo-avtomatyzatsii-krokul/).

Документація живе на сторінці API й згенерована з коду, із прикладами, записаними з живого прогону. Підписками на вебхуки керує роут webhook/api-upsert зі scope webhooks.read і webhooks.write. Сторінка Krokul про [публічний API, вебхуки й MCP](https://krokul.com/uk/solutions/api/) підсумовує решту, а посібник про приклади автоматизацій CRM розповідає, що робити всередині CRM без коду.

## Питання й відповіді

### Що автоматизувати першим через API CRM?

Експорт угод, компаній чи оплат лише на читання в таблицю або BI-інструмент. Він економить ручну роботу й не може змінити дані CRM, тож є найбезпечнішою першою задачею.

### Як обмежити, що може робити API-ключ у Krokul?

Оберіть scope під час створення ключа й роль, що працює межею поверх них. Ключ може мати роль адміністратора, менеджера чи лише перегляду, а ключ лише для перегляду писати не може.

### Чи можна побачити секрет ключа ще раз?

Ні. Krokul показує секрет один раз і зберігає його хешем, тож загублений секрет означає новий ключ.

### Чи є кнопка «Проба» пісочницею?

Ні. Проба надсилає один справжній запит, і роут, що пише, створює справжній запис у вашій компанії.

### Що буде, якщо моя інтеграція кличе надто часто?

API відповість 429 із заголовком Retry-After. Зачекайте стільки секунд, скільки вказано в заголовку, і надішліть виклик знову.

---

Застосунок: https://app.krokul.com/ · API: https://app.krokul.com/api/v1/docs
