Вхідне — сервіс надсилає подію на адресу Krokul, правило знаходить угоду, документ, контакт чи контрагента й створює запис.
Вихідне — Krokul надсилає сервісу тіло, коли його запускає автоматизація з дією «Викликати сервіс».
Версія — кожна правка; діє лише та, яку прогнали на зразках і увімкнули.
Журнал — кожна подія, що дійшла до адреси, з результатом.
Скласти правило словами
Kro складає правило за описом, ви перевіряєте його на зразках.
- Натисніть «Нове правило».
- У блоці «Скласти словами» опишіть, звідки подія, що в ній шукати і що створити.
- На вкладці «Пробний прогін» вставте одне-два тіла запитів сервісу — Kro перевірить правило на них.
- Натисніть «Скласти» й зачекайте: зазвичай 10–40 секунд.
- Перегляньте правило в полі «Правило (JSON)» і результат на вкладці «Пробний прогін».
- Натисніть «Зберегти правило».
ПорадаНічого не зберігається, доки ви не натиснете «Зберегти». Версія, яку склав Kro, позначена «Склав Kro».
ВажливоЯкщо опису замало, Kro скаже, чого бракує, і правила не вставить. Допишіть опис і натисніть «Скласти» ще раз.
Перевірити правило на зразках
Прогін показує, що правило зробило б із кожною подією, і нічого не записує.
- Відкрийте правило й перейдіть на вкладку «Пробний прогін».
- У поле «Зразки» вставте тіла запитів сервісу — JSON-обʼєкт або масив від 1 до 20 обʼєктів.
- Натисніть «Прогнати».
- Під «Результат прогону» кожен зразок отримає позначку: «Буде виконано», «У журнал», «Пропущено» або «Збій».
- Біля кожного зразка видно, що знайшов пошук і яке тіло піде в дію.
ПорадаБеріть різні зразки: такий, що має спрацювати, такий, якого в Krokul немає, і такий, де бракує поля. Прогін, у якому всі зразки дали те саме, Krokul позначить «Перш ніж вмикати».
ВажливоПробний прогін запускає адміністратор.
Увімкнути версію
Діє лише прогнана версія.
- На вкладці «Правило» в блоці «Версії» знайдіть потрібну версію.
- Натисніть «Увімкнути» біля неї — або «Увімкнути версію N» угорі картки для останньої.
- Біля версії зʼявиться «Діє» й ім'я того, хто її увімкнув.
ВажливоВерсію, яку не проганяли, увімкнути не можна: біля неї написано «Не проганяли — увімкнути не можна».
Змінити правило
Діюча версія працює, доки ви не увімкнете нову.
- Змініть правило в полі «Правило (JSON)» або попросіть Kro в блоці «Скласти словами».
- Натисніть «Зберегти як версію N».
- Прожените нову версію на вкладці «Пробний прогін».
- Увімкніть її.
ПорадаЩоб повернути попередню версію, натисніть «Відкотитись» біля неї: її прогін і підтвердження збереглися.
Дати сервісу адресу
Куди сервіс надсилає події вхідного правила.
- Відкрийте правило й перейдіть на вкладку «Двері».
- Натисніть «Копіювати» біля «Адреса для сервісу».
- Вставте адресу в налаштування вебхука сервісу.
- Якщо правило вимагає підпис, впишіть ключ у поле «Новий ключ» і натисніть «Зберегти ключ».
- Той самий ключ задайте в сервісі для підпису запитів.
ВажливоТокен в адресі — це пароль. Якщо адресу побачив хтось сторонній, натисніть «Новий токен»: стара адреса перестане працювати одразу, і сервісу треба дати нову.
Подивитись, що сталося з подією
Журнал — кожна подія, що дійшла до адреси.
- Відкрийте правило й перейдіть на вкладку «Журнал».
- Кожен рядок — час, результат, версія правила й створений запис.
- Натисніть назву запису, щоб відкрити угоду, контакт чи контрагента.
- Під рядком «Збій» чи «У журнал» написано причину: якого поля бракує або що не знайшлося.
ПорадаНові події зверху. Сторінка — 50 подій, далі — стрілки праворуч унизу.
Вимкнути чи видалити правило
Вимкнене правило лишається з усіма версіями.
- Щоб зупинити правило, натисніть «Вимкнути» угорі картки.
- Щоб видалити, натисніть «⋯» угорі картки, оберіть «Видалити правило» й підтвердьте.
ВажливоВидалене правило йде в «Кошик» разом з усіма версіями, і події з його адреси більше не приймаються.
Поля й елементи
Екран «Правила інтеграцій»
| Колонка | Що це й на що впливає |
|---|---|
| Напрям, Вхідне, Вихідне | Вхідне — сервіс надсилає подію на адресу Krokul; вихідне — Krokul надсилає тіло сервісу, коли автоматизація виконує дію «Викликати сервіс». |
| Стан, Увімкнено, Вимкнено, На паузі | «На паузі» — десять збоїв поспіль: події не приймаються, адміністратори отримали сповіщення; знімає паузу «Увімкнути знову» в картці. |
| Діє | Номер увімкненої версії; «—» — жодна не діє. Нові правки не діють, доки їх не прогнали й не увімкнули. |
| Оновлено | Остання правка, увімкнення чи вимкнення правила. |
| Кнопка | Що це й на що впливає |
|---|---|
| Нове правило | Відкриває чернетку: правило складає Kro за описом або ви пишете JSON; нічого не зберігається до «Зберегти правило». Лише адміністратор, тариф «Маржа». |
| Увімкнути версію N, Вимкнути | Вмикає останню версію — лише прогнану на зразках; «Вимкнути» зупиняє правило, версії лишаються. |
| Ще дії з правилом, Видалити правило | Видалене правило йде в кошик з усіма версіями, і події з його адреси більше не приймаються. |
| Надіслати тестовий | Лише вихідне правило: справжній виклик сервісу тілом зразка — сервіс може створити запис у себе. |
| Новий токен адреси, Новий токен | Нова адреса; стара перестає приймати події одразу — дайте сервісу нову. |
| Вкладка | Що це й на що впливає |
|---|---|
| Правило | Версії, складання словами через Kro і саме правило в JSON. |
| Пробний прогін, Зразки, Прогнати | Від 1 до 20 тіл запитів сервісу; прогін шукає записи, але нічого не створює й не надсилає. Запускає адміністратор. |
| Двері, Сервіс, Адреса для сервісу, Адреса сервісу, Копіювати | Вхідне: адреса, яку дають сервісу, — токен у ній є паролем. Вихідне: адреса сервісу, вона задається в JSON правила. |
| Журнал, Виконано, Повтор, Відмовлено, Тест, До адреси | Кожна подія, новіші зверху, по 50: результат, версія, створений запис і причина збою. «Повтор» — те саме тіло вдруге, дія не повторюється. |
| Розділ | Що це й на що впливає |
|---|---|
| Версії, Діє, Остання, Склала людина, Склав Kro, Увімкнути, Відкотитись | Кожна правка — нова версія. Біля кожної — хто й коли склав, коли прогнали і хто увімкнув; «Відкотитись» вмикає попередню, вона вже прогнана. |
| Скласти словами, Що має робити правило, Скласти | Опис до 2 000 символів: звідки подія, що в ній шукати і що створити. Kro перевіряє себе на зразках із «Пробного прогону»; 10–40 секунд. |
| Правило (JSON), Зберегти як версію N, Зберегти правило, Перечитати | Правка руками; помилки перевірки названо з місцем. «Перечитати» — коли правило вже змінили паралельно. |
| Результат прогону, Буде виконано, У журнал, Пропущено, Збій, Перш ніж вмикати | Під кожним зразком — що знайшов пошук і тіло дії. «Перш ніж вмикати» — один зразок, однаковий результат усіх, немає суми від 1 000 чи з копійками. |
| Ключ підпису, Ключ сервісу, Новий ключ, Зберегти ключ, Задано, Не задано | Для підпису HMAC-SHA256 чи Bearer-токена; 16–256 символів, після збереження не показується. Підпис сервіс кладе в один із названих заголовків. |
Як це влаштовано
Тариф
Власні правила інтеграцій — на тарифі «Маржа». На іншому тарифі над реєстром стоїть пояснення, а адреса правила відповідає сервісу відмовою.
Що правило шукає
Угоду — за номером або зовнішнім ключем; документ — за номером або зовнішнім ключем; контакт — за телефоном, поштою або зовнішнім ключем; контрагента — за ЄДРПОУ, зовнішнім ключем, поштою чи телефоном. Знайшлося кілька записів — це «Збій»: правило не вгадує, який із них.
Що правило робить
Створює оплату в угоді чи за документом, змінює угоду, створює чи змінює контакт або контрагента, ставить задачу, пише подію в стрічку. Видаляти правило не може нічого.
Коли не знайшлося
Типово — «У журнал»: запис не створюється, подія чекає людину. «Пропущено» — правило свідомо не бере подію. «Створити» дозволено лише для контакту й контрагента: угоду чи рахунок правило «з повітря» не заводить.
Перетворення значень
Сума з комою чи пробілами між розрядами, дата у форматі сервісу, код валюти, номер телефону, так чи ні, довідник відповідностей і склеювання кількох полів. Порожнє обовʼязкове поле — «Збій» із назвою поля.
Перш ніж вмикати
Прогін попереджає, коли зразок лише один, коли всі зразки дали той самий результат, коли серед сум оплат немає жодної від 1 000 або жодної з копійками — саме там найчастіше ламається розбір числа.
Підпис
Вхідне правило або довіряє адресі (токен в адресі — пароль), або вимагає підпис HMAC-SHA256 сирого тіла ключем із вкладки «Двері». Сервіс кладе підпис в один із заголовків
x-krokul-signature,x-signature-256,x-hub-signature-256абоx-signature— у шістнадцятковому вигляді чи base64, з префіксомsha256=чи без. Ключ — від 16 до 256 символів; після збереження його не показано, лише позначку «Задано».Що отримує сервіс
200 — подію прийнято: виконано, записано в журнал, пропущено чи це повтор. 409 — правило вимкнене чи на паузі. 401 — немає правильного підпису. 402 — тариф. 422 — тіло не розібрано: повтор того самого тіла не допоможе. 502 — запис не вдався, повтор може допомогти.
Повтор доставки
Сервіси повторюють доставку, коли не дочекались відповіді. Те саме тіло вдруге стає рядком «Повтор» — друга оплата не створюється.
Пауза
Десять збоїв поспіль — правило стає «На паузі», адміністратори отримують сповіщення. Кнопка «Увімкнути знову» знімає паузу.
Вихідне правило
Тіло для сервісу збирається з даних події Krokul. Адреса сервісу задається в правилі; Krokul надсилає тіло без ключа, із заголовком
Authorization: Bearerабо з підписом HMAC-SHA256 у заголовкуx-krokul-signature. Запускає правило автоматизація з дією «Викликати сервіс». На вкладці «Пробний прогін» видно тіло, яке піде сервісу; «Надіслати тестовий» — справжній виклик сервісу цим тілом.Журнал
Позначки: «Виконано», «У журнал», «Пропущено», «Збій», «Повтор», «Відмовлено» — правило вимкнене, на паузі чи без ключа підпису, «Тест» — тестовий виклик вихідного правила.
Автор записів
Записи, створені правилом, мають автора «Правило інтеграції» — у стрічці видно, що їх зробила не людина.
Права
Перелік, версії й журнал бачать адміністратор і менеджер. Створює, проганяє, вмикає правила й бачить адресу та ключ — лише адміністратор. Агенту й спостерігачу екран закритий. Правил у компанії — до 100.
Питання й відповіді
Чим правило відрізняється від інтеграції з «Маркетплейсу»?
Інтеграцію з «Маркетплейсу» вже написано для конкретного сервісу. Правило ви складаєте самі — для сервісу, якого в каталозі немає, або коли потрібна інша логіка.
Чому подія лягла в журнал, а запис не створився?
Правило не знайшло угоду, документ, контакт чи контрагента за значенням із тіла. Причину видно під рядком журналу: що шукали і за яким значенням.
Сервіс надіслав ту саму подію двічі — чи буде дві оплати?
Ні. Друге надходження того самого тіла стає рядком «Повтор», дія не повторюється.
Чому правило стало «На паузі»?
Десять подій поспіль закінчились збоєм — найчастіше сервіс змінив формат тіла. Подивіться причину в журналі, виправте правило, прожените й увімкніть знову.
Чи можна повернути попередню версію?
Так. Натисніть «Відкотитись» біля неї у блоці «Версії» — вона вже прогнана, тож вмикається одразу.
Хто бачить ключ підпису?
Ніхто: після збереження ключ не показано навіть адміністратору. Щоб змінити, впишіть новий і натисніть «Зберегти ключ».
Чи допомогла стаття?
Дякуємо — так ми знаємо, яку статтю доробити.
Спробуйте в Krokul
Правила інтеграцій відкривається в застосунку за один клік після входу.