Загрузка...

Блог

Дополнение к серии: Экосистема Adminica 2026

Adminica в CRM и порталах: API, webhooks и MAX

Adminica в CRM и порталах: API, webhooks и MAX

Команды в РФ часто собирают контур из CRM или портала, мессенджера MAX и внутренней базы знаний. Adminica закрывает RAG-слой: ответ по документам через API, события на ваш webhook и бот в MAX для сотрудников — без трёх разных продуктов.

Три канала — одна библиотека

КаналКомуТипичный сценарий
POST /api/v1/queryCRM, портал, скриптыКнопка «Справка по тикету» → ответ с источниками
Webhooks (POST /api/v1/webhooks)Ваш backendУведомление о готовом ответе, низком балансе, digest архива
MAX-бот из ЛКСотрудники в мессенджереБыстрый вопрос по runbook без открытия CRM
POST /chat/async + callback_urlДолгие диалогиОтвет приходит POST на URL CRM, не блокируя UI

Подробнее про MAX — в статье про бота MAX; про digest — scheduled queries.

Сценарий CRM: вопрос из тикета

  1. Пользователь нажимает «Подсказка из базы знаний» в карточке обращения.
  2. Ваш сервер вызывает POST /api/v1/query с API-ключом ak_… (ключ — Профиль → Безопасность).
  3. В теле запроса — текст тикета и при необходимости filters по разделу библиотеки.
  4. Ответ Adminica содержит текст и entries[] с источниками — показываете в CRM или сохраняете в комментарий.
POST /api/v1/query
Authorization: Bearer ak_YOUR_KEY
Content-Type: application/json

{
  "query": "Ошибка 502 на ingress nginx — что проверить по runbook?",
  "filters": { "section": "DevOps" }
}

Webhooks: события в вашу систему

Создайте подписку в ЛК или через API. Adminica доставляет POST на ваш HTTPS URL с подписью X-Adminica-Signature: sha256=<hmac>.

  • query.completed — после успешного /api/v1/query (удобно для аудита и метрик CRM).
  • chat.completed / chat.error — после async-чата.
  • tokens.low — остаток < 500 токенов (напоминание пополнить баланс).
  • digest.ready — «новое в архиве» по расписанию.
POST /api/v1/webhooks
{
  "url": "https://crm.example.com/hooks/adminica",
  "events": ["query.completed", "tokens.low"],
  "description": "Bitrix24 / внутренний портал"
}

Секрет из ответа 201 сохраните один раз — им проверяете HMAC от сырого тела запроса. Retry с backoff; доставки видны в админке (карточка webhook observability).

Async-чат с callback_url

Если ответ RAG занимает десятки секунд, не держите HTTP-соединение CRM: POST /chat/async с callback_url и опционально callback_secret. Adminica вернёт task_id, а по готовности отправит тот же JSON, что и webhook chat.completed.

Ограничения безопасности: только HTTPS в production, private IP и localhost заблокированы (SSRF).

MAX для полевых и дежурных

CRM хорош для учёта обращений, но дежурный чаще в чате. Подключите бота MAX — ответы по той же библиотеке, токены с баланса владельца интеграции. Для узкого контекста (один клиент, один проект) включите bot_enabled на персональной ссылке.

Практики интеграции

  • Разные API-ключи для staging и production; отзыв ключа в ЛК без смены пароля.
  • Логируйте X-Adminica-Delivery — id попытки доставки для разбора сбоев.
  • Для проактивного «что нового в архиве» — webhook на digest.ready + run_scheduled_queries.py по cron.
  • Не дублируйте RAG в CRM: один запрос к Adminica, в тикет — ссылка на источник из entries[].

Итог: CRM получает ответы через /api/v1/query и события через webhooks; MAX закрывает мессенджер; async-чат — длинные диалоги без таймаута. Всё на одной библиотеке знаний Adminica.