Синхронизация каталога через API

Синхронизация каталога через JSON API 1.2 МойСклад — это связка маппинга по externalCode, инкрементальной выгрузки по дате изменения и массового upsert. Правильно построенный обмен переносит товары, цены и остатки без дублей и лишней нагрузки.

Архитектура обмена

Прежде чем писать код, определитесь с направлением и «источником истины». Возможны три сценария:

Для e-commerce типична гибридная схема: номенклатура, цены и остатки идут из МойСклад, а SEO-контент и медиа управляются на сайте. Чёткое разделение полей предотвращает «войну перезаписей».

Маппинг сущностей

Ключевой вопрос — как связать товар МойСклад с элементом каталога Битрикс. Использовать внутренние id обеих систем неудобно, поэтому применяют внешний код:

• Поле externalCode в МойСклад хранит идентификатор из вашей системы.
• Поиск по нему: GET /entity/product?filter=externalCode=ART-123.
• Альтернатива — собственная маппинг-таблица «id Битрикс ↔ id МойСклад».

Инкрементальная выгрузка

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

GET /entity/product?filter=updated>=2026-07-16 10:00:00&limit=1000

1. Храните метку времени последней успешной синхронизации.
2. Запрашивайте сущности с updated больше этой метки.
3. Пагинируйте выборку через limit и offset.
4. После успешной обработки обновляйте метку.

Так объём обмена пропорционален числу реальных изменений, а не размеру всего каталога. Держите небольшой перехлёст окна (например, вычитайте из метки минуту), чтобы не потерять сущности, изменённые ровно на границе интервала, а дубли отсекайте идемпотентной записью на приёмной стороне.

Массовый upsert

Запись изменений на сторону МойСклад делается массово. В одном POST /entity/product с массивом можно и создавать новые товары, и обновлять существующие:

• Элемент с meta известной сущности — обновление.
• Элемент без meta, но с уникальным externalCode — создание.
• Дробите на пачки по 200–500 объектов, чтобы уложиться в лимиты размера и не ловить таймауты.

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

Остатки и цены

Остатки нельзя записать в товар напрямую — это расчётная величина. Их получают через отчёт остатков:

GET /report/stock/all?filter=...

• Остатки берутся отчётом, а не из карточки товара.
• Цены хранятся в товаре в массиве salePrices и указываются в копейках.
• Для больших каталогов остатки удобно тянуть асинхронным отчётом, а не постранично.

Событийная синхронизация

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

1. Подписка на UPDATE и CREATE по product.
2. По событию делается точечный GET изменённого товара.
3. Изменение применяется на стороне сайта.

Гибрид «вебхуки для оперативности + периодическая сверка для надёжности» — самый устойчивый вариант: события дают скорость, а регулярная инкрементальная выгрузка страхует от пропущенных уведомлений. Чтобы избежать «эха» (когда изменение, пришедшее из МойСклад, тут же уезжает обратно и порождает новый вебхук), помечайте изменения своим источником и сверяйте auditContext — правки, сделанные самой интеграцией, при обратной синхронизации нужно пропускать.

Итог

Надёжная синхронизация каталога стоит на четырёх опорах: чёткое разделение источника истины по полям, маппинг по externalCode или отдельной таблице, инкрементальная выгрузка по updated и массовый upsert пачками. Остатки берутся отчётом stock, а вебхуки добавляют оперативности поверх периодической сверки.

Мы в B2Bsite собираем такие обмены между 1С-Битрикс и МойСклад в отдельный модуль: маппинг, инкремент, очереди, логирование и откаты. Это превращает синхронизацию каталога в предсказуемый процесс, который выдерживает рост номенклатуры и не создаёт дублей.