Коробка меняет условия задачи
Когда компания переезжает на коробочный Битрикс24, обмен данными с учётной системой всплывает в первые же недели. Менеджер закрывает сделку, а счёт и отгрузка живут в ERP. Склад считает остатки в одной программе, продажи обещают сроки, глядя в другую. Пока сотрудников десять, всё держится на копипасте и памяти руководителя отдела. На тридцати сотрудниках копипаст начинает врать, и обычно это выясняется через клиента.
Коробочная версия отличается от облачной не только тем, что стоит на вашем сервере. Она отличается доступом. У вас есть файловая система портала, база данных, возможность писать серверный код и ставить свои модули. Это открывает пути интеграции, которых в облаке нет, и одновременно добавляет ответственности: за сетевые доступы, за обновления, за то, чтобы самописный обработчик не положил портал в понедельник утром.
Дальше идёт разбор способов, которыми коробочный Битрикс24 связывают с внешними CRM и ERP, с честными границами каждого. Мы в B2BPRO делаем такие интеграции регулярно, и большая часть провалов, которые приходится потом разгребать, случается не из-за плохого кода, а из-за решений, принятых до кода.
Четыре способа связать коробку с внешней системой
Формально их больше, но на практике всё сводится к четырём подходам. Они не конкурируют, в живом проекте обычно работают два или три одновременно.
Вебхуки
Самый быстрый старт. Входящий вебхук представляет собой секретный URL, по которому внешняя система вызывает методы REST API портала. Адрес строится из домена портала, сегмента /rest, идентификатора сотрудника, секретного кода и названия метода. Ключевая деталь, про которую забывают: запросы выполняются в рамках выбранного при создании вебхука scope и с правами того сотрудника, который вебхук создал. Уволили сотрудника, отключили учётку, обмен встал. Часть методов через вебхук вообще недоступна, потому что требует контекста приложения.
Исходящий вебхук работает в обратную сторону: портал сам стучится на ваш обработчик, когда происходит событие. Для коробочной версии здесь два условия, о которых стоит знать заранее. Нужна активная лицензия, на демонстрационном режиме исходящий вебхук недоступен. И нужно открыть сетевые доступы: сервер портала должен уметь достучаться до вашего обработчика, а обработчик должен принимать POST-запросы.
Право создавать входящие вебхуки администратор выдаёт отдельным сотрудникам через настройки безопасности портала. Сам себе рядовой пользователь такой доступ не назначит, и это правильно: вебхук с широким scope по сути равен ключу от портала. Отсюда же практическое требование к эксплуатации. Секретный код вебхука не должен лежать в переписке, в коде на публичном репозитории или в паре десятков закладок у разных подрядчиков. Заводите отдельный вебхук под каждую интегрируемую систему, с минимально необходимым scope, и ведите список: кто, когда и зачем его создал.
Локальное приложение
Следующая ступень. Локальное приложение живёт внутри портала, авторизуется через OAuth и работает от имени приложения, а не конкретного человека. Оно переживает увольнения, умеет обновлять токены и подписываться на события централизованно. Если интеграция рассчитана на годы, а не на квартал, разумнее сразу закладывать этот вариант, даже когда стартовать проще с вебхука.
Серверные обработчики на PHP
Тут у коробки есть возможность, которой в облаке нет вовсе: доступ к событийной системе ядра Bitrix Framework. Обработчик регистрируется через менеджер событий, \Bitrix\Main\EventManager::getInstance()->addEventHandler($fromModuleId, $eventType, $callback), где первый параметр указывает модуль, чьё событие вы ловите, второй задаёт имя события. Для старой сигнатуры аргументов есть addEventHandlerCompatible с теми же параметрами, и есть классическая функция AddEventHandler, доставшаяся от прежнего ядра.
Что это даёт на практике. Обработчик срабатывает синхронно, внутри той же транзакции, до или после действия пользователя. Можно проверить данные перед сохранением и отменить операцию, если внешняя система вернула отказ. Через REST такое поведение не воспроизвести: событие прилетит уже постфактум.
Взамен требуется дисциплина. Тяжёлый обработчик, повешенный на добавление сделки, замедлит работу всего отдела продаж. Внешний HTTP-запрос внутри синхронного обработчика почти гарантированно подвесит интерфейс, когда чужой сервер начнёт отвечать за десять секунд. Поэтому в синхронном обработчике делают только валидацию и постановку задачи в очередь, а сам обмен уносят в фон.
Готовые коннекторы
Если внешняя система построена на 1С, изобретать велосипед чаще всего не нужно. Есть приложение «Коннектор к 1С», которое связывает две системы напрямую. Состав синхронизируемых данных зависит от конфигурации: с 1С:Бухгалтерией это счета, с 1С:Управление торговлей это сделки на стороне Битрикс24 и заказы на стороне 1С, с 1С:УНФ и счета, и сделки. Поддерживается обмен полями, статусами и табличными частями смарт-процессов.
Обмен работает в трёх режимах: реального времени, когда изменение сразу запускает синхронизацию; ручном, когда обмен стартует из 1С по кнопке; и по расписанию, с заданной периодичностью. Модуль ставится расширением, конфигурацию 1С менять не требуется. Нужна платформа 1С:Предприятие 8, а доступность отдельных возможностей зависит от тарифа.
Коннектор закрывает типовой сценарий. Но если ваша 1С допилена под себя за пять лет, а обмениваться нужно не счетами, а производственными заказами с десятком нестандартных полей, готового решения не хватит, и вы всё равно придёте к REST плюс серверные обработчики. Мы обычно смотрим на это так: коннектор берёт на себя большую часть сущностей, остальное дописывается руками.
Кто главный: источник истины важнее протокола
Самый дорогой вопрос интеграции не технический. Он звучит так: если у контрагента в Битрикс24 один БИН, а в ERP другой, какая система права?
Пока ответа нет, любой обмен превращается в качели. Одна система перезаписывает другую, потом другая перезаписывает первую, и через месяц никто не может сказать, где актуальные реквизиты. Поэтому до первой строчки кода мы садимся с клиентом и по каждой сущности фиксируем владельца.
Типовое разделение выглядит так. Контрагенты и контакты остаются за Битрикс24, потому что их заводят продавцы и там же живёт вся история общения. Номенклатура и цены остаются за ERP, потому что там они рождаются и там за них отвечает конкретный человек. Остатки идут только из ERP, в одну сторону. Документы и оплаты тоже ERP. Сделки, задачи и коммуникации остаются в Битрикс24.
Дальше это разделение превращается в направление обмена по каждой сущности: односторонний или двусторонний. Двусторонних оставляйте минимум. Каждый двусторонний обмен требует правил разрешения конфликтов, а правила через год никто не помнит.
Отдельно фиксируйте, что происходит при удалении. Удалённая в ERP номенклатура должна пропасть из Битрикс24 или остаться помеченной? Второе почти всегда правильнее: связанные с ней сделки не должны терять смысл. Если этот пункт не проговорить, первый же массовый пересчёт справочника в учётной системе выкосит половину карточек в CRM.
События вместо опроса
Начинающий интегратор пишет скрипт, который раз в пять минут дёргает crm.deal.list и сравнивает результат с прошлым разом. Это работает ровно до того момента, пока сделок не станет много.
Правильный путь идёт через подписку на события. Битрикс24 сам сообщает, что изменилось: новая сделка, смена стадии, обновление контакта, добавление задачи. Внешняя система получает уведомление и забирает только то, что реально поменялось.
Здесь есть техническая тонкость, которая на коробке проявляется чаще, чем в облаке. Обычная подписка означает, что портал вызовет ваш обработчик. Если обработчик в этот момент недоступен, потому что сервер обновляется, канал упал или приложение перезапускается, событие теряется. На объёме это выглядит как «в CRM сделка есть, а в ERP её нет», и найти такое расхождение задним числом крайне неприятно.
Офлайн-события: страховка от падения приёмника
Для этого случая в REST API предусмотрен отдельный механизм. При регистрации обработчика методом event.bind указывается тип события offline. После этого Битрикс24 перестаёт вызывать ваш обработчик и вместо этого копит изменения в очереди у себя. Приложение само приходит за накопленным методами event.offline.get или event.offline.list, а об ошибках обработки сообщает через event.offline.error.
Важная деталь, которая экономит нервы на проектировании: в очереди хранится не история всех изменений, а текущее состояние объекта. Если одну и ту же сделку правили тысячу раз, в очереди останется одна запись со временем последнего изменения. Значит, очередь не раздувается от активной работы менеджеров. Но значит и другое: восстановить последовательность правок по ней нельзя. Если бизнесу нужен именно журнал изменений, его придётся вести отдельно.
На практике выбор такой. Если приёмник представляет собой ваш собственный сервис, который вы контролируете и который стоит рядом, обычных событий достаточно. Если приёмник это чужая система, обновляемая по своему графику, или связь между площадками нестабильна, офлайн-события снимают целый класс проблем.
Лимиты, batch и объём
Первая массовая выгрузка обычно и показывает, насколько крепко сделан обмен. Полтора года истории сделок, тридцать тысяч контрагентов, номенклатура на сотню тысяч позиций.
В облачном Битрикс24 интенсивность запросов ограничена алгоритмом «дырявого ведра»: для большинства тарифов это два запроса в секунду в устойчивом режиме с порогом накопления, для Enterprise пять. При превышении приходит ответ 503 с ошибкой QUERY_LIMIT_EXCEEDED. Отдельно считается ресурсоёмкость: в ответе есть поле operating с накопленным временем выполнения, и при его превышении вернётся 429 с ошибкой OPERATION_TIME_LIMIT.
В коробочной версии эти ограничения настраиваются на стороне вашего сервера и отличаются от облачных. Соблазн выкрутить лимиты в ноль велик, и это ошибка. Лимиты защищают не Битрикс, а ваш собственный сервер: интеграция, забирающая всё доступное железо, сначала подвесит портал для живых сотрудников, а потом объяснит, почему отдел продаж не работал полдня.
Рабочий инструмент против лимитов это метод batch. Он позволяет упаковать до пятидесяти вызовов методов в один HTTP-запрос. Превышение даст ошибку ERROR_BATCH_LENGTH_EXCEEDED для лишних подзапросов. Важно понимать, что batch сокращает число HTTP-запросов, но не отменяет проверку ресурсоёмкости вложенных методов, так что упаковать пятьдесят тяжёлых выборок в один пакет и ждать чуда не стоит.
Для выгрузки больших списков документация рекомендует постраничный обход без подсчёта общего количества элементов: подсчёт итога на больших таблицах стоит дороже самой выборки. И общее правило по первой миграции: делать её отдельным разовым процессом, ночью, с возможностью продолжить с места обрыва, а не тем же кодом, который потом будет обслуживать текущий поток изменений.
Сопоставление сущностей: где ломается большинство проектов
Техническая часть интеграции обычно занимает меньше времени, чем сведение справочников. Это та часть работы, которую клиенты недооценивают чаще всего.
В Битрикс24 контрагент записан как «ТОО Альфа», в ERP как «Альфа, ТОО», а в третьей системе как «ALFA LLP». Человек видит, что это одна компания, программа не видит. Поэтому связь между записями нужно хранить явно: в карточке Битрикс24 заводится пользовательское поле с идентификатором записи во внешней системе, и наоборот. Сопоставление по названию ведёт к дублям, сопоставление по БИН или ИНН работает надёжнее, но и оно ломается на филиалах и физлицах.
Перед запуском обмена почти всегда нужен этап чистки: выгрузить оба справочника, свести вручную или полуавтоматически, разметить связи, и только потом включать синхронизацию. На нашей практике это самый недооценённый этап. Клиент рассчитывает на неделю, уходит три, и уходят они на решения вида «эти два контрагента одна компания или всё-таки разные юрлица».
Второй частый источник боли это статусы и стадии. Воронка в CRM и статусы заказа в ERP редко совпадают один в один. Нужна явная таблица соответствий, включая ответ на вопрос, что делать со статусом, которому нет пары. Оставлять как есть, ставить ближайший, писать в служебное поле: решение принимает бизнес, а не разработчик.
Как это выглядит на живом проекте
Дальше идёт собирательный пример, а не описание конкретного клиента. Оптовая компания, около сорока сотрудников, коробочный Битрикс24 на своём сервере и 1С:Управление торговлей. Задача в том, чтобы менеджер видел актуальные остатки и статус отгрузки, не переключаясь в 1С, а бухгалтерия не заводила контрагентов дважды.
Разделение получилось такое: контрагенты рождаются в Битрикс24 и уезжают в 1С при первой сделке; номенклатура и остатки идут только из 1С; заказ создаётся в 1С по факту перехода сделки на стадию «Согласовано»; статус отгрузки и оплаты возвращается в карточку сделки.
Остатки обновляются по расписанию, раз в пятнадцать минут, пакетно. Синхронность здесь не нужна, менеджеру достаточно свежести в четверть часа. Создание заказа идёт по событию смены стадии. Возврат статусов сделан через офлайн-очередь, потому что сервер 1С по ночам уходит в обслуживание и в это время просто не отвечает.
Отдельно закладывается служебная стадия «Ошибка обмена» и ответственный, которому падает задача, если сделка не смогла уехать в учётную систему. Без такого предохранителя проблема всплывает не в момент сбоя, а через неделю, когда клиент звонит и спрашивает про свою отгрузку.
Что заложить заранее
Интеграция с внешними системами живёт долго и ломается регулярно, поэтому несколько вещей стоит предусмотреть на старте: дописывать их потом дороже.
Логирование каждого обмена: что ушло, что вернулось, сколько заняло. Без журнала разбор инцидента превращается в гадание. Повторные попытки с нарастающей паузой, потому что внешние системы падают и обмен должен это переживать без вмешательства человека. Уведомление ответственному при повторяющихся ошибках, а не только запись в лог, который никто не читает. И тестовый контур, где можно проверить изменения до боевого портала: на коробке это несложно, копия портала разворачивается на отдельном сервере.
Отдельно стоит завести регламент по обновлениям. Коробочный Битрикс24 обновляется, и самописные обработчики после обновления иногда перестают работать. К этому нужен процесс: проверять интеграцию после каждого крупного обновления, а не узнавать о поломке от менеджеров.
Если внутренней команды под такую работу нет, разумнее отдать её подрядчику вместе с сопровождением. Наши услуги по внедрению и настройке Битрикс24 включают и проектирование обмена, и его последующее обслуживание. Синхронизация Битрикс24 с ERP редко бывает разовой задачей, чаще это то, что живёт вместе с бизнесом и меняется вместе с ним.
Частые вопросы
Чем интеграция с внешними системами в коробке отличается от облака?
Главное отличие в доступе к серверу и коду. В коробке можно писать обработчики событий ядра на PHP, ставить собственные модули и работать с базой напрямую, чего в облаке нет. Взамен вы отвечаете за сетевые доступы, обновления и производительность своего сервера. REST API доступен в обеих версиях, но у исходящего вебхука в коробке есть свои условия: нужна активная лицензия, на демонстрационном режиме он не работает.
Что выбрать для обмена с 1С, готовый коннектор или разработку?
Если конфигурация 1С типовая и обмениваться нужно стандартными сущностями, начинайте с приложения «Коннектор к 1С»: оно ставится расширением, конфигурацию менять не требуется, режимы обмена доступны в реальном времени, вручную и по расписанию. Разработка нужна там, где учётная система сильно доработана или обмениваться приходится нестандартными объектами. Часто оптимален гибрид, когда коннектор закрывает типовое, а остальное дописывается.
Сколько времени занимает интеграция?
Технически простой обмен по паре сущностей запускается за одну-две недели. Реальный срок определяет не код, а состояние справочников и количество согласований по правилам обмена. Проекты, где справочники сначала привели в порядок, стартуют быстрее тех, где решили разобраться по ходу.
Что произойдёт с обменом при обновлении коробочного портала?
Интеграции через REST и вебхуки обычно переживают обновления спокойно. Самописные серверные обработчики требуют проверки: методы ядра меняются, и код, написанный несколько лет назад, может перестать работать. Поэтому проверка интеграции включается в регламент обновления, а сами обновления сначала прогоняются на тестовой копии.
Можно ли синхронизировать не с 1С, а с другой ERP?
Да. REST API Битрикс24 не привязан к конкретной учётной системе, обмениваться можно с любой, у которой есть API или хотя бы возможность выгрузки в файл. Разница в объёме работ: под 1С есть готовые решения, под остальные системы обмен проектируется с нуля, и на это закладывается больше времени.