Інтеграції

1. Огляд інтерфейсу

Сторінка /settings/integrations показує картки доступних провайдерів: Meta Lead Ads, Telegram-бот. Підключені відображаються зі статусом active і доступом до конфігурації; неактивні — кнопкою «Підключити».

У сусідніх розділах:

• /settings/api-keys — список API-ключів тенанта.
• /settings/api-docs — інтерактивна документація REST API.

2. Meta Lead Ads

Інтеграція забирає заявки з форм Lead Ads на Facebook / Instagram у режимі реального часу. Кожен новий лід попадає в розділ /leads із джерелом Meta Ads та посиланням на оригінальну форму.

Послідовність підключення:

1. Натисніть «Підключити» на картці Meta Lead Ads.
2. Авторизуйтесь у Facebook (OAuth) і дайте дозвіл на читання сторінок.
3. Оберіть Facebook-сторінку, з якою працюєте.
4. Налаштуйте field mapping — які поля з форми в які поля ліда писати.

3. Telegram-бот

На картці Telegram-бот можна підключити одного або кілька ботів. Кожен бот обслуговує свою аудиторію — наприклад, окремі боти для гарячої лінії і для підтримки.

Як підключити:

1. У @BotFather Telegram створіть бота, отримайте BOT_TOKEN.
2. У TurboCRM натисніть «+ Додати бот», вставте токен.
3. Система автоматично налаштує webhook на свій endpoint і поверне статус.

Усі повідомлення від користувачів бота попадають у розділ «Розмови», а нові звернення створюють лід (якщо контакт ще не звʼязаний).

4. API-ключі

REST API /api/v1/* захищене Bearer-токеном. У розділі /settings/api-keys ви можете:

• Створити новий ключ — система згенерує токен sk_live_… і покаже його один раз (далі тільки відбиток).
• Подивитися дату останнього використання.
• Відкликати ключ у будь-який момент — токен перестає працювати.

Доступ єдиний — будь-який валідний ключ дає повний доступ до всіх ресурсів API (ліди, клієнти, угоди, товари, задачі). Поділу за scope-ами немає; рядкові права (own / team / all) визначаються роллю користувача, який створив ключ.

# Приклад: створити лід
curl -H "Authorization: Bearer sk_live_…" \
     -H "Content-Type: application/json" \
     -d '{"name":"Іван","phone":"+380501234567","tags":["website"]}' \
     https://acme.turbocrm.com.ua/api/v1/leads

5. API-документація

/settings/api-docs — інтерактивна документація з розгортанням кожного endpoint, прикладами curl і таблицею HTTP-кодів. Завантаження:

• Markdown (.md) — повний референс, який можна одразу віддати ChatGPT/Claude/іншому LLM для побудови інтеграції.
• OpenAPI 3.0 (.yaml) — імпорт у Postman, Insomnia, openapi-generator.

Покриті ресурси:

• /api/v1/leads — повний CRUD + /convert
• /api/v1/clients — повний CRUD + nested /contacts
• /api/v1/deals — повний CRUD + items + переходи стадій /stage, /won, /lost
• /api/v1/products — повний CRUD у структурі Google Merchant (gtin, brand, status, availability, sale_price, мульти-валюта), nested /images, швидке оновлення залишку /availability, public Google feed /products.xml, CSV import/export
• /api/v1/tasks — повний CRUD + /complete
• Довідники: /pipelines, /lead-sources, /lead-statuses, /client-statuses, /deal-lost-reasons, /users, /tags, /task-meta

Теги. Будь-який ресурс приймає tags: [string]. Невідомі імена автоматично створюються в довіднику тегів — їх не треба резолвити заздалегідь.

Помилки валідації. Будь-який 422 повертає стандартну форму з полем errors, де ключ — назва поля, значення — масив повідомлень.

{
  "error": "ValidationException",
  "message": "The given data was invalid.",
  "status": 422,
  "errors": {
    "name": ["The name field is required."],
    "email": ["The email must be a valid email address."]
  }
}

6. Outbound webhooks

Webhooks — це HTTP-callback'и у ваші системи на події в TurboCRM. Наприклад, при появі нового ліда відправити POST у Zapier / Make / власний скрипт.

Підтримувані події:

• lead.created, lead.converted, lead.status_changed
• deal.created, deal.stage_changed, deal.won, deal.lost
• task.created, task.completed, task.overdue

Кожен webhook підписується HMAC-SHA256 — у заголовку X-TurboCRM-Signature: sha256=…; ваш приймач має звіряти підпис із секретом, заданим при створенні webhook. У логах /settings/integrations → Webhooks → Logs видно усі спроби, відповіді (200/500) і retry-полицю. Після 10 підряд провалів вебхук авто-вимикається.

7. Імпорт історичних лідів Meta

Після підключення Meta Lead Ads є кнопка «Імпортувати історичні» — забирає лідів за останні 90 днів (обмеження Meta API). Корисно при першому підключенні, щоб не починати з порожньої воронки.

8. Хто може налаштовувати

Доступ до всього розділу контролюється permission settings.integrations.manage. За замовчуванням є тільки в owner та admin. Manager / viewer не бачать пункту меню «Інтеграції».

9. Часті запитання