Интеграция Битрикс24 с сайтом: лиды, сделки и автоматизация

Интеграция Битрикс24 с сайтом — это не просто установка формы обратной связи. Это настройка двустороннего обмена данными через REST API, вебхуки и CommerceML, с контролем OAuth-токенов, кэшированием через Redis и асинхронной обработкой через RabbitMQ. В статье — конкретные протоколы, конфигурации серверов и чек-лист для внедрения.

Архитектура интеграции: протоколы и потоки данных

Любая интеграция Битрикс24 с сайтом строится на трёх уровнях: транспорт (HTTP/HTTPS), аутентификация (OAuth 2.0, JWT) и формат данных (JSON, XML для CommerceML). Для синхронизации лидов и сделок используется REST API Битрикс24 (crm.lead.add, crm.deal.add). Для товаров и каталогов — CommerceML (XML-обмен).

Ключевой момент: OAuth-токен живёт 3600 секунд (1 час). Без его ротации через refresh_token интеграция сломается. В production мы храним токены в Redis с TTL, а refresh-запросы отправляем асинхронно через RabbitMQ, чтобы не блокировать пользовательский запрос.

Способы интеграции: лид-формы, вебхуки, кастомное API

Выбор метода зависит от задач:

• Лид-формы Битрикс24 — готовый виджет, встраивается на сайт через iframe или JS. Минимум кода, но нет гибкости: нельзя добавить кастомные поля или валидацию.
• Вебхуки (входящие/исходящие) — простой способ отправлять данные из сайта в CRM по URL. Не требует OAuth, но ограничен 50 запросами в минуту на один вебхук.
• Кастомное API (REST + OAuth) — полный контроль: создание лидов, сделок, контактов, привязка файлов, работа с бизнес-процессами. Требует серверной логики и управления токенами.

Сравнение методов интеграции

Пошаговая инструкция: настройка интеграции через REST API (чек-лист)

1. Зарегистрировать приложение в Битрикс24 — перейти в «Разработчикам» → «Приложения» → «Добавить приложение». Указать права: crm, user, im (для уведомлений). Получить client_id и client_secret.
2. Получить OAuth-токен — выполнить GET-запрос на /oauth/authorize/ с параметрами, затем POST на /oauth/token/ с code. Сохранить access_token и refresh_token.
3. Настроить серверную часть — на PHP или Node.js реализовать функцию отправки лида. Пример на PHP (с использованием cURL):

$queryUrl = 'https://your-domain.bitrix24.ru/rest/crm.lead.add.json';
$queryData = http_build_query([ 'fields' => [ 'TITLE' => 'Лид с сайта', 'NAME' => $_POST['name'], 'PHONE' => [['VALUE' => $_POST['phone'], 'VALUE_TYPE' => 'WORK']], 'SOURCE_ID' => 'WEB' ], 'params' => ['REGISTER_SONET_EVENT' => 'Y']
]);
$curl = curl_init();
curl_setopt_array($curl, [ CURLOPT_URL => $queryUrl . '?auth=' . $accessToken, CURLOPT_POST => true, CURLOPT_POSTFIELDS => $queryData, CURLOPT_RETURNTRANSFER => true
]);
$result = curl_exec($curl);
curl_close($curl);

1. Реализовать refresh-токена — при ответе 401 (EXPIRED_TOKEN) отправить POST на /oauth/token/ с grant_type=refresh_token. Обновлённый токен сохранить в Redis с TTL 3500 секунд.
2. Настроить вебхуки для обратной связи — в Битрикс24 создать исходящий вебхук на событие «Добавление лида» и указать URL вашего эндпоинта. Сервер должен принимать POST с JSON и возвращать 200 OK.
3. Оптимизировать сервер — в .htaccess (Apache) добавить SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 для передачи Bearer-токена. Для Nginx — proxy_set_header Authorization $http_authorization;. В wp-config.php (если WordPress) включить define('WP_HTTP_BLOCK_EXTERNAL', false); и настроить прокси для cURL.
4. Добавить асинхронность — при большом потоке лидов отправку в CRM ставить в очередь RabbitMQ. Consumer обрабатывает сообщения и отправляет запросы к API. Это снижает нагрузку на сайт и гарантирует доставку.
5. Протестировать — создать тестовый лид через форму, проверить в CRM, убедиться, что refresh-токен срабатывает при долгом простое.

CommerceML: синхронизация каталога товаров

Для интернет-магазинов на 1С-Битрикс или WooCommerce используется протокол CommerceML. Настройка включает:

• Генерацию XML-файлов (import.xml, offers.xml) на стороне сайта.
• Отправку по HTTP на адрес https://your-domain.bitrix24.ru/crm/config/import/ с Basic-аутентификацией.
• Обработку ответа (успех/ошибка) и логирование.

Важно: CommerceML не поддерживает OAuth — используется логин/пароль администратора CRM. Рекомендуется создать отдельного пользователя с правами только на импорт.

Архитектурные паттерны: Redis и RabbitMQ

В высоконагруженных проектах мы в AVOdigital используем:

• Redis — для кэширования OAuth-токенов и конфигураций (например, список воронок). Время жизни токена — 3500 секунд, при каждом запросе проверяем TTL и при необходимости обновляем.
• RabbitMQ — для очередей задач. При отправке лида из формы данные помещаются в очередь, consumer отправляет запрос к REST API. Если CRM недоступна, задача остаётся в очереди и повторяется с экспоненциальной задержкой.

Пример конфигурации для RabbitMQ на PHP (библиотека php-amqplib):

$connection = new AMQPStreamConnection('localhost', 5672, 'guest', 'guest');
$channel = $connection->channel();
$channel->queue_declare('bitrix24_leads', false, true, false, false);
$msg = new AMQPMessage(json_encode($leadData), ['delivery_mode' => 2]);
$channel->basic_publish($msg, '', 'bitrix24_leads');

Опыт AVOdigital: кейсы и рекомендации

В нашей практике интеграция Битрикс24 с сайтом часто требует кастомных решений. Например, для одного интернет-магазина мы реализовали двухстороннюю синхронизацию: лиды с сайта → сделки в CRM, а при изменении статуса сделки (например, «Оплачен») — автоматическое обновление заказа на сайте через REST API. Для этого использовали исходящие вебхуки и очередь RabbitMQ.

Ещё один кейс — интеграция с WordPress через плагин, но с заменой стандартного OAuth-потока на JWT-авторизацию для повышения безопасности. Мы добавили в wp-config.php константы для хранения client_id и client_secret, а refresh-токен сохраняли в Redis.

Важно: всегда проверяйте лимиты API Битрикс24 — 2 запроса в секунду на один метод. При превышении возвращается ошибка 429. Решение — очередь с задержкой или пакетная обработка (метод batch).

Частые вопросы