Работа с изображениями товаров

Изображения товаров в JSON API 1.2 МойСклад — это вложенная коллекция сущности product. Через эндпоинт images их можно загружать в base64, получать вместе с миниатюрами и удалять, соблюдая лимит на количество.

Модель изображений

Изображения хранятся как подчинённая коллекция товара, доступная по адресу /entity/product/{id}/images. Аналогичные коллекции есть у модификаций (variant) и комплектов (bundle).

• Каждое изображение имеет meta, имя файла filename и размер.
• Первое изображение в списке считается обложкой (миниатюра товара).
• Есть уменьшенные версии — miniature и tiny, ссылки на них отдаются в ответе.

Получение изображений

Список изображений товара:

GET https://api.moysklad.ru/api/remap/1.2/entity/product/{id}/images

В ответе — стандартная коллекция с массивом rows, где у каждого изображения есть ссылки:

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

Загрузка изображения

Изображение добавляется через POST к коллекции images с телом, где содержимое файла закодировано в base64:

POST /entity/product/{id}/images

{"filename":"front.jpg","content":"/9j/4AAQSkZJRgABAQ..."}

• filename — имя файла с расширением, задаёт формат.
• content — сам файл в base64 без префикса data URI.
• Можно передать массив объектов, чтобы загрузить несколько картинок за один запрос.

Загрузка через base64 удобна для серверных интеграций, где файл уже есть на стороне клиента и не нужен отдельный multipart-запрос.

Замена обложки и порядок

Отдельного поля «главное фото» нет — обложкой служит первое изображение в коллекции. Чтобы сменить обложку, управляют составом коллекции:

1. Загружают нужный набор изображений в требуемом порядке.
2. Удаляют лишние или устаревшие.
3. Первое в списке становится миниатюрой карточки товара.

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

Удаление изображений

Одно изображение удаляется по его идентификатору:

DELETE /entity/product/{id}/images/{imageId}

Массовое удаление изображений выполняется через POST /entity/product/{id}/images/delete с массивом meta удаляемых картинок — так же, как для других сущностей.

Лимиты и рекомендации

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

• Не перезаливайте картинки при каждой синхронизации — сравнивайте хеш или имя файла и грузите только новые.
• Base64 увеличивает объём тела примерно на треть — учитывайте это в лимите размера запроса.
• Загрузка изображений расходует общий rate limit, поэтому дробите и не грузите всё в один поток.
• Готовьте изображения заранее: приводите к разумному разрешению и весу на стороне сайта, чтобы не гонять через API избыточно тяжёлые оригиналы.

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

Итог

Изображения — вложенная коллекция товара по адресу /entity/product/{id}/images. Загрузка идёт в base64, обложкой служит первое изображение, доступны миниатюры miniature и tiny, а количество ограничено десятью на товар. Чтобы не жечь лимиты, грузите только изменившиеся файлы и храните оригиналы у себя.

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