Битрикс24 REST API: как связать портал со своим сервисом

Если вашему сервису нужно передавать заявки в Битрикс24, первый рабочий результат можно получить за час: создать входящий вебхук, отправить один REST-запрос и проверить появление лида в CRM. Но вебхук подходит только для одного портала и ограниченного набора операций. Для SaaS, который подключает разных клиентов, нужна OAuth-интеграция с хранением токенов и обработкой их обновления.

Сначала выберите схему подключения

У Битрикс24 нет единой «кнопки интеграции со своим сервисом». Способ зависит от того, кто владеет порталом и сколько порталов вы подключаете.

Практическое правило: внутренний обмен данными между вашим сервисом и собственным порталом начинайте с вебхука. Если пользователи сами подключают разные Битрикс24, сразу проектируйте OAuth. Переписывать вебхук в многопользовательскую авторизацию после запуска обычно дороже, чем сразу заложить отдельное хранилище подключений.

Вебхук — это не «маленький OAuth». Это постоянный секрет в URL с фиксированными правами. Относитесь к нему как к паролю от интеграции.

Вебхук — URL, в котором Битрикс24 хранит идентификатор пользователя и секретный код доступа. Любой, кто получил такой URL, может выполнять разрешённые ему REST-методы.

Быстрый запуск через входящий вебхук

Ниже — схема для облачного Битрикс24 и REST API, доступного на момент публикации. У REST API нет единого номера версии наподобие «5.2»: набор методов, права и параметры нужно сверять в официальной документации конкретного портала. Для коробочной версии дополнительно учитывайте версию установленного продукта и настройки сервера.

1. Создайте вебхук

В Битрикс24 откройте раздел разработчика и создайте входящий вебхук. Интерфейс может отличаться по тарифу и обновлению портала, поэтому ориентируйтесь на раздел REST и пункт для входящего вебхука. Выберите права, которые действительно нужны сервису: для создания лида достаточно доступа к CRM, а права на пользователей, задачи или диски добавлять не следует.

После создания портал покажет URL вебхука. Скопируйте его в менеджер секретов, а не в исходный код, задачу в трекере или общий чат. Проверка шага: у вас есть адрес портала, идентификатор пользователя, код вебхука и список разрешённых методов.

2. Проверьте соединение безопасным методом

Сначала вызовите метод, который возвращает данные текущего пользователя. Это отделяет проблему авторизации от ошибки в полях CRM. Пример запроса с замените URL на значение из своего портала:

curl --request POST \
  --url 'https://YOUR_PORTAL.bitrix24.ru/rest/USER_ID/WEBHOOK_CODE/user.current.json'

В ответе должен прийти JSON с объектом result и данными пользователя. Если вместо него возвращается error, не переходите к CRM: сначала исправьте URL, код вебхука или права.

3. Создайте тестовый лид

Метод crm.lead.add принимает поля лида и возвращает его идентификатор. В примере используется Node.js 20 и стандартный fetch, поэтому отдельный HTTP-пакет не нужен. Данные передаются как application/x-www-form-urlencoded — такой формат удобен для вложенных полей REST API.

const portalUrl = 'https://YOUR_PORTAL.bitrix24.ru';
const userId = 'USER_ID';
const webhookCode = 'WEBHOOK_CODE';

const endpoint = `${portalUrl}/rest/${userId}/${webhookCode}/crm.lead.add.json`;

const fields = new URLSearchParams({
  'fields[TITLE]': 'Тестовая заявка из внешнего сервиса',
  'fields[NAME]': 'Иван',
  'fields[PHONE][0][VALUE]': '+79990000000',
  'fields[PHONE][0][VALUE_TYPE]': 'WORK'
});

const response = await fetch(endpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: fields
});

const data = await response.json();

if (!response.ok || data.error) {
  throw new Error(`${data.error || response.status}: ${data.error_description || 'REST request failed'}`);
}

console.log('Created lead ID:', data.result);

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

Как перейти от теста к рабочему обмену

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

Храните внешний идентификатор

Записывайте в своей базе идентификатор созданного лида из поля result. Если бизнес-процесс допускает повторную отправку, сохраняйте также собственный идентификатор заявки и связывайте его с сущностью Битрикс24. Иначе повтор после тайм-аута может создать второй лид, хотя первый запрос уже успел выполниться.

Разделяйте ошибки

• Ошибка авторизации. Проверьте URL вебхука, идентификатор пользователя и секрет. Не повторяйте запрос бесконечно: новый вызов с тем же неверным секретом ничего не изменит.
• Недостаточно прав. Вебхук может быть действительным, но не иметь доступа к нужному REST-методу или CRM-сущности. Вернитесь к настройкам прав и убедитесь, что метод разрешён для пользователя вебхука.
• Ошибка в поле. Битрикс24 может отвергнуть неизвестное поле, неверный формат телефона или обязательное поле конкретного портала. Сверяйте название и тип каждого поля с документацией метода.
• Временный сбой или ограничение частоты. Увеличьте интервал между повторами, используйте очередь и ограничьте число попыток. Повторяйте только операции, для которых вы понимаете риск дубля.

Не передавайте секрет через фронтенд

Запрос к REST API должен выполнять ваш сервер. Если вставить URL вебхука в JavaScript страницы, его увидит любой посетитель через исходный код или инструменты разработчика. Для браузерного приложения используйте свой backend-прокси: фронтенд передаёт ему заявку, а секретный запрос к Битрикс24 выполняется на сервере.

Когда нужен OAuth 2.0

OAuth выбирайте, если подключение инициирует клиент, а ваш сервис не должен знать пароль от Битрикс24. Пользователь проходит авторизацию на стороне портала, разрешает приложению запрошенные права, после чего ваш callback получает временный код. Сервер меняет этот код на токены и хранит их отдельно для каждого портала.

Минимальная модель данных для подключения выглядит так:

• идентификатор портала;
• идентификатор пользователя или приложения, если он нужен выбранному сценарию;
• токен доступа и срок его действия;
• токен обновления, если его возвращает выбранный OAuth-сценарий;
• дата последней успешной проверки и статус подключения.

Токены нельзя хранить в cookie без защиты, в открытых логах и в таблице заявок. При ошибке авторизации сервис должен один раз попробовать обновить токен, а затем перевести подключение в состояние «требуется повторная авторизация». Не запускайте бесконечный цикл обновления: он быстро превращается в поток бесполезных запросов.

Что ломается на границе интеграции

Главная проблема — разница между моделью данных вашего сервиса и моделью CRM. Внешняя заявка может иметь один телефон, а в Битрикс24 телефон представлен массивом значений с типом. Статусы, ответственные, воронки и пользовательские поля также могут отличаться между порталами.

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

События и исходящие уведомления — отдельная тема: здесь рассматривается только вызов REST API из вашего сервиса. Если нужно получать изменения из CRM, проектируйте обработчик событий, повторную доставку и защиту от повторной обработки отдельно.

Что сделать дальше

После первого успешного лида добавьте журнал запросов без секретов, корреляционный идентификатор и метрики: долю успешных вызовов, количество повторов, время ответа и число ошибок по кодам. Затем протестируйте сценарии с пустым телефоном, неизвестным статусом, недоступным порталом и повторной отправкой одной заявки. Для публичной интеграции переходите с вебхука на OAuth и ограничьте права приложения минимальным набором методов.