Интеграция коробки с внешними сервисами — одна из главных причин выбирать именно коробочную версию: здесь доступны и REST API, и серверный код, и прямой обмен. Разбираем инструменты интеграции, их различия и особенности, которые важны именно для коробки на своём сервере.
Способы интеграции: обзор
Коробка даёт больше вариантов связи с внешним миром, чем облако, потому что помимо REST у вас есть доступ к серверу. Выбор инструмента зависит от задачи и того, кто инициирует обмен.
- Вебхуки — простой способ дать внешней системе доступ к REST-методам по ключу, без создания приложения.
- Локальные REST-приложения — полноценные приложения с OAuth, событиями и правами, установленные на портал.
- Серверный код — обработчики событий и модули на PHP, недоступные в облаке.
- Штатные интеграции — готовые коннекторы 1С, телефонии, почты, мессенджеров.
REST API и вебхуки
REST — универсальный язык интеграций Битрикс24. В коробке он работает так же, как в облаке, но эндпоинт указывает на ваш домен. Самый быстрый старт — входящий вебхук.
- Создайте вебхук в разделе
Разработчикам → Другое → Входящий вебхук. - Выдайте ему права на нужные модули (CRM, задачи, диск).
- Дёргайте методы по URL вида
https://portal.company.ru/rest/1/КЛЮЧ/crm.deal.add.
Для событий (когда портал должен сам уведомлять внешнюю систему) используют исходящие вебхуки и подписку на события вроде ONCRMDEALUPDATE. Для сложных сценариев с авторизацией пользователей делают полноценное локальное приложение с OAuth 2.0.
Обмен с 1С
Связка с 1С — типовая задача для коробки. В зависимости от контура интеграции применяют разные механизмы обмена.
| Сценарий | Механизм |
|---|---|
| Синхронизация товаров и цен | Обмен через CommerceML |
| Выгрузка счетов и оплат в CRM | REST / интеграционный модуль |
| Контрагенты и реквизиты | REST-методы CRM |
| Двусторонний обмен статусами | События + очередь |
Для CRM-контура (сделки, счета, оплаты) обмен обычно строят на REST-методах и событиях. Ключевой вопрос — идемпотентность: каждая запись должна иметь внешний идентификатор из 1С, чтобы повторный обмен не создавал дубли. Тяжёлые обмены выносят в фоновую очередь, а не выполняют синхронно в момент запроса.
Телефония и мессенджеры
Каналы коммуникаций подключают через штатные механизмы «Открытых линий» и телефонии, а нестандартных операторов — через REST.
- SIP-телефония — подключение оператора через SIP-коннектор коробки, звонки привязываются к сделкам и лидам.
- Открытые линии — единая обработка обращений из мессенджеров и чатов с маршрутизацией на менеджеров.
- Кастомные каналы — свой коннектор через REST-методы
imconnectorиimopenlines. - Уведомления наружу — отправка в мессенджеры через исходящие вебхуки на события CRM.
Для коробки важно, что телефония требует доступности сервера извне и корректной настройки push-сервера — иначе события звонков не будут долетать до операторов в реальном времени.
Особенности интеграции коробки
Интеграция коробки отличается от облачной несколькими практическими моментами, которые часто всплывают уже в процессе.
- Доступность извне — если внешний сервис шлёт вебхуки в портал, ваш сервер должен быть доступен по HTTPS из интернета.
- Самоподписанный SSL — некоторые внешние сервисы не примут его, нужен валидный сертификат.
- Фоновые задачи через cron — тяжёлые обмены и очереди должны крутиться агентами на cron, а не на хитах.
- Свои обработчики — часть логики выгоднее делать модулем/событием на сервере, чем гонять через REST.
Надёжность и отладка
Живая интеграция ломается не в момент запуска, а потом — когда меняется формат данных или падает канал. Заложите наблюдаемость сразу.
| Что делать | Зачем |
|---|---|
| Логировать все обмены | Разбор инцидентов и дублей |
| Очередь с ретраями | Пережить недоступность внешней системы |
| Внешние ID на записях | Защита от дублирования |
| Мониторинг очереди | Заметить затор до жалоб пользователей |
Для отладки REST удобно проверять методы прямо в браузере или через curl, а ответы портала смотреть в формате JSON. Ошибки авторизации и прав вебхука — самая частая причина «молчащей» интеграции.
Итог
Коробка даёт полный набор инструментов интеграции: вебхуки и REST для внешних систем, локальные приложения с OAuth, серверные обработчики событий и штатные коннекторы 1С, телефонии и мессенджеров. Практический успех держится на надёжности — очередях с ретраями, внешних идентификаторах против дублей, логировании и доступности сервера по валидному HTTPS.
Мы в B2Bsite связываем коробочный Битрикс24 с сайтом, 1С, телефонией и мессенджерами: проектируем обмен, пишем надёжные интеграции с очередями и логами, настраиваем инфраструктуру под вебхуки. Если нужно, чтобы системы работали как единое целое без дублей и потерь — поможем выстроить интеграцию и сопровождать её.
Частые вопросы
Чем интеграция коробки отличается от облачной?
Помимо REST, в коробке доступен серверный код: обработчики событий и модули на PHP. Часть логики выгоднее реализовать прямо в ядре, а не гонять через внешние вызовы.
С чего проще всего начать интеграцию?
С входящего вебхука: создаёте его в разделе для разработчиков, выдаёте права на нужные модули и дёргаете REST-методы по URL с ключом. Это быстрее, чем полноценное приложение.
Как избежать дублей при обмене с 1С?
Храните на каждой записи внешний идентификатор из 1С и проверяйте его перед созданием. Тогда повторный обмен обновит существующую запись, а не создаст новую.
Нужен ли валидный SSL для интеграций?
Да. Многие внешние сервисы не принимают самоподписанный сертификат, а без HTTPS данные передаются небезопасно. Для входящих вебхуков сервер должен быть доступен из интернета.
Как подключить нестандартную телефонию или мессенджер?
Через REST-методы imconnector и imopenlines можно сделать свой коннектор к открытым линиям. Стандартных операторов подключают штатным SIP-коннектором коробки.
Почему тяжёлые обмены выносят в очередь?
Синхронный вызов упадёт, если внешняя система недоступна, и заблокирует запрос. Очередь с повторными попытками и логированием переживает сбои и не тормозит пользователей.
Как отлаживать REST-интеграцию?
Проверяйте методы через curl или браузер и смотрите JSON-ответ портала. Чаще всего «молчащая» интеграция вызвана ошибками авторизации или нехваткой прав вебхука.
Что делать, чтобы события долетали в реальном времени?
Настроить push-сервер и обеспечить доступность сервера извне. Без корректного push-сервера события звонков и обновлений не будут приходить операторам мгновенно.
Поможем с настройкой и поддержкой Битрикс24
Поможем с настройкой, доработкой и поддержкой Битрикс24.