Синхронизация с МойСклад

Модуль codebrain.moysklad связывает интернет-магазин на 1С-Битрикс с МоимСкладом через JSON API. Он переносит каталог, цены, остатки и картинки из МоегоСклада на сайт, заказы сайта — в МойСклад, а обратно приносит статусы, изменения корзины, оплаты, отгрузки, трек-номера и коды маркировки. Каталог, который уже есть на сайте, модуль умеет выгрузить в МойСклад.

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

#Возможности

• Каталог из МоегоСклада: группы → разделы, товары, модификации → торговые предложения (характеристики становятся свойствами-списками), комплекты → комплекты торгового каталога, услуги. Описание, артикул, код, штрихкоды, вес, габариты, НДС, единица измерения, страна, доп. поля и картинки.
• Цены: любые типы цен МоегоСклада, закупочная и минимальная цены; наценка и округление. Пустая цена модификации берётся у товара.
• Остатки: по складам МоегоСклада на склады сайта, «остаток», «свободный остаток» или «доступно»; количество — сумма всех или выбранных складов. Товар без остатка можно скрывать и показывать снова.
• Сопоставление с каталогом сайта: по внешнему коду, артикулу, коду, штрихкоду или названию, со сравнением без учёта регистра, пробелов, дефисов и похожих букв.
• Безопасность: пробный прогон, правила «когда записывать поле», защита ручных правок, задержка скачков цены, остановка массового скрытия товаров, откат запуска.
• Заказы: скидка сайта видна менеджеру, дата заказа, адрес по полям, юрлицо, склад, канал продаж и проект по правилам, статусы в обе стороны, доп. поля, покупатели без дублей. Из МоегоСклада — статус, отмена, состав заказа, стоимость доставки, оплаты, отгрузки с трек-номером и кодами маркировки.
• Выгрузка каталога сайта в МойСклад: разделы, товары, торговые предложения с характеристиками, цены, штрихкоды, вес, картинки. Поля, которые ведутся на сайте, и дальше передаются в МойСклад.
• Быстро и экономно: изменения приходят вебхуками за секунды, без вебхуков — опросом; остатки — быстрым отчётом только по изменившимся товарам; модуль сам выдерживает лимиты API МоегоСклада.
• Здоровье обмена: последние успешные проходы каждого потока, состояние вебхуков, очередь, расход лимита API, отчёт для техподдержки.

#Требования

Модуль работает по API и не использует штатный обмен через CommerceML. Если вы пользовались штатной интеграцией МоегоСклада, выключите её, чтобы два обмена не писали одни и те же данные.

#Установка

1. Установите модуль из Маркетплейса: Marketplace → Каталог решений, найдите «Синхронизация с МойСклад» и нажмите «Установить».
2. В главном меню административной панели появится раздел Codebrain → МойСклад.

#Быстрый старт

1. В МоёмСкладе откройте Настройки → Токены и создайте токен для сотрудника-администратора.
2. На сайте: Codebrain → МойСклад → Подключения → Подключить аккаунт МоегоСклада. Вставьте токен, нажмите «Проверить», выберите сайт и каталог. Сохраните — модуль прочитает склады, типы цен, доп. поля и статусы МоегоСклада и создаст вебхуки.
3. Пройдите вкладки «Каталог», «Поля» и «Цены и остатки»: что брать, как искать существующие товары, куда записывать цены и остатки.
4. Нажмите «Пробный прогон». Модуль покажет, какие товары создаст, какие найдёт на сайте и что в них изменит, — ничего не записывая.
5. Всё верно — «Выполнить по-настоящему» или «Полная синхронизация». Дальше изменения из МоегоСклада приходят сами.

В карточке подключения видно, когда последний раз проходил каждый поток обмена, сколько товаров и заказов связано и в порядке ли вебхуки. Кнопка «Синхронизировать сейчас» обрабатывает накопленные изменения не дожидаясь агента.

#Подключение

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

#Что брать из МоегоСклада

• Что брать: товары, модификации, комплекты, услуги.
• Только эти группы / Кроме групп: группы МоегоСклада вместе с подгруппами. Служебные группы (упаковка, расходники) можно исключить.
• Только товары с отметкой: доп. поле-флажок МоегоСклада, например «На сайт». Снятая отметка скрывает товар на сайте.
• Создавать на сайте новые товары: если выключить, модуль только обновляет найденные товары — например, если с МоимСкладом синхронизируются лишь цены и остатки.
• Разделы: дерево групп МоегоСклада (внутри выбранного раздела сайта), все новые товары в один раздел или «не трогать разделы».
• Товар в архиве / удалён в МоёмСкладе: скрыть на сайте, удалить или ничего не делать.
• Комплекты: комплект торгового каталога (состав из связанных товаров) или обычный товар.

#Сопоставление с товарами сайта

Если каталог уже есть на сайте, модуль сначала ищет каждый товар МоегоСклада среди существующих и только потом создаёт новый.

• Поле МоегоСклада — внешний код, UUID, артикул, код, штрихкод или наименование.
• Поле сайта — внешний код (XML_ID), символьный код, название, штрихкод торгового каталога или любое свойство.
• Нестрогое сравнение — без учёта регистра, пробелов, дефисов, точек, ведущих нулей и похожих русских и латинских букв: «АРТ-0012» найдёт «apt12».

Внешний код совпадает сам, если раньше работал штатный обмен МоегоСклада или 1С: торговые предложения ищутся по коду вида «товар#модификация». Связь запоминается: дальше товар находится сразу, даже если у него изменится артикул.

Если по ключу нашлось несколько товаров, модуль ничего не создаёт и показывает их на странице «Сопоставление».

Выберите нужный товар, укажите ID другого (только товар каталога этого подключения, для модификации — торговое предложение), создайте новый или отметьте «не синхронизировать» — модуль больше не будет трогать этот товар МоегоСклада.

#Поля: когда записывать

Для каждого поля задаётся правило:

Например, если описания и SEO-тексты пишет контент-менеджер на сайте, а МойСклад отвечает за цены и остатки, поставьте «Описание» — «при создании» или «никогда». По умолчанию разделы задаются только новым товарам, и ваша раскладка товаров по разделам на сайте не ломается.

#Куда записывать

• Описание — в детальное описание или описание для анонса, как текст или HTML.
• Артикул — «автоматически» выбирает свойство ARTICLE, CML2_ARTICLE или ARTNUMBER и создаёт его, если такого нет.
• Штрихкоды — в штрихкоды торгового каталога или в свойство.
• Вес — в МоёмСкладе он может быть в килограммах или граммах; на сайте вес хранится в граммах, модуль переводит.
• Габариты — из доп. полей МоегоСклада (длина, ширина, высота) в сантиметрах, миллиметрах или метрах.
• Доп. поля МоегоСклада — в выбранные свойства товара. Без сопоставления модуль создаёт свойство с кодом MS_… при первой встрече доп. поля (флажок «Создавать свойства»). Доп. поле можно не брать.
• Характеристики модификаций — в свойства торговых предложений. Если у предложений уже есть свойство с тем же названием (например, «Размер» или «Цвет»), характеристика записывается в него; иначе создаётся свойство-список, его сразу видит умный фильтр и выбор предложения в карточке.
• Описание с разметкой записывается как HTML и перед записью очищается: скрипты, обработчики событий и опасные ссылки удаляются, даже если описание в МоёмСкладе правил посторонний сотрудник.

#Картинки

Картинки МоегоСклада скачиваются через API: первая — детальная картинка (и картинка анонса), остальные — в свойство MORE_PHOTO. Не изменившиеся в МоёмСкладе картинки повторно не скачиваются.

• как в МоёмСкладе — удалённая там картинка удаляется и на сайте;
• только добавлять новые — если вы удаляете фото в МоёмСкладе, чтобы не платить за место: на сайте они останутся;
• не брать — картинки ведутся на сайте.

#Цены

Каждый тип цены МоегоСклада можно записать в тип цены сайта или в закупочную цену, с наценкой в процентах и округлением (например, до 10 рублей). Закупочная и минимальная цены МоегоСклада доступны как отдельные строки. Если у модификации цена не задана, можно брать цену её товара.

#Остатки

• Что считать остатком: остаток на складе, свободный остаток (за вычетом резерва — не продаёт то, что уже отложено под другие заказы) или «доступно» (минус резерв, плюс ожидание).
• Склады МоегоСклада → склады сайта: остатки выбранных складов записываются в одноимённые склады сайта.
• Количество товара на сайте: сумма всех складов МоегоСклада, сумма выбранных или не менять.
• Нет в наличии (вкладка «Каталог»): скрыть товар и показать снова, когда остаток появится. Товар, скрытый вручную, модуль не показывает.

Модуль спрашивает только изменившиеся остатки: по вебхуку остатков МоегоСклада (раз в 1–5 минут) или опросом. Отрицательный остаток МоегоСклада на сайте — ноль.

#Пробный прогон и полная синхронизация

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

Кнопка «Выполнить по-настоящему» запускает ту же синхронизацию с записью. Страница показывает прогресс, а после — все изменения запуска.

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

#Защита каталога

• Ручные правки. Если поле изменили на сайте после синхронизации (название, описание, свойство), модуль его больше не перезаписывает и пишет об этом в журнал. Цены и остатки МойСклад меняет всегда.
• Скачок цены. Изменение цены больше заданного процента и нулевая цена задерживаются до решения на странице «Изменения». Остальные поля товара записываются.
• Массовое скрытие. Если полная синхронизация собирается скрыть больше заданной доли каталога (неверный аккаунт, сбитый фильтр, сбой), запуск останавливается и ждёт кнопки «Продолжить всё равно».
• Откат. Кнопка «Откатить изменения запуска» возвращает значения, которые были до него. Поля, изменённые после запуска, остаются как есть; созданные товары скрываются.

#Изменения и решения

На странице «Изменения» видно, что модуль изменил на сайте, а также задержанные изменения, которые ждут решения.

Отметьте изменения и нажмите «Применить выбранные» или «Отклонить выбранные». Число ожидающих решений показывается в меню и в информере административной панели.

#Заказы

С сайта в МойСклад заказ уходит сразу после оформления (или в выбранных статусах). В заказе МоегоСклада:

• позиции с ценой до скидки и процентом скидки сайта — менеджер видит, что скидка уже дана; сумма совпадает с сайтом;
• доставка — позицией-услугой «Доставка» (услуга создаётся сама);
• дата и номер заказа сайта (шаблон номера, например САЙТ-#ACCOUNT_NUMBER#), комментарий покупателя и названия применённых скидок и купонов;
• адрес доставки по полям (индекс, город, улица, дом, квартира) — так его принимают службы доставки, подключённые к МоемуСкладу;
• юрлицо, склад, канал продаж и проект — по умолчанию или по правилам: «если платёжная система = …, то юрлицо = …», «если сайт = s2, то склад = …»;
• доп. поля заказа из свойств заказа сайта, номер заказа сайта;
• резерв товаров (по желанию).

Товары заказа, ещё не связанные с МоимСкладом, ищутся по внешнему коду, а если их нет — создаются, как при штатном обмене.

Покупатели ищутся по телефону и e-mail, компании — по ИНН. Новый контрагент получает правильный тип (физлицо, ИП, юрлицо) и название компании вместо ФИО. Обязательные доп. поля контрагента и заказа модуль заполняет значениями по умолчанию, чтобы МойСклад не отказывал в сохранении.

Товары других каталогов. Если в заказе есть товар не из каталога подключения (другой инфоблок сайта), модуль создаёт его в МоёмСкладе для позиции заказа, но не связывает с каталогом: синхронизация такой товар на сайт не переносит. Услуга «Доставка» тоже не попадает в каталог сайта.

Статусы сопоставляются в обе стороны или только в одну. «Статус отмены» отменяет заказ на сайте, а отменённый на сайте заказ получает этот статус в МоёмСкладе.

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

Оплаты. Оплата на сайте становится входящим платежом в МоёмСкладе, привязанным к заказу; входящий платёж или приходный ордер МоегоСклада отмечает оплату на сайте. Частичная оплата уменьшает сумму оплаты на сайте, остаток остаётся к оплате.

Отгрузки. Отгрузка МоегоСклада разрешает отгрузку на сайте, переносит трек-номер (из выбранного доп. поля) и коды маркировки «Честного знака».

Старые заказы не отправляются сами при включении обмена. Чтобы выгрузить их, укажите дату в поле «Передавать заказы, созданные с» или запустите выгрузку заказов за период.

#Выгрузка каталога сайта в МойСклад

Если каталог ведётся на сайте — загружается от поставщиков, переносится с 1С, — модуль выгрузит его в МойСклад.

1. Включите «Выгрузка каталога сайта в МойСклад» и выберите, какие цены сайта в какие типы цен МоегоСклада передавать.
2. На странице подключений нажмите «Пробная выгрузка» — модуль покажет, сколько товаров создаст и сколько найдёт в МоёмСкладе.
3. «Выгрузить каталог сайта в МойСклад»: разделы станут группами, товары — товарами, торговые предложения — модификациями (свойства предложений — характеристиками), переносятся цены, артикулы, штрихкоды, вес, описание и до 10 картинок.

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

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

У товаров, созданных выгрузкой, картинки в МоёмСкладе — копии картинок сайта, поэтому обратно они не скачиваются; торговое предложение сохраняет своё название (МойСклад называет модификацию сам: «Товар (XL)»). Комплекты и услуги МоегоСклада выгрузка не трогает — они ведутся в МоёмСкладе.

#Вебхуки и опрос

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

• МойСклад выключает вебхуки, если сайт долго отвечал ошибками (например, был недоступен), — модуль включает их снова;
• после переноса сайта или восстановления из резервной копии старые вебхуки ведут не туда — модуль удаляет их и создаёт новые;
• лишние вебхуки удаляются.

Приём вебхука только ставит изменение в очередь и отвечает за миллисекунды; обрабатывает очередь агент. Повторные уведомления об одном товаре объединяются. Изменения, которые модуль сам отправляет в МойСклад, не возвращаются к нему вебхуками.

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

#Здоровье обмена

• Потоки обмена — когда последний раз успешно прошли проверка изменений, полная сверка, остатки и заказы. Поток, давно не работавший, отмечается проблемой и приходит уведомлением.
• Агенты — выполняются ли агенты по cron и когда последний раз работал агент модуля.
• Вебхуки — когда проверялись, когда пришёл последний вебхук, кнопка «Проверить и восстановить вебхуки».
• Очередь — сколько изменений ждут обработки; ошибки можно повторить или очистить.
• Отчёт для техподдержки — окружение, настройки без токена и последние ошибки одним текстом: скопируйте его в обращение.

#Лимиты API МоегоСклада

МойСклад ограничивает число запросов: 45 единиц за 3 секунды на сотрудника. С 1 декабря 2026 года запрос по токену сотрудника засчитывается за 4 единицы — это 11 запросов за 3 секунды, а запрос отчёта остатков — за 5.

Модуль:

• выдерживает темп по заголовкам МоегоСклада и при ответе «превышен лимит» ждёт столько, сколько просит МойСклад;
• не повторяет один и тот же ошибочный запрос больше нескольких раз — иначе МойСклад отключает доступ к API;
• если МойСклад раз за разом отвечает «превышен лимит», ставит обмен на паузу на 5 минут;
• запрашивает только изменившиеся товары и остатки, страницами до 100–1000 объектов.

На странице «Здоровье» виден расход лимита по часам за сутки.

#Журнал

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

#Карточка товара и заказа

В карточке товара и заказа в административной панели появляется вкладка «МойСклад»: ссылка на объект в МоёмСкладе, время последней синхронизации, история изменений и кнопка «синхронизировать сейчас» (для заказа — «отправить сейчас»).

#Настройки модуля и права доступа

• Публичный адрес сайта — по нему МойСклад присылает вебхуки. Если пусто, берётся адрес сервера из настроек главного модуля или сайта по умолчанию (адрес из запроса посетителя не используется). Если не задан ни один — вебхуки не создаются, «Здоровье» подскажет, что заполнить.
• E-mail для уведомлений — токен отозван, вебхуки отключены, обмен остановлен: не чаще одного письма в сутки на проблему. Уведомления видны и в информере административной панели.
• Хранить журнал и историю изменений, дней.
• Права: группы, которые видят состояние обмена (по умолчанию — с правом просмотра торгового каталога), и группы, которые запускают синхронизацию и решают спорные изменения (по умолчанию — только администраторы). Подключения и настройки меняют только администраторы.

#Как это работает

• Связи. Каждый товар, модификация, раздел, заказ, платёж и отгрузка МоегоСклада связаны с объектом сайта. Связь запоминает, какое значение модуль записал в каждое поле: если на сайте значение другое, его изменили вручную.
• Очередь. Вебхуки и опрос ставят изменения в очередь; агент модуля раз в минуту разбирает её: сначала заказы, потом каталог, остатки и выгрузку с сайта. Неудачная запись повторяется с растущей паузой.
• Агенты. Agent::run — каждую минуту (обмен и запуски), Agent::monitor — раз в час (вебхуки и здоровье), Agent::cleanup — раз в сутки (журнал и история). На cron агент работает до 50 секунд, на хитах посетителей — 8 секунд.
• Своя запись. Изменения, которые делает сам модуль, не вызывают обратной отправки: ни в МойСклад, ни из него.

#Данные и конфиденциальность

Модуль обменивается данными только между вашим сайтом и вашим аккаунтом МоегоСклада. На сервер Codebrain ничего не передаётся. Токен МоегоСклада хранится в базе данных сайта и не выводится на страницы и в отчёт для техподдержки. В МойСклад передаются данные заказов и покупателей (имя, телефон, e-mail, адрес), необходимые для работы с заказами.

#Для разработчиков

#События

Обработчик события «OnBefore…» может вернуть изменённое тело или отказаться от отправки:

use Bitrix\Main\EventManager;
use Bitrix\Main\EventResult;

EventManager::getInstance()->addEventHandler('codebrain.moysklad', 'OnBeforeOrderSend', function (\Bitrix\Main\Event $event) {
    $body = $event->getParameter('body');
    $body['description'] .= "\nИсточник: сайт";
    return new EventResult(EventResult::SUCCESS, ['body' => $body]);
});

#Удаление модуля

При удалении модуль спрашивает, сохранить ли данные. Без сохранения удаляются вебхуки в МоёмСкладе, подключения, связи, журнал и настройки; товары, разделы и заказы на сайте остаются.

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

Нужна ли платная опция «Интернет-магазин» в МоёмСкладе? Модуль работает по API и не использует штатный обмен через CommerceML. Для вебхуков нужен платный тариф МоегоСклада; без них модуль работает опросом — и каталог, и остатки, и заказы.

На сайте уже есть каталог из 1С или штатного обмена. Будут дубли? Нет. Внешние коды после штатного обмена совпадают сами, а если товары заводились отдельно — включите сопоставление по артикулу. Запустите пробный прогон: в нём видно, какие товары будут найдены, а какие созданы.

Каталог ведётся на сайте, а МойСклад пустой. Включите вкладку «Выгрузка с сайта», сделайте пробную выгрузку и выгрузите каталог. Остатки после этого можно вести в МоёмСкладе.

Контент-менеджер правит описания на сайте — синхронизация их не затрёт? Нет, если включена защита ручных правок (включена по умолчанию). Можно и вовсе поставить для описания правило «при создании» или «никогда».

Остатки на сайте не совпадают с МоимСкладом. Проверьте «Что считать остатком» (остаток или свободный остаток) и какие склады сопоставлены. Кнопка «Пересчитать остатки» на странице подключений пересчитывает все товары сразу.

Изменения из МоегоСклада приходят с задержкой. Откройте «Здоровье»: если агенты выполняются на хитах, переведите их на cron; если вебхуки с проблемой — нажмите «Проверить и восстановить вебхуки». Если «последний вебхук» давно не обновлялся, проверьте, что сайт доступен МоемуСкладу из интернета (не закрыт по IP или паролем). Без вебхуков изменения приходят с интервалом опроса.

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

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