Интеграции

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, публичный 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. Частые вопросы