# Маркетплейс Krokul: сайт, магазини, телефонія й API

Підключайте форми сайту, магазини, телефонію й оплати, видавайте ключі API і пускайте AI-агентів у Krokul.

Теги: інтеграції, форма заявки з сайту, api ключ, інтернет-магазин, телефонія, mcp

## Коротко
- **Токен входу** — особиста адреса, на яку один канал надсилає заявки, дзвінки чи оплати.
- **Журнал приймань** — що сталося з кожною заявкою, яку прислав канал.
- **Ключ API** — доступ зовнішньої системи до Krokul за вибраними правами.
- **Підключений застосунок** — AI-клієнт, який діє від імені людини, що його дозволила.

## Як зробити
### Підключити форму з сайту
Заявки з сайту самі стають контактами й угодами.
1. Натисніть картку «Веб-форма (універсальна)» — відкриється сторінка інтеграції.
2. Впишіть назву токена, наприклад назву лендінгу, і натисніть «Підключити».
3. У рядку токена натисніть «Скопіювати адресу» й передайте адресу розробнику сайту.
4. Натисніть «Налаштувати» й оберіть воронку, джерело й відповідального за заявки.
5. Натисніть «Зберегти».
6. Надішліть тестову заявку й перевірте «Журнал приймань».
> Порада: Угода зветься „Заявка · імʼя з форми“. Якщо форма передає поле `company`, Krokul знайде або заведе контрагента й привʼяже до нього контакт і угоду.
> Важливо: Новий токен одразу дістає першу воронку компанії. Відповідальний за заявки отримає сповіщення про кожну нову угоду.

### Поставити готову форму на сайт
Готова форма заявки ставиться на будь-який сайт одним рядком коду, без розробника форми.
1. Підключіть веб-форму, як описано вище, і оберіть воронку: тоді заявка стане контактом і угодою. Без воронки буде лише контакт.
2. У рядку токена натисніть «Віджет на сайт».
3. Оберіть «Вигляд»: «Форма на сторінці» або «Плаваюча кнопка» в кутку сторінки.
4. Позначте «Поля форми» й ті, що «Обовʼязкове», за потреби змініть тексти, «Колір» і «Мову віджета». «Попередній перегляд» одразу показує, як форма виглядатиме на сайті.
5. Натисніть «Зберегти вигляд», щоб наступного разу відкрилось те саме.
6. У «Рядку для вставки на сайт» натисніть «Скопіювати» й вставте рядок у сторінку сайту там, де має стояти форма. Токен у рядку вже стоїть.
7. Натисніть «Налаштувати» й у полі «Дозволені сайти» впишіть свої сайти, по одному на рядок, наприклад `example.com`. Натисніть «Зберегти».
8. Надішліть тестову заявку з сайту й перевірте «Журнал приймань».
> Порада: Заявка з попереднього перегляду не надсилається: перегляд не знає справжнього токена. Перевіряйте форму на самому сайті.
> Порада: Рядок із токеном дає лише адміністратор; іншим ролям токен показано маскою.
> Важливо: Запис `example.com` пускає й піддомени, наприклад `www.example.com` і `shop.example.com`. Якщо поле порожнє, форма працює на будь-якому сайті.

### Підключити магазин чи оплати
Магазини, телефонія, платежі й Нова пошта підключаються так само — токеном.
1. Натисніть картку сервісу, впишіть назву токена й натисніть «Підключити».
2. Розгорніть «Як підключити» — там інструкція саме для цього сервісу.
3. Якщо сервіс надсилає дані сам, натисніть «Скопіювати адресу» й впишіть її в його кабінеті.
4. Натисніть «Налаштувати», заповніть ключі сервісу й натисніть «Зберегти».
5. Перевірте, що під рядком токена стоїть „Налаштовано“.
> Порада: Поки чогось бракує, під токеном написано „Бракує: …“ з назвами полів.
> Важливо: Збережений секрет показується маскою. Порожнє поле при збереженні його не змінює.

### Підключити банк через Salt Edge
Банки через Salt Edge передають рух коштів у «Надходження»: гроші на рахунках компанії зʼявляються там самі, з підказкою, до якого плану оплати вони належать.
1. У блоці «Підключення банку» натисніть «Підключити банк».
2. Сторінка згоди Salt Edge відкриється в новій вкладці: завершіть згоду й поверніться — натисніть «Я вже підключив — оновити».
3. Перевірте стан підключення, кількість рахунків, «Останнє читання», «Наступне читання» і «Згода діє до».
4. Щоб підтягнути виписку негайно, натисніть «Оновити зараз»; ще один банк — «Додати ще банк».
> Важливо: Підключенням банку керує адміністратор. Коли згода скоро спливе, Krokul попереджає: оновіть її кнопкою «Оновити згоду», інакше нові надходження перестануть приходити.
> Важливо: «Відключити» зупиняє нові надходження; уже прочитані надходження й підтверджені оплати лишаються.

### Планувати надходження у Finmap
Планові оплати угод зʼявляються в платіжному календарі Finmap як очікувані надходження — без ручного переписування.
1. Натисніть картку Finmap, впишіть назву токена й натисніть «Підключити».
2. У Finmap відкрийте Налаштування → API й створіть ключ (API є на тарифі, що його дає).
3. У налаштуваннях токена в Krokul впишіть «Ключ API», «Рахунок Finmap (id)» — рахунок, на який планувати надходження, — і «Валюта рахунку».
4. За потреби впишіть «Категорія доходу (id)» — поле необовʼязкове.
5. Натисніть «Зберегти» й перевірте журнал надсилань під налаштуваннями токена.
> Порада: Адреса прийому для Finmap не потрібна: Krokul сам надсилає плани у Finmap.
> Важливо: Надсилається кожен відкритий план оплати зі строком — на дату строку й на суму, що лишилась до оплати. Плани в іншій валюті, ніж у рахунку, не надсилаються: причину видно в журналі.
> Важливо: Підключення не перевірено на живому акаунті Finmap — зроблено за документацією API. Якщо Finmap відмовить, текст відмови буде в журналі.

### Підключити QuickBooks Online
Рахунки з Krokul потрапляють у QuickBooks Online разом із клієнтом і товарами, а оплати й анулювання повертаються на документ. Ключі в поля не вписуються — достатньо ввійти в акаунт Intuit.
1. Натисніть картку QuickBooks Online і виберіть «Підключити QuickBooks».
2. Вхід в Intuit відкриється в новій вкладці: дайте згоду й поверніться — натисніть «Я вже підключив — оновити».
3. Переконайтесь, що стоїть «Підключено», а під статусом видно, хто підключив і коли оновлено доступ.
4. У налаштуваннях QuickBooks оберіть «Компанія в QuickBooks» і вирішіть, коли надсилати документ та хто нумерує.
5. Оберіть «Рахунок доходу», «Позицію для рядків без товару» і для кожної ставки ПДВ — податковий код QuickBooks. Натисніть «Зберегти».
6. У картці рахунку натисніть «Надіслати в QuickBooks» — або залиште автоматичне надсилання за вибраним режимом.
7. Перебіг обміну дивіться в журналі синхронізації: у черзі, надсилається, готово, помилка; збійні записи можна повторити.
> Важливо: Підключенням керує адміністратор. Якщо картка каже «Недоступно в цій установці», у ній немає ключів застосунку Intuit — їх додає той, хто розгортав Krokul.
> Важливо: Рахунок зі ставкою ПДВ без податкового коду або з рядком без товару, коли «Позицію для рядків без товару» не обрано, не надсилається; товар не надсилається без «Рахунок доходу». Чернетки й скасовані рахунки не надсилаються ніколи.
> Важливо: Обмін перевірено на пробному сервері QuickBooks Online, наживо з акаунтом Intuit його ще не звіряли.
> Порада: «Відключити» не видаляє нічого в QuickBooks, а звʼязки документів зберігаються. Коли доступ спливає, Krokul просить «Підключити заново».

### Призначити лінії для дзвінків із UniTalk
Без лінії людина не дзвонить із Krokul.
1. Підключіть картку «UniTalk» токеном і впишіть у налаштуваннях потоку ключ API з кабінету UniTalk (Інтеграції → API).
2. На сторінці UniTalk знайдіть блок «Лінії людей». Кожній людині компанії відповідає поле «Лінія».
3. Введіть внутрішній номер (2–6 цифр) або мобільний (10–15 цифр) й натисніть «Зберегти».
4. Щоб прибрати лінію, натисніть «Зняти лінію».
> Порада: Блок бачить і змінює лише адміністратор.
> Важливо: Людина без лінії бачить кнопку дзвінка вимкненою з поясненням „Вам не призначено внутрішню лінію UniTalk“.

### Подзвонити клієнту з картки
UniTalk спершу дзвонить на вашу лінію, а після відповіді набирає клієнта.
1. Відкрийте картку контакту чи контрагента з номером телефону.
2. Натисніть кнопку з трубкою біля номера. Підказка на ній називає номер, наприклад «Подзвонити +380501234567 через UniTalk».
3. Біля кнопки з’явиться „UniTalk дзвонить на вашу лінію …“ — візьміть слухавку або прийміть виклик у софтфоні.
4. Дочекайтеся, поки UniTalk з’єднає вас із клієнтом.
> Важливо: Номер має бути міжнародним, наприклад +380501234567, або українським із нуля. Інакше Krokul попросить виправити номер.
> Порада: Поки йде виклик, кнопка зайнята — другого виклику не буде. Розмову Krokul у стрічку не пише: запис з’явиться після її завершення.

### Послухати запис розмови
Розмову з відповіддю видно в стрічці з плеєром.
1. Відкрийте стрічку картки, де записано дзвінок: рядок повідомляє, звідки дзвінок і чи відповіли, а після відповіді додає тривалість, наприклад „розмова 1:35“.
2. Під рядком натисніть кнопку відтворення «Запис розмови» й слухайте.
> Порада: Плеєр з’являється лише в розмови, яку UniTalk записав. Запис не вантажиться, доки ви не натиснете відтворення.
> Важливо: Запис лежить у UniTalk — Krokul лише дає посилання на нього.

### Встановити модуль OpenCart
Готовий архів модуля для адмінки магазину.
1. Відкрийте картку «OpenCart» і створіть токен.
2. У розділі модуля для магазину натисніть «Модуль для OpenCart 3.x» або «Модуль для OpenCart 4.x».
3. Встановіть архів в адмінці OpenCart як розширення.
4. У налаштуваннях модуля вкажіть адресу шлюзу й токен цього підключення.
> Порада: Архів однаковий для всіх магазинів: адреси й токена в ньому немає. Якщо зібрати не вдалося, причина зʼявиться біля кнопки.

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

### Створити ключ API
Доступ для зовнішньої системи, яка сама ходить у Krokul.
1. Під каталогом у блоці ключів публічного API натисніть «Створити ключ».
2. Впишіть назву — для чого цей ключ.
3. Позначте права — лише ті, що потрібні цій системі.
4. За потреби оберіть роль і строк дії ключа.
5. Натисніть «Створити ключ».
6. Скопіюйте секрет кнопкою «Скопіювати» — він показується лише один раз.
- Роль — межа поверх прав, та сама матриця, що в користувачів; типово — менеджер.
- Строк дії — без строку, 30 днів, 90 днів або рік.
> Важливо: «Дозволити руйнівні дії для AI-клієнтів (MCP)» дає AI-клієнту скасовувати й видаляти записи. Змінити це потім не можна — лише відкликати ключ.

### Перевірити ключ пробою
Один справжній запит ключем і відповідь сервера.
1. У рядку ключа натисніть «Проба».
2. Оберіть маршрут.
3. Натисніть «Надіслати» — зʼявиться відповідь сервера.
4. Історію викликів ключа відкрийте кнопкою «Журнал».
> Важливо: Проба — не пісочниця. Маршрут із правом на запис створить справжній запис у вашій компанії.
> Порада: Порожня адреса сервера в пробі — ваш робочий Krokul.

### Відкликати ключ API
Зовнішня система зупиниться одразу.
1. У рядку ключа натисніть «Відкликати».
2. Підтвердьте кнопкою «Відкликати».
> Порада: Відкликаний ключ лишається в переліку як історія — його видно з перемикачем «Показувати відкликані».

### Підключити AI-агента (MCP)
Claude чи інший MCP-клієнт працює з вашою компанією від вашого імені, без ключа.
1. У Claude додайте власний конектор з адресою `https://app.krokul.com/mcp`.
   - У Claude Code: `claude mcp add --transport http krokul https://app.krokul.com/mcp`, далі `/mcp` → «Authenticate».
2. Увійдіть у Krokul на сторінці, яку відкриє клієнт.
3. Перевірте назву застосунку й адресу, куди буде передано дозвіл.
4. Оберіть компанію.
5. Зніміть позначки з дозволів, яких застосунку не треба.
6. Натисніть «Дозволити» — клієнт повернеться до роботи сам.
> Важливо: Дозволи групи „Зміни“ дають право створювати й змінювати записи від вашого імені.
> Порада: Позначка „Назву не перевірено“ означає, що назву застосунок вказав сам. Дозволяйте, лише якщо підключення почали ви.

### Відкликати доступ застосунку
Застосунок втратить доступ і попросить увійти знову.
1. Відкрийте «Мій профіль» і знайдіть блок підключених застосунків.
2. У рядку застосунку натисніть «Відкликати».
3. Підтвердьте кнопкою «Відкликати».
> Порада: Адміністратор бачить підключення всіх людей компанії тут, на «Маркетплейсі», під ключами API, і може відкликати будь-яке.

### Запустити агента керівника
AI-агент перевіряє дисципліну заповнення угод і розбирає демонстрації.
1. Підключіть AI-клієнта від імені адміністратора.
2. На сторінці згоди лишіть позначеними дозволи:
   - «Висновки агента керівника» — перегляд і запис;
   - «Звіти — перегляд» і «Угоди — перегляд»;
   - «Стрічка подій — перегляд»;
   - «Задачі — створення й зміна» — якщо агент ставитиме задачі менеджерам.
3. Попросіть агента виконати промпт `discipline-review` або `demo-review`.
> Порада: Тексти демонстрацій агент бере з подій „Зустріч“ у стрічці угоди. Після демонстрації додайте таку подію з підсумком у кілька речень.
> Важливо: Таблицю висновків бачить лише адміністратор і лише через агента. У стрічку угоди агент нічого не пише.

## Як це влаштовано
**Які інтеграції є.** Каталог групує картки за видом сервісу; кожна картка веде на свою сторінку інтеграції.
- Форми — Google Forms;
- Магазини — OpenCart, Хорошоп, Rozetka, Prom.ua;
- Платежі — Plata by mono, NovaPay, LiqPay;
- Телефонія — UniTalk, Binotel, Phonet;
- Доставка — Нова пошта;
- Документи на підпис — Вчасно (кроки — в статті «Картка документа»);
- Облік і фінанси — QuickBooks Online (рахунки й оплати), Finmap (платіжний календар), банки через Salt Edge (надходження);
- Інше — веб-форма, Telegram, Viber-бот, Shopify, WooCommerce, Lead Ads Instagram / Facebook, Ringostat.

**Дзвінок у клік.** Кнопка стоїть біля номера в картках контакту й контрагента. Вона з’являється, коли в компанії підключено UniTalk із ключем API. Активна, якщо в людини є лінія і її роль не «Спостерігач»; інакше вимкнена, а підказка називає причину: немає ключа, немає лінії чи роль.

**Дзвінок у стрічці.** UniTalk повідомляє Krokul про кінець розмови: у стрічку лягає рядок із напрямком, номером, результатом і тривалістю, а в розмови з відповіддю — плеєр запису. На пропущений дзвінок Krokul ставить задачу „Передзвонити …“. Повторний дзвінок того ж контакту потрапляє в уже відкриту угоду.

**Призупинені інтеграції.** Позначка „Призупинено“ означає, що обробка каналу тимчасово зупинена. Токени й адреси створюються й запрацюють, щойно обробку відновлять.

**Що відбувається із заявкою.** Krokul знаходить або створює контакт, створює угоду, ставить задачу чи записує розмову. Месенджери й телефонія чіпляють повторне звернення того самого контакту до вже відкритої угоди.

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

**Telegram.** Самого бота підключають у «Комунікаціях». Токен тут лише задає воронку й джерело для нових звернень із Telegram.

**Токен проти ключа API.** Токен приймає дані одного каналу на одну адресу. Ключ API дає зовнішній системі доступ до Krokul за вибраними правами.

**Підключення входом.** AI-клієнт діє з правами людини, яка його дозволила, і лише в межах обраних дозволів. Знизили роль — права звузяться з наступного виклику; прибрали людину з компанії — підключення погасне.

**Безпека.**
- повністю адреса токена показується один раз; далі видно останні чотири символи, а «Скопіювати адресу» адміністратора копіює її цілою;
- секрет ключа API показується один раз; у Krokul лежить лише його відбиток;
- активних ключів API в компанії — не більше 10;
- руйнівні дії AI-клієнт дістає лише через ключ із такою позначкою, підключенню входом вони не даються;
- журнал приймань показує останні 50 подій;
- готова форма відсіює ботів прихованим полем і перевіркою часу заповнення й приймає не більше 10 заявок за хвилину з однієї адреси.

**Документація API.** Посилання «Документація API» біля блоку ключів веде на опис усіх маршрутів публічного API.

**Хто що може.** Підключати канали, завантажувати модуль магазину, керувати ключами й підключеннями всіх людей — лише адміністратор. Менеджер бачить токени й журнал приймань без права змінювати.

Повʼязані вікна: «Мій профіль», «Вебхуки», «Комунікації», «Зовнішні ID».

## Питання й відповіді
### Де знайти адресу токена, якщо я її не скопіював?
Адміністратор натискає «Скопіювати адресу» в рядку токена — копіюється повна робоча адреса з доменом. Іншим ролям видно лише кінець адреси.

### Чому заявка з форми на сайті не дійшла?
Відкрийте «Журнал приймань» цього токена. „Відсіяно захистом від ботів“ означає, що форму заповнили за дві секунди або заповнили приховане поле: так поводяться боти, а не люди. Якщо форма пише, що сайт не приймається, додайте цей сайт у «Дозволені сайти».

### Що робити, якщо ключ API потрапив у чужі руки?
Натисніть «Відкликати» в його рядку: ключ перестане працювати одразу. Підписки на вебхуки, створені цим ключем, вимкнуться разом із ним.

### Чи є в Krokul відкритий API?
Так. Адміністратор створює ключ із потрібними правами й строком дії, а опис маршрутів відкривається посиланням «Документація API». AI-клієнти ходять тим самим API через MCP.

### Чому на сторінці згоди немає моєї компанії?
Підключити можна лише компанію, де у вас внутрішня роль. Демо-компанії й кабінет партнера на сторінці згоди не показуються.

### Як підключити AI-агента від іншого акаунта?
На сторінці згоди біля вашого імені натисніть «Інший акаунт» і увійдіть під потрібним.

### Як агент дізнається, хто пробує перескочити етап?
Коли угоду переводять на етап без обовʼязкових полів, Krokul відмовляє й записує спробу в службовий журнал. Його бачать адміністратор і керівник через агента; у стрічці угоди цього немає.

## Поля й елементи

### Екран «Маркетплейс»

| Поле | Що це й на що впливає |
|---|---|
| Поля підключення | Склад задає адаптер. Секрети показано маскою; порожнє поле збережений секрет не змінює. |
| Воронка, джерело й відповідальний за заявки | Куди лягає заявка з токена; без воронки заявка з сайту не стає угодою. |

| Фільтр і пошук | Що це й на що впливає |
|---|---|
| Показувати відкликані | Відкликані ключі як історія: на них можна відкрити журнал викликів. |

| Кнопка | Що це й на що впливає |
|---|---|
| Створити ключ | Секрет показується один раз; загублений ключ відкликають і заводять новий. Лише адміністратор. |
| Журнал | Виклики ключа: час, запит, код, тривалість і помилка; є й на відкликаних. |
| Проба | Справжній запит цим ключем у вашу компанію, не пісочниця. |
| Відкликати | Застосунок зупиняється одразу, його підписки на вебхуки вимикаються; ключ лишається в історії. |
| Скопіювати адресу | Копіює ПОВНУ робочу адресу, хоч у рядку вона схована; якщо роль бачить лише маску — з маскою. |
| Налаштувати | Під токеном завжди видно стан: «Налаштовано» або «Бракує:» з переліком полів. |
| Підключити | Створює токен; повну адресу прийому скопіюйте одразу. Лише адміністратор. |
| Завантажити модуль | Архів однаковий для всіх: адреси й токена в ньому немає. |

| Розділ | Що це й на що впливає |
|---|---|
| Вітрина інтеграцій | Картки адаптерів за призначенням; натиск відкриває сторінку інтеграції. «Призупинено» підключення не блокує. |
| Ключі публічного API | Доступ зовнішнього застосунку до запитів Krokul у межах прав; це не токен адаптера. Активних — до десяти. |
| Рядок ключа | «Руйнівні дії» — ключу дозволено скасування й видалення для MCP-клієнтів. |
| Токени входу | Токен — адреса прийому одного адаптера; повна адреса видна лише при створенні, далі — хвіст. |
| Модуль для магазину | Розширення ставлять в адмінці магазину й вказують у ньому адресу шлюзу й токен. |
| Журнал приймань | Що створено чи знайдено з кожної заявки, або помилка текстом сервера. |

### Поля форми «Новий ключ API»

| Поле | Що це й на що впливає |
|---|---|
| Назва | Обовʼязкова, до 120 символів; за нею відрізняють ключі. |
| Права | Потрібне хоч одне; запит поза правами відхиляється. |
| Роль | Межа поверх прав; не обрано — «Менеджер». |
| Строк дії | Після дати ключ не працює; «Без строку» — доки не відкличуть. |
| Дозволити руйнівні дії для AI-клієнтів (MCP) | Лише для MCP-клієнтів: дає інструменти скасування й видалення; вмикається тільки при створенні. |

### Поля форми «Проба маршруту»

| Поле | Що це й на що впливає |
|---|---|
| Маршрут | Запит із порожнім тілом — справжній: маршрут запису створить запис. |
| Адреса сервера | Лише для прикладу curl; на сам запит не впливає. |

| Кнопка | Що це й на що впливає |
|---|---|
| Надіслати | Один запит у вашу живу компанію. |

| Розділ | Що це й на що впливає |
|---|---|
| Відповідь | Код, тіло відповіді й готова команда curl. |

### Поля налаштувань QuickBooks

| Поле | Що це й на що впливає |
|---|---|
| Коли надсилати документ | «Вручну» — лише кнопкою в картці рахунку. «Лише вже надіслані» (типово) — автоматично йдуть зміни рахунків, уже надісланих кнопкою. «Кожен рахунок від стану «Виставлено»» — ще й нові рахунки. Чернетки й скасовані не надсилаються ніколи. |
| Нумерація документів | «Номер із Krokul» потребує ввімкнених власних номерів документів у QuickBooks і номерів до 21 символу — інакше збереження відмовить з причиною. «Нумерує QuickBooks» — номер дає QuickBooks. |
| Рахунок доходу | Рахунок доходу QuickBooks для товарів і послуг, які Krokul створює там. Не обрано — товар не надсилається. |
| Позиція для рядків без товару | Позиція QuickBooks для рядків рахунку, не повʼязаних із товаром каталогу. Не обрано — рахунок із таким рядком не надсилається. |
| Ставки ПДВ → податкові коди | Для кожної ставки ПДВ Krokul — податковий код QuickBooks. Рахунок зі ставкою без коду не надсилається: податок не підставляється навмання. |

---

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