Массовые операции и bulk

Массовые операции в JSON API 1.2 МойСклад позволяют за один HTTP-запрос создать или изменить сотни сущностей вместо тысяч одиночных вызовов. Это ключевой инструмент экономии лимитов при синхронизации каталога и заказов.

Принцип массовой записи

В JSON API 1.2 нет отдельного «bulk-эндпоинта» для создания и обновления: массовость встроена в обычный POST к коллекции сущности. Если в тело передать JSON-массив объектов вместо одного объекта, МойСклад обработает каждый элемент как отдельную сущность в рамках одной транзакции запроса.

• Элемент без поля meta и без id — создаётся новая сущность.
• Элемент с meta.href (или id) существующей сущности — она обновляется (частично, только переданные поля).
• В одном массиве можно смешивать создание и обновление — это удобно для upsert-синхронизации.

Ответ приходит массивом в том же порядке, что и запрос, поэтому по индексу легко сопоставить результат с исходным элементом.

Пример массового создания и обновления

Создание двух товаров и обновление третьего одним вызовом:

POST https://api.moysklad.ru/api/remap/1.2/entity/product

[{"name":"Товар А","code":"A-001"},{"name":"Товар Б","code":"B-001"},{"meta":{"href":"https://api.moysklad.ru/api/remap/1.2/entity/product/5a9a...","type":"product","mediaType":"application/json"},"salePrices":[{"value":150000}]}]

Обязательные заголовки — те же, что для одиночного запроса: Authorization, Content-Type: application/json и Accept-Encoding: gzip для сжатия ответа. Цены указываются в копейках (value: 150000 = 1500,00 ₽).

Массовое удаление через delete

Для удаления пачкой используется отдельный эндпоинт /delete, в тело которого передаётся массив объектов meta удаляемых сущностей:

POST https://api.moysklad.ru/api/remap/1.2/entity/product/delete

[{"meta":{"href":".../entity/product/ID1","type":"product","mediaType":"application/json"}},{"meta":{"href":".../entity/product/ID2","type":"product","mediaType":"application/json"}}]

В ответ приходит массив статусов по каждой сущности с полем info и HTTP-подобным error, если удалить не удалось (например, сущность используется в проведённом документе).

Лимиты размера запроса

Массовость не бесконечна — есть ограничения на объём одного запроса. Их нужно учитывать при разбивке синхронизации на пачки.

Практический совет: держите пачку в пределах 100–500 объектов. Так и размер тела остаётся разумным, и при ошибке проще локализовать проблемный элемент, и таймаут обработки не превышается.

Частичные ошибки в пачке

Важная особенность: массовый запрос обрабатывается поэлементно. Если один объект невалиден, остальные всё равно применяются, а в ответе на позиции сбойного элемента будет объект с полем errors вместо созданной сущности.

• Всегда проверяйте ответ поэлементно, а не только HTTP-код 200.
• Сохраняйте соответствие «индекс в запросе → ваш внутренний идентификатор», чтобы понять, что именно не записалось.
• Типичные причины: дубликат code, ссылка на несуществующий meta, обязательное поле не заполнено.

Практика интеграции с 1С-Битрикс

При обмене каталога между 1С-Битрикс и МойСклад массовые операции резко снижают число обращений и попаданий под rate limit. Рекомендуемый конвейер:

1. Собрать изменения из инфоблока каталога Битрикс в очередь (агент или событие OnAfterIBlockElementUpdate).
2. Сгруппировать по пачкам 200–500 элементов.
3. Отправить массовый POST /entity/product с upsert по externalCode.
4. Разобрать ответ, сохранить возвращённые id в маппинг-таблицу.

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

Итог

Массовые операции — это обычный POST с массивом для создания и обновления и отдельный /delete для удаления пачкой. Держите пачки в пределах 100–500 объектов, всегда разбирайте ответ поэлементно и сопоставляйте результат с исходными данными по индексу. Так вы экономите лимиты и получаете предсказуемую синхронизацию.

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