Коротка відповідь
Автоматизуйте через API CRM у такому порядку: спершу ключ лише на читання, що вивантажує угоди чи оплати в таблицю або BI, потім записи, що створюють картки з ваших форм чи продукту, потім оплати з бухгалтерії. Давайте кожному ключу лише ті scope й роль, які потрібні задачі, робіть кожен запис безпечним до повтору й стежте за журналом викликів ключа.
- Почніть із: ключа лише на читання
- Кожен ключ має: scope, роль, строк дії
- Записи мусять бути: безпечними до повтору
На цій сторінці
Коли брати API-ключі замість готової інтеграції#
Ключ і API підходять, коли жодна готова інтеграція не закриває задачу або коли ваш продукт мусить говорити з CRM. Посібник про безпечне підключення AI-агентів та інших сервісів до CRM порівнює канали, а цей іде вглиб прямого.
- BI-інструмент чи таблиця мусять показувати угоди й оплати без ручного вивантаження.
- Ваш продукт чи форма на сайті мусять створювати клієнта або заявку в CRM.
- Бухгалтерія мусить повідомити CRM, що рахунок оплачено.
- Розробник чи партнер-інтегратор будує зʼєднання для клієнта.
- API-ключ
- API-ключ означає секрет, що дозволяє стороннім системам викликати CRM від власного імені з обмеженими правами.
- Scope
- Scope означає названу групу роутів, які ключ може викликати, наприклад cards.read для читання угод чи contacts.write для створення контактів.
- Ключ ідемпотентності
- Ключ ідемпотентності означає унікальне значення, що йде із записом, щоб повтор повертав першу відповідь і картка записувалась один раз.
Що автоматизувати першим через API CRM за шість кроків#
Найбезпечніший порядок такий: спершу читання, потім створення, потім зміна, і кожен ключ отримує найменші права для своєї роботи. Кроки нижче веде інтегратор, якому потрібні угоди в BI-інструменті, а згодом заявки з власного сайту в CRM.
Перелічіть задачі й упорядкуйте їх за ризиком
Запишіть кожну задачу одним рядком із напрямом: читати з CRM, створювати в CRM чи змінювати в CRM. Читання не може зашкодити даним, створення може додати дублі, а зміна може затерти те, що ввела людина.
Почніть із найменшого ризику, що все одно економить справжній час, зазвичай це експорт лише на читання.
Прочитайте документацію роутів, які вам потрібні
Сторінка документації API згенерована з коду, а приклади в ній записано з живого прогону, тож роут і його поля збігаються з продуктом. Кожен роут є POST-запитом на адресу виду обʼєкт, коса риска, дія, із заголовком Bearer-ключа й JSON-тілом.
Помилки мають стабільний код, тож обробляйте їх за кодом. Повідомлення типово українською, а заголовок Accept-Language зі значенням en повертає англійські.
Створіть ключ з найменшими scope й найнижчою роллю
Адміністратор відкриває блок ключів API під каталогом «Маркетплейсу», натискає «Створити ключ», називає ключ за задачею, позначає лише потрібні scope, а тоді обирає роль і строк дії. Для BI-експорту позначте scope читання угод і компаній та нічого з закінченням write.
Роль є межею поверх scope й іде за тією самою матрицею, що й люди. Ключ може мати роль адміністратора, менеджера чи лише перегляду, типова роль менеджера, а ключ лише для перегляду писати не може.
Скопіюйте секрет один раз і перевірте пробою
Секрет показується один раз і зберігається хешем, тож одразу покладіть його в сховище секретів. Загублений секрет означає новий ключ.
Кнопка «Проба» біля ключа надсилає один справжній запит. Це не пісочниця, тож роут із правом на запис створить справжній запис у вашій компанії.
Зробіть кожен запис безпечним до повтору
Надсилайте заголовок Idempotency-Key із кожним записом. Повтор із тим самим ключем і тілом повертає першу відповідь із позначкою повтору й не створює другої картки. Той самий ключ з іншим тілом відбивається конфліктом.
Для зміни передавайте час оновлення, який ви читали останнім, і CRM відповість конфліктом, якщо запис тим часом змінився.
Стежте за журналом викликів і поважайте ліміт
Відкрийте «Журнал» ключа, щоб побачити його виклики. Ключ, що кличе надто часто, отримує відповідь 429 із заголовком Retry-After, тож зачекайте стільки секунд, перш ніж кликати знову.
Задайте строк дії ключам, що обслуговують проєкт, і відкликайте ключ у ту мить, коли його задача завершилась. Відкликані ключі за замовчуванням сховані з переліку й показуються перемикачем.

Яка задача потребує яких 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-клієнтам скасовувати й видаляти записи, і змінити його потім не можна, лише відкликати ключ. Кожен ключ може спитати, хто він, тож конектор перевіряє зʼєднання. Правила автоматизації ключам не відкриті, тож створюйте їх у вікні правил автоматизації.
Документація живе на сторінці API й згенерована з коду, із прикладами, записаними з живого прогону. Підписками на вебхуки керує роут webhook/api-upsert зі scope webhooks.read і webhooks.write. Сторінка Krokul про публічний API, вебхуки й MCP підсумовує решту, а посібник про приклади автоматизацій CRM розповідає, що робити всередині CRM без коду.
Питання й відповіді#
Що автоматизувати першим через API CRM?
Експорт угод, компаній чи оплат лише на читання в таблицю або BI-інструмент. Він економить ручну роботу й не може змінити дані CRM, тож є найбезпечнішою першою задачею.
Як обмежити, що може робити API-ключ у Krokul?
Оберіть scope під час створення ключа й роль, що працює межею поверх них. Ключ може мати роль адміністратора, менеджера чи лише перегляду, а ключ лише для перегляду писати не може.
Чи можна побачити секрет ключа ще раз?
Ні. Krokul показує секрет один раз і зберігає його хешем, тож загублений секрет означає новий ключ.
Чи є кнопка «Проба» пісочницею?
Ні. Проба надсилає один справжній запит, і роут, що пише, створює справжній запис у вашій компанії.
Що буде, якщо моя інтеграція кличе надто часто?
API відповість 429 із заголовком Retry-After. Зачекайте стільки секунд, скільки вказано в заголовку, і надішліть виклик знову.