Інтеграції

Інтеграції — це місце, де ви підключаєте Looma до власних систем через публічний API: створюєте API-ключі, керуєте вихідними webhooks і знаходите готові інтеграції. Розділ розташований у бічній панелі (ролі Власник та Адміністратор) і потребує плану, який включає доступ до API.

Хто може користуватися API

Сторінка Інтеграції доступна лише ролям Власник та Адміністратор. Крім того, ваш план повинен включати функцію доступу до API. Якщо ваш поточний план її не включає або термін підписки минув, сторінка замінює інструменти API на пропозицію оновити план із посиланням на Білінг — оберіть або реактивуйте план із доступом до API, щоб розблокувати ключі та webhooks. Усе нижче передбачає, що функція активна.

API-ключі

Відкрийте Інтеграції → API. Темна шапка вгорі показує Базову адресу API (https://api.looma.chat/v1/) з кнопкою Скопіювати й посилання на документацію: Швидкий старт, Автентифікація, Вебхуки та Помилки й ліміти. Під нею, на під-вкладці Ключі, — список ваших ключів.

Натисніть Створити API-ключ і заповніть:

• Назва ключа — внутрішня позначка, щоб розрізняти ключі (наприклад, «Production» чи «Мій додаток»).
• Дозволи — по картці на кожну область доступу (scope) з назвою й кодом. Для нового ключа відмічені всі десять; Вибрати все й Очистити перемикають їх разом. Якщо не лишити жодного, ключ отримає Повний доступ.
• Доступ до сайтів — Всі сайти (без обмежень) або Тільки обрані сайти, а далі відмітьте потрібні сайти-чипи.
• Термін дії — Безстроковий, 30 днів, 90 днів, 1 рік або Довільна дата в календарі.

Повний секрет ключа показується лише один раз — у вікні API-ключ створено («Скопіюйте цей ключ зараз. Ви більше не зможете його побачити.») разом із прикладом Перший запит. Скопіюйте його там, збережіть надійно й підтвердьте кнопкою Я зберіг ключ. Згодом Looma показує тільки префікс ключа (наприклад, lm_xxx); сам секрет зберігається як хеш і не може бути отриманий повторно. Якщо ви його втратили, відкличте ключ і створіть новий.

Таблиця ключів показує для кожного ключа назву й дату створення, префікс (перші вісім символів, як-от lm_7Kq2a…), дозволи (перші два й лічильник «+N»), сайти, Останнє використання (Ніколи, якщо ключем ще не користувалися) і статус — Активний, Відкликаний або Прострочений. У рядку можна:

• Редагувати активний ключ — змінити назву, дозволи й сайти. Термін дії після створення не змінюється: для іншого терміну створіть новий ключ.
• Відкликати ключ — усі запити з ним одразу перестають працювати, скасувати це не можна. Прострочений ключ теж можна відкликати; відкликаний лишається в таблиці сірим.

Доступні області доступу (scopes)

Області доступу (scopes) визначають, що дозволено робити API-ключу. Ваш розробник обирає scopes, потрібні його інтеграції. Ключ без обмеження області доступу має Повний доступ. Інакше ви надаєте набір із цих десяти scopes:

• leads:read — читати зібрані ліди.
• leads:write — створювати або оновлювати ліди.
• chats:read — читати чат-сесії та повідомлення.
• chats:write — надсилати повідомлення та змінювати стан чату.
• products:read — читати каталог товарів.
• visitors:read — читати події та сесії відвідувачів.
• visitors:write — записувати події відвідувачів.
• sites:read — читати дані сайту. Ендпоінти каналів покриваються цією областю доступу — окремого scope channels немає.
• balance:read — читати ваш баланс кредитів.
• webhooks:manage — створювати, редагувати та видаляти webhooks через API.

Webhooks

На під-вкладці Вебхуки розділу Інтеграції → API ви реєструєте ендпоінти, які Looma викликає, коли у вашому акаунті щось відбувається. Натисніть Створити вебхук і заповніть:

• URL ендпоінту — адреса вашого сервера, наприклад https://your-app.com/webhook.
• Опис — необовʼязковий, для вас самих.
• Оберіть події для підписки — по картці на подію з коротким поясненням; для нового вебхука відмічені всі три.
• Фільтр сайтів — Всі сайти або Тільки конкретні сайти.

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

Рядок вебхука показує адресу, події, статус (Активний або Вимкнений, а також червоний лічильник помилок, якщо останні доставки не вдалися) й Останнє використання. Кнопки рядка:

• Тест — надсилає зразкову доставку; сповіщення скаже «Тестова доставка успішна» з часом відповіді або «Тестова доставка невдала» з причиною (наприклад, HTTP-кодом, який повернув ваш сервер).
• Доставки — журнал останніх спроб: подія, статус (success, failed або pending), код HTTP, який повернув ваш сервер, Час відповіді й Дата. Невдала спроба з «—» у колонці HTTP означає, що сервер не відповів зовсім.
• Редагувати — змінити адресу, опис, події або вимкнути й знову ввімкнути вебхук. Фільтр сайтів задається лише під час створення.
• Видалити — прибирає вебхук разом з усією історією доставок.

Якщо ваш тариф перестав включати доступ до API або підписка завершилась, на під-вкладці з'являється банер Події не доставляються: вебхуки лишаються «Активними», але нічого не отримують, доки ви не оновите чи не поновите тариф.

Деталі підпису нижче призначені для розробника, який створює ваш ендпоінт — ви можете передати йому цей розділ.

Кожна доставка підписується, щоб ви могли переконатися, що вона справді надійшла від Looma. Looma надсилає POST із цими заголовками:

• X-Looma-Event — назва події (наприклад, lead.created).
• X-Looma-Delivery — унікальний ID доставки.
• X-Looma-Timestamp — Unix-мітка часу, використана в підписі.
• X-Looma-Signature — sha256=<hmac>, де <hmac> — це HMAC-SHA256(timestamp + "." + rawBody, webhook_secret).

Щоб перевірити автентичність на своєму боці: візьміть значення X-Looma-Timestamp, з'єднайте його з . та сирим тілом запиту, обчисліть HMAC-SHA256 із секретом вашого webhook, додайте до результату префікс sha256= і порівняйте його (з використанням порівняння за сталий час) із X-Looma-Signature.

Події webhook

Це три події, на які ви можете підписати webhook у інтерфейсі:

• lead.created — захоплено новий лід.
• chat.started — відвідувач відкриває розмову.
• chat.message.new — у чаті опубліковано нове повідомлення.

Один webhook може слухати будь-яку комбінацію з них, а фільтр сайтів, який ви задаєте при створенні webhook, обмежує, які сайти його запускають.

Ліміти запитів

Публічний API має обмеження запитів на кожен ключ у ковзному одно­хвилинному вікні. Кожна відповідь API несе три заголовки, щоб ви могли регулювати темп запитів:

• X-RateLimit-Limit — максимальна кількість запитів, дозволена у вікні.
• X-RateLimit-Remaining — скільки запитів у вас залишилося в поточному вікні.
• X-RateLimit-Reset — коли вікно скидається.

Ліміт на ключ визначається вашим планом та конфігурацією ключа, а не фіксованим глобальним числом, тож читайте заголовок X-RateLimit-Limit, щоб дізнатися значення, яке застосовується до конкретного ключа. Коли ліміт перевищено, запити відхиляються, доки вікно не скинеться.

Готові інтеграції

Перша верхня вкладка, Готові інтеграції, — це каталог заздалегідь зібраних конекторів до платформ магазинів, CRM і сервісів автоматизації. Кожна картка має брендову обкладинку, прапори країн, теги можливостей, короткий опис, кількість уже підключених сайтів (Підключено сайтів: N) і кнопку Налаштувати підключення, що відкриває власну сторінку конектора.

Конектор	Тип	Теги на картці	Посібник
Horoshop	магазин	Каталог товарів, Замовлення	Пряме підключення магазину
OpenCart	магазин	Каталог товарів, Сторінки сайту	Пряме підключення магазину
KeyCRM	CRM	Ліди	KeyCRM
SalesDrive	CRM	Ліди	SalesDrive
KeepinCRM	CRM	Ліди	KeepinCRM
Zapier	автоматизація	Ліди	Zapier
WooCommerce	магазин	Каталог товарів, Замовлення	позначений як Скоро, його кнопка вимкнена

Теги показують, що конектор справді робить сьогодні: Каталог товарів (товари надходять із магазину, без фіду), Замовлення (замовлення потрапляють в аналітику), Сторінки сайту (сторінки магазину зчитуються) і Ліди (ліди Looma доставляються в CRM як угоди чи заявки або запускають Zap у Zapier).

Картка Zapier влаштована інакше: на боці Looma підключати нічого, тож замість «Налаштувати підключення» на ній три кроки, кнопка Створити API-ключ (відкриває форму ключа з уже позначеними скоупами, які потрібні Zapier) і Відкрити в Zapier. Докладно — Zapier.

Фільтри каталогу

• Країна — Усі країни, Україна або Увесь світ. Horoshop, KeyCRM, SalesDrive і KeepinCRM позначені як Україна; OpenCart, Zapier і WooCommerce мають обидва прапори.
• Чипи можливостей — Усі та по одному чипу на кожен тег, кожен із живим лічильником. Чип, для якого в обраній країні немає конекторів, приховується.

Обидва фільтри поєднуються, а лічильники відповідають обраній країні.

Повна довідка API

Щодо ендпоінтів, схем запитів і відповідей та прикладів коду використовуйте повну довідку API на docs.looma.chat — те саме призначення, що й банер документації на вкладці API. Автентифікуйте кожен запит вашим API-ключем у заголовку Authorization як Bearer-токен: Authorization: Bearer lm_xxx. Надсилайте сирий ключ (повний секрет, показаний один раз при створенні), а не префікс.

Пов'язане

• Канали — підключення месенджерів (ендпоінти каналів використовують область доступу sites:read)
• Ліди — ліди, що доставляються webhook lead.created
• Чати — розмови за подіями chat.started та chat.message.new
• Пряме підключення магазину, KeyCRM, SalesDrive, KeepinCRM, Zapier — готові конектори
• Білінг та платежі — плани, що включають доступ до API