Продукт

API та вебхуки MARREK: підключіть ШІ-консультанта до власного продукту

У MARREK зʼявилися публічний REST API та підписані вебхуки. Розповідаємо, як створити API-ключ, підписатися на події, які доступи можна дати інтеграції і як стежити за кожною доставкою в Журналі доставок.

Команда MARREK6 хв читання

MARREK відповідає вашим клієнтам в Instagram, Telegram і на сайті. Досі все, що він збирав, — діалоги, ліди, каталог, статистика — жило в кабінеті MARREK. Тепер із цими даними може працювати й ваше власне ПЗ: у MARREK зʼявилися публічний REST API і підписані вебхуки. Ваша CRM, ERP, BI-панель чи внутрішній сервіс можуть читати діалоги й відповідати клієнтам, синхронізувати ліди, керувати товарами та базою знань — і дізнаватися про кожне нове повідомлення в ту саму мить, коли воно зʼявилося.

Що можна зробити за допомогою API та вебхуків

  • Передавати ліди в будь-яку CRM — навіть у ту, для якої в MARREK немає готової інтеграції.
  • Відповідати зі своєї системи. Менеджери працюють у звичному інтерфейсі, а відповіді йдуть клієнту в Instagram чи Telegram через MARREK.
  • Тримати каталог актуальним разом із вашим магазином чи складом: товари створюються, оновлюються й видаляються автоматично, тож ШІ завжди називає правильні ціни.
  • Наповнювати базу знань з вашої вікі чи довідкового центру.
  • Вивантажувати аналітику у вашу BI-систему поруч з іншими даними про продажі.
  • Реагувати миттєво — вебхук про нового ліда може сповістити менеджера, створити задачу чи запустити повторний контакт.

Як створити API-ключ

API-ключ дозволяє вашому серверу звертатися до MARREK від вашого імені. Створюйте окремий ключ для кожної інтеграції — тоді його можна точно обмежити й відкликати, не зачіпаючи інших.

  1. У кабінеті MARREK відкрийте Розробникам → API-ключі і натисніть Створити ключ.
  2. Дайте йому зрозумілу назву, наприклад «Синхронізація з CRM».
  3. Оберіть доступ для кожної області: без доступу, читання або читання і запис. Шаблони Лише читання і Повний доступ заповнюють усе одним кліком.
  4. За бажанням обмежте ключ вибраними проєктами — наприклад, одним магазином із кількох — і вкажіть термін дії.
  5. Натисніть Створити і скопіюйте ключ (він починається з mk_live_). Його показують лише один раз.

Далі ваш сервер передає ключ у заголовку Authorization: Bearer mk_live_…. У кабінеті видно, коли кожен ключ використовувався востаннє, а відкликати ключ можна будь-коли — він одразу перестає працювати.

Які доступи можна надати

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

Області доступу API і що дозволяє кожен рівень
ОбластьЧитанняЧитання і запис
ДіалогиПереглядати діалоги й читати повідомленняНадсилати відповіді та вкладення, позначати прочитаним, вмикати й вимикати ШІ, змінювати статус ліда
ЛідиЧитати й експортувати лідиРедагувати й видаляти ліди
Товари та категоріїЧитати каталогСтворювати, редагувати й видаляти товари та категорії
База знаньЧитати документиДодавати документи й керувати ними
Налаштування ШІЧитати промпт і поведінкуЗмінювати промпт і поведінку
АналітикаЧитати статистику—

Давайте кожній інтеграції мінімум потрібного. Ключу, який лише передає дані у вашу BI-систему, достатньо Аналітика: читання.

Як підписатися на вебхуки

API дозволяє вам запитувати дані в MARREK, а вебхуки дозволяють MARREK самому повідомляти вам про події. Замість того щоб опитувати сервер кожні кілька секунд, ви отримуєте HTTPS-запит у ту мить, коли щось відбулося.

  1. Відкрийте Розробникам → Вебхуки і натисніть Додати ендпоінт.
  2. Вкажіть URL вашого сервера — публічну адресу https://.
  3. Оберіть події: усі (включно з тими, які ми додамо пізніше) або лише потрібні.
  4. Оберіть проєкти, події з яких має отримувати ендпоінт.
  5. Натисніть Створити і скопіюйте секрет підпису. Його показують один раз, і він дозволяє перевірити, що кожен запит справді від MARREK.
  6. Натисніть Надіслати тест, щоб переконатися, що ендпоінт відповідає, ще до справжніх подій.
Події, на які можна підписатися
ПодіяКоли надсилається
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.

Запустіть ШІ-консультанта у своєму бізнесі

Підключіть Telegram, Instagram або сайт, завантажте каталог — і MARREK відповідатиме клієнтам 24/7. 7 днів безкоштовно.