API та вебхуки MARREK: підключіть ШІ-консультанта до власного продукту
У MARREK зʼявилися публічний REST API та підписані вебхуки. Розповідаємо, як створити API-ключ, підписатися на події, які доступи можна дати інтеграції і як стежити за кожною доставкою в Журналі доставок.
MARREK відповідає вашим клієнтам в Instagram, Telegram і на сайті. Досі все, що він збирав, — діалоги, ліди, каталог, статистика — жило в кабінеті MARREK. Тепер із цими даними може працювати й ваше власне ПЗ: у MARREK зʼявилися публічний REST API і підписані вебхуки. Ваша CRM, ERP, BI-панель чи внутрішній сервіс можуть читати діалоги й відповідати клієнтам, синхронізувати ліди, керувати товарами та базою знань — і дізнаватися про кожне нове повідомлення в ту саму мить, коли воно зʼявилося.
Що можна зробити за допомогою API та вебхуків
- Передавати ліди в будь-яку CRM — навіть у ту, для якої в MARREK немає готової інтеграції.
- Відповідати зі своєї системи. Менеджери працюють у звичному інтерфейсі, а відповіді йдуть клієнту в Instagram чи Telegram через MARREK.
- Тримати каталог актуальним разом із вашим магазином чи складом: товари створюються, оновлюються й видаляються автоматично, тож ШІ завжди називає правильні ціни.
- Наповнювати базу знань з вашої вікі чи довідкового центру.
- Вивантажувати аналітику у вашу BI-систему поруч з іншими даними про продажі.
- Реагувати миттєво — вебхук про нового ліда може сповістити менеджера, створити задачу чи запустити повторний контакт.
Як створити API-ключ
API-ключ дозволяє вашому серверу звертатися до MARREK від вашого імені. Створюйте окремий ключ для кожної інтеграції — тоді його можна точно обмежити й відкликати, не зачіпаючи інших.
- У кабінеті MARREK відкрийте Розробникам → API-ключі і натисніть Створити ключ.
- Дайте йому зрозумілу назву, наприклад «Синхронізація з CRM».
- Оберіть доступ для кожної області: без доступу, читання або читання і запис. Шаблони Лише читання і Повний доступ заповнюють усе одним кліком.
- За бажанням обмежте ключ вибраними проєктами — наприклад, одним магазином із кількох — і вкажіть термін дії.
- Натисніть Створити і скопіюйте ключ (він починається з
mk_live_). Його показують лише один раз.
Далі ваш сервер передає ключ у заголовку Authorization: Bearer mk_live_…. У кабінеті видно, коли кожен ключ використовувався востаннє, а відкликати ключ можна будь-коли — він одразу перестає працювати.
Які доступи можна надати
Кожен ключ отримує рівно ті права, які ви йому дали, — окремо для кожної області. «Читання і запис» завжди включає «читання». Запит поза правами ключа відхиляється, тож помилка в одній інтеграції не зачепить дані, які їй не призначені.
| Область | Читання | Читання і запис |
|---|---|---|
| Діалоги | Переглядати діалоги й читати повідомлення | Надсилати відповіді та вкладення, позначати прочитаним, вмикати й вимикати ШІ, змінювати статус ліда |
| Ліди | Читати й експортувати ліди | Редагувати й видаляти ліди |
| Товари та категорії | Читати каталог | Створювати, редагувати й видаляти товари та категорії |
| База знань | Читати документи | Додавати документи й керувати ними |
| Налаштування ШІ | Читати промпт і поведінку | Змінювати промпт і поведінку |
| Аналітика | Читати статистику | — |
Давайте кожній інтеграції мінімум потрібного. Ключу, який лише передає дані у вашу BI-систему, достатньо Аналітика: читання.
Як підписатися на вебхуки
API дозволяє вам запитувати дані в MARREK, а вебхуки дозволяють MARREK самому повідомляти вам про події. Замість того щоб опитувати сервер кожні кілька секунд, ви отримуєте HTTPS-запит у ту мить, коли щось відбулося.
- Відкрийте Розробникам → Вебхуки і натисніть Додати ендпоінт.
- Вкажіть URL вашого сервера — публічну адресу
https://. - Оберіть події: усі (включно з тими, які ми додамо пізніше) або лише потрібні.
- Оберіть проєкти, події з яких має отримувати ендпоінт.
- Натисніть Створити і скопіюйте секрет підпису. Його показують один раз, і він дозволяє перевірити, що кожен запит справді від MARREK.
- Натисніть Надіслати тест, щоб переконатися, що ендпоінт відповідає, ще до справжніх подій.
| Подія | Коли надсилається |
|---|---|
message.received | Клієнт написав повідомлення (Telegram, Instagram, веб-віджет) |
message.sent | Створено відповідь — ШІ, менеджером або через API |
message.updated | Змінився статус доставки повідомлення або вкладення готове |
thread.created | Розпочався новий діалог |
thread.updated | Змінився статус діалогу, перемикач ШІ, відповідальний чи статус ліда |
lead.created | Отримано перші контактні дані клієнта |
lead.updated | Лід оновлено ШІ або відредаговано людиною |
lead.deleted | Лід видалено |
Кожен запит підписаний HMAC-SHA256 у заголовку X-Marrek-Signature, а тіло події має ту саму форму, що й відповідь REST API, — вивчати треба один формат, а не два. Події повідомлень також містять діалог, тож ви знаєте, хто написав, без додаткового запиту.
Журнал доставок: усі надіслані вебхуки як на долоні
Найскладніше у вебхуках — зрозуміти, що пішло не так: чи спрацювала подія, чи дійшла до сервера, що він відповів? У MARREK відповідь — на сусідній вкладці: Розробникам → Журнал доставок.
- Кожна подія, надіслана на ваші ендпоінти, — з типом, ендпоінтом, часом створення, кількістю спроб і HTTP-кодом, який повернув ваш сервер.
- Фільтри за ендпоінтом, статусом і подією, щоб швидко знайти потрібну доставку.
- Кожна спроба окремо — HTTP-статус, тривалість і відповідь вашого сервера.
- Точний вміст, який було надіслано, — зручно, коли налагоджуєте свій обробник.
- Надіслати знову одну доставку або Повторити пропущене для ендпоінта, щоб доставити все, що він не отримав.
| Статус | Що означає |
|---|---|
| У черзі / Надсилається | Подія чекає на відправку або надсилається просто зараз |
| Доставлено | Ваш сервер відповів статусом 2xx |
| Буде повтор | Тимчасова помилка (таймаут, 429, 5xx) — MARREK спробує ще раз автоматично |
| Відхилено | Ваш сервер відповів помилкою 4xx — це вважається проблемою налаштування, тож повтору не буде |
| Здались | Усі спроби повтору вичерпано |
| Пропущено | Подію не надсилали — наприклад, ендпоінт був вимкнений |
Тимчасові помилки повторюються з наростаючими паузами — до 10 спроб за 24 години. Якщо ендпоінт постійно відповідає помилками, MARREK ставить його на паузу, щоб не перевантажувати ваш сервер, і ви бачите це просто в кабінеті. Події зберігаються, тож після виправлення сервера все пропущене можна надіслати повторно.
Документація для розробників
Усе, що потрібно розробнику, — у відкритому доступі, без реєстрації:
- Інструкція з інтеграції — швидкий старт, автентифікація, проєкти, права доступу, помилки й ліміти, перевірка підпису вебхуків із готовими прикладами на PHP, Node.js і Python.
- Довідник API — кожен ендпоінт із параметрами, схемами та консоллю «Спробувати».
- Документ OpenAPI, який імпортується в Postman і працює з генераторами коду.
Часті запитання
Чи витрачає надсилання повідомлення через API ліміт ШІ-повідомлень?
Ні. Повідомлення, надіслане через API, рахується як повідомлення менеджера. Відповіді ШІ клієнтам рахуються як зазвичай.
Чи можна обмежити ключ одним проєктом?
Так. Створюючи ключ чи вебхук-ендпоінт, оберіть «Лише вибрані проєкти» і позначте ті, до яких він має доступ.
Що станеться, якщо я перейду на тариф без API?
Ключі та ендпоінти збережуться, але запити відхилятимуться, а вебхуки не надсилатимуться. Оновіть тариф, щоб повернути їх, і повторіть пропущене з Журналу доставок.
Чи є офіційний SDK для API?
Поки ні. Документ OpenAPI працює з генераторами, як-от openapi-generator, тож клієнт для вашої мови можна створити за кілька хвилин.
Підсумок
API та вебхуки перетворюють MARREK з окремого кабінету на частину вашої власної системи: ШІ-консультант спілкується з клієнтами, а ваше ПЗ отримує діалоги й ліди в реальному часі — рівно з тим доступом, який ви дозволили. Почніть з інструкції з інтеграції або подивіться, які готові підключення вже є, в огляді інтеграцій з CRM.



