МойСклад: Интеграция с Битрикс24 от разработчика «Денис Спиридонов»

Модуль связывает CRM Битрикс24 и складской учёт МойСклад в один рабочий контур. Менеджер ведёт сделку в привычной CRM — в МойСкладе сам появляется заказ покупателя или заказ поставщику: с клиентом, составом товаров, ценами, скидками и ставками НДС. Кладовщик или бухгалтер меняет документ в учёте — изменение возвращается в карточку сделки. Никаких файлов обмена, кнопок «выгрузить» и переписывания строк руками.

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

• Сделки и заказы покупателя МойСклад — в обе стороны.
  
• Сделки и заказы поставщику МойСклад — отдельный контур со своими настройками.
  
• Контакты и компании Битрикс24 и контрагенты МойСклад — включая юрлиц, ИП и физлиц.
  
• Реквизиты клиента: ИНН, КПП, ОГРН, юридическое название, адреса, телефон, почта, сайт.
  
• Состав заказа: товарные строки сделки и позиции документа — товар, количество, цена, скидка, ставка НДС.
  
• Номенклатура: товары, услуги, комплекты и модификации (торговые предложения) с картинками и характеристиками.
  
• Стадии сделки и статусы документа, статусы контрагента.
  
• Ответственный менеджер и валюта документа.
  
• Теги (группы) контрагента и произвольные пользовательские поля обеих систем.
  
• Справочники: сотрудники, валюты, единицы измерения, ставки НДС.
  

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

В обратную сторону работает так же: МойСклад присылает уведомление об изменении документа или контрагента, модуль кладёт его в очередь и обновляет карточку в Битрикс24. Опроса API по расписанию нет — значит, нет ни задержки в полчаса, ни лишней нагрузки на лимиты учётной системы.

При повторном обмене модуль сравнивает собранные данные с текущими и отправляет только изменившиеся поля. Если не изменилось ничего — запроса на запись не будет вовсе. Состав заказа сравнивается построчно: совпавшие позиции не трогаются, обновляются только те, что реально поменялись.

Всё настраивается в интерфейсе модуля, списками и таблицами соответствий, а не правкой кода:

• Сопоставление полей. Любое поле сделки, контакта или компании связывается с любым полем документа или контрагента МойСклад — стандартным, пользовательским или дополнительным (атрибутом). У каждой пары своё направление: в МойСклад, в Битрикс24 или в обе стороны.
  
• Значения по умолчанию. Организация, счёт, склад, канал продаж — то, что постоянно и не хранится в CRM, задаётся правилом, а не отдельным полем в Битрикс24.
  
• Поля поиска связанной записи. Связь ведётся по тому полю, которое уже сложилось в ваших данных: внешнему коду, ИНН, номеру договора.
  
• Фильтры обмена. Условия на поля решают, какие сделки уезжают в учёт и какие документы принимаются обратно.
  
• Справочники соответствий. Сотрудники, валюты, единицы измерения и ставки НДС сопоставляются явной таблицей — видно, что с чем связано и почему значение не перенеслось.
  
• Создание полей CRM. Служебные поля, которые нужны интеграции (признак типа документа, тип контрагента, статус, теги), модуль заводит сам из своих настроек — ходить в конструктор полей Битрикс24 не нужно.
  
• Помощник настройки каталога. Инфоблоки, разделы, группы товаров МойСклад и поля связи выбираются из подставленных списков, а не вводятся идентификаторами.
  

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

Интеграция с внешним сервисом ломается предсказуемо: сервис недоступен, API ограничил частоту запросов, поле заполнено не так. Модуль рассчитан именно на это.

• Очередь обмена. Задачи копятся в отдельной линии на каждый профиль и обрабатываются пакетами. Повторные правки одной сделки склеиваются в одну задачу: десять изменений подряд не превращаются в десять обращений к МойСкладу. Сбой не теряется — задача повторяется с нарастающей паузой.
  
• Проверка готовности настроек. Перед каждым обменом модуль смотрит, достаточно ли настроек, чтобы запись нашлась и связалась. Недонастроенный контур обмен не запускает — вместо того чтобы плодить дубли. Состояние по обоим видам документов, трём типам контрагента и четырём справочникам видно на дашборде.
  
• Защита от дублей. Перед созданием записи модуль ищет её пару на другой стороне и обновляет найденную. Если поиск не выполнился из-за сбоя, обмен прерывается и повторяется позже: создавать запись вслепую после ошибки нельзя, это гарантированный дубль.
  
• Защита от зацикливания. Записи, которые модуль делает сам, не запускают встречный обмен: ни события CRM, ни уведомления МойСклад на них не срабатывают.
  
• Страница очереди. Видно каждую задачу: направление, документ, статус, число попыток, полный текст ошибки. Задачу можно выполнить принудительно или удалить, не дожидаясь расписания. Рядом — карточка агента: активен ли, когда следующий запуск, кнопки переустановить и прогнать проход вручную.
  

Товарная часть — самое трудоёмкое место любой интеграции, и здесь она разобрана подробно.

Товар ищется по выбранному вами полю связи: внешнему коду (XML_ID) или конкретному свойству инфоблока, а на стороне МойСклад — по внешнему коду или внутреннему идентификатору. Если XML_ID уже занят выгрузкой из 1С или интернет-магазина, связь настраивается на своё свойство, не ломая существующие интеграции. После создания товара код связи дозаписывается обратно, чтобы следующий обмен нашёл товар, а не создал второй.

Если товара во второй системе ещё нет, модуль создаёт его сам: переносит название, описание, единицу измерения, картинки и характеристики. Связанные сущности разворачиваются каскадом — у модификации сначала создаётся родительский товар, у комплекта сначала компоненты. Свойства торговых предложений (цвет, размер, объём) сопоставляются с характеристиками модификаций МойСклад — списки, привязки к элементам инфоблока и справочники highload-блоков.

Благодаря этому обмен заказами можно запустить, не выгружая заранее весь каталог: номенклатура наполняется по мере появления реальных заказов и остаётся связанной с обеих сторон.

Двусторонний. Причём направление настраивается не «целиком», а по частям: отдельно для каждого контура документов, отдельно для состава товаров, ответственного, валюты, тегов и каждой пары полей. Можно, например, отдавать ответственного в МойСклад, но не принимать обратно.

Нет. Обмен запускают события CRM — создание и изменение сделки, контакта, компании. Кнопки «выгрузить» в карточке нет и не требуется. Пользователь работает как обычно и про интеграцию не думает.

Как правило, сразу: после постановки задачи модуль пытается обработать её в фоне, не дожидаясь очередного запуска агента. Штатная обработка очереди идёт раз в минуту. Изменения из МойСклад приходят уведомлением в момент правки документа.

Задача останется в очереди и повторится — до трёх попыток с нарастающей паузой. Временные отказы и превышение лимитов обрабатываются автоматическим повтором запроса. Если авторизация в МойСклад не проходит, очередь приостанавливается, не тратя попытки впустую.

Нет, если настроены поля поиска связанной записи — и обмен документами просто не запустится, пока не задано хотя бы одно такое поле с сохранением связки. Это встроенная проверка, а не рекомендация в инструкции.

Да. Фильтр задаёт условия на поля: направление, источник, стадия, дата, произвольное пользовательское поле. Операторы — равно и не равно, больше и меньше, содержит и не содержит. Отдельный набор условий работает на приём документов из МойСклад: например, принимать только заказы нужного склада или организации.

По правилу, которое задаёте вы: пользовательское поле сделки и его значение. Например, поле «Тип сделки» со значением «Закупка» относит сделку к заказам поставщику. Сделка без заданного признака уезжает заказом покупателя — это тип по умолчанию. При загрузке из МойСклад поле проставляется автоматически.

Да. В МойСкладе контрагент бывает трёх типов — юрлицо, ИП, физлицо, — и каждый настраивается отдельно: к контакту или компании Битрикс24 он привязан, какие поля переносить, какой шаблон реквизита использовать. У юрлица переносятся ИНН, КПП и юридический адрес, у физлица — паспортные данные и контакты.

Да. Реквизиты в Битрикс24 лежат не в самой карточке, а в связанной сущности «Реквизит», поэтому модуль находит реквизит нужного шаблона (или создаёт его) и пишет значения туда. Адреса собираются по типам, телефон, почта и сайт пишутся в множественные поля карточки. Адреса и множественные значения переносятся из МойСклад в Битрикс24.

Нет. Заказ в МойСкладе не бывает без контрагента, поэтому клиент выгружается попутно со сделкой: в учёт попадут только те клиенты, по которым реально есть заказы. Полный обмен клиентской базой включается отдельно, когда он понадобится.

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

Нет. Модуль синхронизирует документы, клиентов и карточки номенклатуры, но не остатки и не прайс-листы. Цена и скидка переносятся как часть позиции документа — то есть цена в конкретном заказе, а не цена в каталоге.

Нет. Удалённая сделка не удаляет заказ в МойСкладе, удалённый контакт не удаляет контрагента, и наоборот. Это сделано намеренно: удаление — необратимая операция, и автоматически размножать её на вторую систему опасно.

Нет. В обмене участвуют сделки, контакты и компании.

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

Две вещи: планировщик агентов Битрикс24 (запуск по cron) для обработки очереди и публично доступный адрес на сайте портала для приёма уведомлений МойСклад. Файл-обработчик уведомлений модуль разворачивает сам из интерфейса и проверяет реальным запросом, что адрес отвечает — ходить на сервер по FTP не нужно.

• Битрикс24 в коробочной версии с модулем CRM.
  
• Модули «Торговый каталог» и «Информационные блоки» — для обмена составом заказа и номенклатурой.
  
• Учётная запись МойСклад: подключение по токену доступа или по логину и паролю. Права в учётной системе определяются той записью, под которой выпущен токен.
  
• Планировщик агентов Битрикс24 (cron) — для очереди обмена.
  
• Публично доступный адрес на сайте портала — для веб-хуков МойСклад.
  

Честный список, чтобы не было сюрпризов при внедрении:

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

1. Подключить МойСклад: токен или логин с паролем.
   
2. Создать служебные поля CRM прямо из настроек модуля.
   
3. Включить нужный контур — заказы покупателя или заказы поставщику — и задать поля поиска связанной записи.
   
4. Сопоставить поля обмена и, если нужно, стадии со статусами.
   
5. Проверить состояние настроек на дашборде: там видно, что готово, а что осталось донастроить.
   
6. Включить состав товаров, клиентскую базу и приём уведомлений из МойСклад, когда основной контур заработал.