# Правила інтеграцій у Krokul: подія сервісу → запис у CRM

Власні правила для сервісів, яких немає в «Маркетплейсі»: що зробити в Krokul, коли сервіс надсилає подію, і що надіслати сервісу, коли подія сталась у Krokul.

Теги: правила інтеграцій, вебхук, вхідний вебхук, підпис hmac, пробний прогін, журнал подій, Kro

## Коротко
- **Вхідне** — сервіс надсилає подію на адресу Krokul, правило знаходить угоду, документ, контакт чи контрагента й створює запис.
- **Вихідне** — Krokul надсилає сервісу тіло, коли його запускає автоматизація з дією «Викликати сервіс».
- **Версія** — кожна правка; діє лише та, яку прогнали на зразках і увімкнули.
- **Журнал** — кожна подія, що дійшла до адреси, з результатом.

## Як зробити
### Скласти правило словами
Kro складає правило за описом, ви перевіряєте його на зразках.
1. Натисніть «Нове правило».
2. У блоці «Скласти словами» опишіть, звідки подія, що в ній шукати і що створити.
3. На вкладці «Пробний прогін» вставте одне-два тіла запитів сервісу — Kro перевірить правило на них.
4. Натисніть «Скласти» й зачекайте: зазвичай 10–40 секунд.
5. Перегляньте правило в полі «Правило (JSON)» і результат на вкладці «Пробний прогін».
6. Натисніть «Зберегти правило».
> Порада: Нічого не зберігається, доки ви не натиснете «Зберегти». Версія, яку склав Kro, позначена «Склав Kro».
> Важливо: Якщо опису замало, Kro скаже, чого бракує, і правила не вставить. Допишіть опис і натисніть «Скласти» ще раз.

### Перевірити правило на зразках
Прогін показує, що правило зробило б із кожною подією, і нічого не записує.
1. Відкрийте правило й перейдіть на вкладку «Пробний прогін».
2. У поле «Зразки» вставте тіла запитів сервісу — JSON-обʼєкт або масив від 1 до 20 обʼєктів.
3. Натисніть «Прогнати».
4. Під «Результат прогону» кожен зразок отримає позначку: «Буде виконано», «У журнал», «Пропущено» або «Збій».
5. Біля кожного зразка видно, що знайшов пошук і яке тіло піде в дію.
> Порада: Беріть різні зразки: такий, що має спрацювати, такий, якого в Krokul немає, і такий, де бракує поля. Прогін, у якому всі зразки дали те саме, Krokul позначить «Перш ніж вмикати».
> Важливо: Пробний прогін запускає адміністратор.

### Увімкнути версію
Діє лише прогнана версія.
1. На вкладці «Правило» в блоці «Версії» знайдіть потрібну версію.
2. Натисніть «Увімкнути» біля неї — або «Увімкнути версію N» угорі картки для останньої.
3. Біля версії зʼявиться «Діє» й ім'я того, хто її увімкнув.
> Важливо: Версію, яку не проганяли, увімкнути не можна: біля неї написано «Не проганяли — увімкнути не можна».

### Змінити правило
Діюча версія працює, доки ви не увімкнете нову.
1. Змініть правило в полі «Правило (JSON)» або попросіть Kro в блоці «Скласти словами».
2. Натисніть «Зберегти як версію N».
3. Прожените нову версію на вкладці «Пробний прогін».
4. Увімкніть її.
> Порада: Щоб повернути попередню версію, натисніть «Відкотитись» біля неї: її прогін і підтвердження збереглися.

### Дати сервісу адресу
Куди сервіс надсилає події вхідного правила.
1. Відкрийте правило й перейдіть на вкладку «Двері».
2. Натисніть «Копіювати» біля «Адреса для сервісу».
3. Вставте адресу в налаштування вебхука сервісу.
4. Якщо правило вимагає підпис, впишіть ключ у поле «Новий ключ» і натисніть «Зберегти ключ».
5. Той самий ключ задайте в сервісі для підпису запитів.
> Важливо: Токен в адресі — це пароль. Якщо адресу побачив хтось сторонній, натисніть «Новий токен»: стара адреса перестане працювати одразу, і сервісу треба дати нову.

### Подивитись, що сталося з подією
Журнал — кожна подія, що дійшла до адреси.
1. Відкрийте правило й перейдіть на вкладку «Журнал».
2. Кожен рядок — час, результат, версія правила й створений запис.
3. Натисніть назву запису, щоб відкрити угоду, контакт чи контрагента.
4. Під рядком «Збій» чи «У журнал» написано причину: якого поля бракує або що не знайшлося.
> Порада: Нові події зверху. Сторінка — 50 подій, далі — стрілки праворуч унизу.

### Вимкнути чи видалити правило
Вимкнене правило лишається з усіма версіями.
1. Щоб зупинити правило, натисніть «Вимкнути» угорі картки.
2. Щоб видалити, натисніть «⋯» угорі картки, оберіть «Видалити правило» й підтвердьте.
> Важливо: Видалене правило йде в «Кошик» разом з усіма версіями, і події з його адреси більше не приймаються.

## Як це влаштовано
**Тариф.** Власні правила інтеграцій — на тарифі «Маржа». На іншому тарифі над реєстром стоїть пояснення, а адреса правила відповідає сервісу відмовою.

**Що правило шукає.** Угоду — за номером або зовнішнім ключем; документ — за номером або зовнішнім ключем; контакт — за телефоном, поштою або зовнішнім ключем; контрагента — за ЄДРПОУ, зовнішнім ключем, поштою чи телефоном. Знайшлося кілька записів — це «Збій»: правило не вгадує, який із них.

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

**Коли не знайшлося.** Типово — «У журнал»: запис не створюється, подія чекає людину. «Пропущено» — правило свідомо не бере подію. «Створити» дозволено лише для контакту й контрагента: угоду чи рахунок правило «з повітря» не заводить.

**Перетворення значень.** Сума з комою чи пробілами між розрядами, дата у форматі сервісу, код валюти, номер телефону, так чи ні, довідник відповідностей і склеювання кількох полів. Порожнє обовʼязкове поле — «Збій» із назвою поля.

**Перш ніж вмикати.** Прогін попереджає, коли зразок лише один, коли всі зразки дали той самий результат, коли серед сум оплат немає жодної від 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; вихідне — 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 символів, після збереження не показується. Підпис сервіс кладе в один із названих заголовків. |

---

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