Как подключить Битрикс24 к n8n через вебхук

Проще всего дать n8n доступ к Битрикс24 через входящий вебхук. Для него не нужно писать приложение и настраивать OAuth. Ниже настройка, примеры запросов к сделкам и приём событий из Битрикс24 в n8n.

Что понадобится

• Облачный Битрикс24. На бесплатном тарифе REST API и вебхуки ограничены, проверьте условия своего тарифа.
• Права администратора или разрешение создавать вебхуки.
• n8n на своём сервере с HTTPS, чтобы Битрикс24 мог отправлять события. Как его поставить, описано в инструкции.

Встроенного узла Битрикс24 в n8n нет. Пакеты от сообщества, например n8n-nodes-bitrix, n8n не проверяет. Мы работаем через HTTP Request.

Шаг 1. Создать входящий вебхук

1. Откройте Приложения → Разработчикам → Готовые сценарии → Другое → Входящий вебхук.
2. В правах доступа отметьте только нужные разделы. Для сделок и комментариев достаточно CRM (crm).
3. Сохраните и скопируйте адрес вебхука.

Если пункта нет, создание вебхуков вам не разрешено. Администратор включает его в Настройки → Настройки Битрикс24 → Безопасность → Интеграции Битрикс24, поле «Кому разрешить создавать входящие вебхуки».

Запросы через вебхук выполняются с правами сотрудника, который его создал. Вебхук администратора получит права администратора. Где возможно, создавайте вебхук от сотрудника с доступом только к нужным разделам CRM.

Код в адресе вебхука заменяет логин и пароль. Не публикуйте адрес. Если он утёк, удалите вебхук и создайте новый.

Шаг 2. Формат вызова методов

https://ВАШ_ПОРТАЛ.bitrix24.ru/rest/ID_ПОЛЬЗОВАТЕЛЯ/КОД_ВЕБХУКА/МЕТОД.json

Окончание .json можно не писать, JSON и так формат по умолчанию. В n8n используйте узел HTTP Request с методом POST и телом в формате JSON (Send Body → JSON).

Шаг 3. Создать сделку

curl -X POST "https://ВАШ_ПОРТАЛ.bitrix24.ru/rest/1/КОД/crm.deal.add.json" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "TITLE": "Заявка с сайта",
      "OPPORTUNITY": 15000,
      "CURRENCY_ID": "RUB",
      "CONTACT_IDS": [42],
      "ASSIGNED_BY_ID": 1
    },
    "params": { "REGISTER_SONET_EVENT": "N" }
  }'

В ответе поле result содержит ID новой сделки, в n8n это {{ $json.result }}. Параметр REGISTER_SONET_EVENT: N не пишет создание сделки в живую ленту.

Для crm.deal.add документация указывает «Развитие метода остановлено» и предлагает crm.item.add. Метод работает, но для новых сценариев удобнее универсальный вариант. Для сделок entityTypeId равен 2, а поля пишутся в camelCase:

{
  "entityTypeId": 2,
  "fields": {
    "title": "Заявка с сайта",
    "opportunity": 15000,
    "currencyId": "RUB",
    "contactIds": [42]
  }
}

ID сделки придёт в result.item.id.

Шаг 4. Получить список сделок

Метод crm.deal.list, тело запроса:

{
  "select": ["ID", "TITLE", "STAGE_ID", "OPPORTUNITY", "DATE_CREATE"],
  "filter": { ">=DATE_CREATE": "{{ $now.minus({ days: 1 }).toISO() }}" },
  "order": { "ID": "ASC" },
  "start": 0
}

В фильтре перед именем поля ставится оператор: >=, <, ! и другие. Метод отдаёт 50 записей за раз. В ответе есть total с общим числом и next со смещением для следующей страницы.

Пагинация в Options → Pagination:

• Pagination Mode: Update a Parameter in Each Request
• Type: Body, Name: start, Value: {{ $pageCount * 50 }}
• Pagination Complete When: Other
• Complete Expression: {{ !$response.body.next }}
• Interval Between Requests (ms): 500

Аналог на новых методах называется crm.item.list.

Шаг 5. Добавить комментарий в таймлайн

Метод crm.timeline.comment.add:

{
  "fields": {
    "ENTITY_ID": {{ $json.dealId }},
    "ENTITY_TYPE": "deal",
    "COMMENT": {{ JSON.stringify($json.summary) }}
  }
}

Ключ fields пишите строчными буквами. Варианты FIELDS или Fields этот метод не принимает. В result придёт ID комментария.

Шаг 6. Получать события в n8n

1. В n8n добавьте узел Webhook: метод POST, Respond: Immediately. Скопируйте Production URL и опубликуйте сценарий.
2. В Битрикс24 откройте Приложения → Разработчикам → Готовые сценарии → Другое → Исходящий вебхук.
3. Вставьте адрес и выберите событие, например ONCRMDEALADD, создание сделки. Сохраните токен приложения, который покажет Битрикс24.

Битрикс24 отправляет данные в формате application/x-www-form-urlencoded. n8n сохраняет такие ключи как есть, со скобками:

{{ $json.body['event'] }}
{{ $json.body['data[FIELDS][ID]'] }}
{{ $json.body['auth[application_token]'] }}

Первым после Webhook поставьте узел If и сравните auth[application_token] с сохранённым токеном. Запросы с другим токеном останавливайте.

Событие передаёт только ID сделки. Остальные данные получите запросом crm.item.get с entityTypeId: 2 и id. Подробнее о приёме событий в статье про вебхуки в n8n.

Шаг 7. Объединить запросы через batch

Метод batch выполняет до 50 команд за один вызов. Результат одной команды можно подставить в следующую через $result[имя]:

{
  "halt": 0,
  "cmd": {
    "deal": "crm.deal.add?fields[TITLE]={{ encodeURIComponent($json.title) }}",
    "comment": "crm.timeline.comment.add?fields[ENTITY_TYPE]=deal&fields[ENTITY_ID]=$result[deal]&fields[COMMENT]={{ encodeURIComponent($json.note) }}"
  }
}

Параметры внутри команд передаются строкой запроса, поэтому кириллицу и пробелы кодируйте через encodeURIComponent. Значение halt: 1 останавливает пакет на первой ошибке. Результаты лежат в result.result, ошибки в result.result_error.

Ограничения по частоте

Лимиты облачного Битрикс24 работают по принципу «дырявого ведра». Каждый запрос добавляет единицу к счётчику, а счётчик уменьшается каждую секунду.

При превышении приходит ошибка QUERY_LIMIT_EXCEEDED с кодом 503. Один запрос должен выполниться за 60 секунд. Есть ещё лимит на суммарное время работы метода: при его превышении приходит OPERATION_TIME_LIMIT с кодом 429. Подробности в документации Битрикс24.

На практике держите не больше 2 запросов в секунду и объединяйте операции через batch.

Частые ошибки

• Ошибка доступа к методу. В правах вебхука нет нужного раздела, например CRM.
• Видно только 50 сделок. Не настроена пагинация.
• Комментарий не создаётся. Ключ написан как FIELDS вместо fields.
• Пустые данные из события. В выражении $json.body.data.FIELDS.ID вместо ключа со скобками.
• 503 QUERY_LIMIT_EXCEEDED. Добавьте паузы между запросами или перейдите на batch.
• Персональные данные в Telegram. В уведомлениях отправляйте номер сделки и ссылку, без имён и телефонов. Подробнее в статье про 152-ФЗ.