Интеграция с Bitrix24: пошагово для AI-агента

Интеграция с Bitrix24 через REST API: входящий вебхук, crm.item.add, события, лимиты и ошибки. С примерами.

У агента интеграция с bitrix24 упирается в один вопрос: откуда он берёт доступ. Остальное — механика: вызовы вроде crm.item.add да подписка на события.

Дальше — только по официальной документации Битрикс24: REST API, вебхуки, лимиты. Каждое утверждение сверено с разделами для разработчиков.

Шаг 1. Доступ: входящий вебхук или приложение

Механизмов доступа у Битрикс24 два. Их постоянно путают.

Входящий вебхук — самый короткий путь. В ссылке лежит адрес портала, /rest, номер пользователя и секретный код. Метод приписывается в конец: https://example.bitrix24.ru/rest/1/xxxxxxxx/crm.item.add.json.

Права вебхука ограничены scope, который вы отметили при создании, и правами сотрудника. Некоторым методам нужен контекст приложения — через вебхук их не вызвать. Проверять это лучше до старта, а не в день запуска.

• Создать отдельного сотрудника под агента — не работать от аккаунта директора
• Отметить только нужные scope: crm, tasks, im
• Ссылку вебхука хранить как пароль: она даёт доступ к порталу
• Проверить метод простым GET в браузере до написания кода

Шаг 2. Методы: crm.lead.add устарел

О чём часто забывают: crm.lead.add помечен как DEPRECATED. Документация говорит прямо — метод больше не развивают, переходите на crm.item.add.

crm.item.add принимает любой тип объекта CRM. Обязательные параметры:

Так выглядят значения entityTypeId для системных типов. Для смарт-процесса идентификатор получают через crm.type.list.

curl -X POST "https://example.bitrix24.ru/rest/1/xxxxxxxx/crm.item.add.json" \
  -H "Content-Type: application/json" \
  -d '{
    "entityTypeId": 1,
    "fields": {
      "title": "Заявка с сайта — Иван",
      "name": "Иван",
      "comments": "Просит расчёт забора, 40 метров"
    }
  }'

Второй параметр — fields, объект с полями сущности. Коды полей зависят от настроек портала. Часть полей пользовательские, их имена надо запрашивать, а не угадывать.

1. Узнать поляЗапросить описание полей нужного типа и сохранить карту кодов.
2. Создать элементcrm.item.add с entityTypeId и полями.
3. СвязатьПривязать контакт и компанию к сделке через методы связей.
4. Добавить задачуtasks.task.add с ответственным и сроком.
5. Записать итогКомментарий или дело в таймлайне: что агент сделал и что ответил.

Для массовых операций пригодится batch: несколько вызовов в одном HTTP-запросе. Так быстрее и легче попасть в лимиты.

Шаг 3. События: где чаще всего ошибаются

Вот главная ловушка. event.bind регистрирует обработчик, но только в контексте авторизации приложения. Из входящего вебхука метод ответит ошибкой WRONG_AUTH_TYPE.

То есть одним вебхуком на события через event.bind не подписаться. Выходов два:

• собрать приложение и подписывать события уже из него;
• завести исходящий вебхук в интерфейсе портала.

Исходящий вебхук шлёт событие POST-запросом на ваш обработчик. Документация ставит условия: адрес доступен из интернета, в имени хоста есть точка. Поэтому localhost отпадает.

Ещё пара деталей оттуда же:

• Не админу офлайн-события недоступны: подписка с event_type=offline отдаст ACCESS_DENIED.
• Удаляете приложение — обработчики удаляются вместе с ним, обновляете — остаются. За повторную регистрацию того же обработчика прилетит ERROR_CORE. Значит, перед регистрацией смотрят текущие через event.get.

Без подписки на события интеграции нет. Код события передают строкой, скажем ONCRMLEADADD — этот пример есть в документации метода event.bind. Список доступных событий отдаёт метод events. Сверяйтесь с ним, а не с чужими статьями: набор зависит от scope и версии портала.

Событие — сигнал, не карточка. В обработчик обычно приходят идентификаторы, а сами данные агент дочитывает отдельным методом.

Шаг 4. Лимиты

REST API Bitrix24 ограничивает не только частоту обращений, но и время выполнения запроса.

Лимит интенсивности устроен как Leaky Bucket: короткий всплеск допустим, постоянная нагрузка — нет. Запрос дольше 60 секунд обрывается по таймауту. Отсюда правило: большие выборки режут на страницы и не тянут лишние поля.

В коробочной версии лимиты задаются на сервере. Правила там свои, спрашивать их у администратора портала.

Шаг 5. Ошибки, которые агент должен понимать

• WRONG_AUTH_TYPE — метод требует приложения, а вызван через вебхук
• ACCESS_DENIED — не хватает прав или scope
• ERROR_EVENT_NOT_FOUND — событие не входит в scope приложения
• ERROR_CORE — обработчик уже зарегистрирован

Правило простое. Ошибку авторизации не повторяем. Ошибку лимита — повторяем с паузой. Ошибку данных — отдаём человеку. Агент, который пять раз подряд долбится в 401, создаёт только видимость работы.

Интеграция с Bitrix24: что делает агент

Ловит событие о новой заявке, подтягивает данные, ищет дубль по телефону, создаёт элемент CRM нужного типа, цепляет контакт, ставит задачу менеджеру, оставляет комментарий с резюме и отвечает клиенту в том канале, откуда он пришёл.

Стартовать лучше с одного типа сущности и одного события. Расширяться — после недели без расхождений.

Общая схема и сравнение с amoCRM — в статье интеграция AI-агента с CRM. Когда сервисов больше двух, нужен агент-интегратор: он держит связки и следит за обрывами.

Сергей ЕзепенкоИнтеграция с Bitrix24

Настрою интеграцию агента с Bitrix24: лиды, сделки, уведомления. Бесплатная диагностика — 30 минут.

Написать в TelegramНаписать в MAX