## Загрузить изображение товара `POST /v1/catalog-products/:productId/images` Загружает изображение товара каталога из содержимого в base64: детальную картинку, картинку анонса или картинку галереи. Тело запроса — плоский JSON. ## Параметры | Параметр | Тип | Обяз. | Описание | |----------|-----|:-----:|----------| | `productId` (path) | number | да | ID товара. Список: [`GET /v1/catalog-products`](/docs/entities/catalog-products/list). Подходит и ID головного товара из [`GET /v1/catalog-skus`](/docs/entities/catalog-skus/list), вариации из [`GET /v1/catalog-offers`](/docs/entities/catalog-offers/list) или услуги из [`GET /v1/catalog-services`](/docs/entities/catalog-services/list) | ## Поля запроса (body) | Поле | Тип | Обяз. | Описание | |------|-----|:-----:|----------| | `type` | string | да | Вид изображения: `DETAIL_PICTURE` — детальная картинка, `PREVIEW_PICTURE` — картинка анонса, `MORE_PHOTO` — картинка галереи. Другое значение отклоняется до обращения к Битрикс24 | | `fileName` | string | да | Имя файла с расширением, например `photo.png`. Пустое имя не принимается | | `fileContent` | string | да | Содержимое файла в base64 | Других полей тело не принимает: лишнее поле, например `description`, возвращает `400 INVALID_PARAMS`. Предел тела запроса — 40 MiB. ## Примеры ### curl — личный ключ ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-products/7257/images" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "MORE_PHOTO", "fileName": "photo.png", "fileContent": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4z8DwHwAFgAI/ScL/nwAAAABJRU5ErkJggg==" }' ``` ### curl — OAuth-приложение ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-products/7257/images" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "MORE_PHOTO", "fileName": "photo.png", "fileContent": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4z8DwHwAFgAI/ScL/nwAAAABJRU5ErkJggg==" }' ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-products/7257/images', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'MORE_PHOTO', fileName: 'photo.png', fileContent: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4z8DwHwAFgAI/ScL/nwAAAABJRU5ErkJggg==', }), }) const { success, data } = await res.json() console.log('ID изображения:', data.id) ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-products/7257/images', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ type: 'MORE_PHOTO', fileName: 'photo.png', fileContent: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4z8DwHwAFgAI/ScL/nwAAAABJRU5ErkJggg==', }), }) const { success, data } = await res.json() ``` ## Поля ответа Успешная загрузка отвечает HTTP-статусом `201 Created`. | Поле | Тип | Описание | |------|-----|----------| | `success` | boolean | Всегда `true` при успехе | | `data` | object | Загруженное изображение | | `data.id` | number | ID изображения | | `data.productId` | number | ID товара, которому принадлежит изображение | | `data.type` | string | Вид изображения: `DETAIL_PICTURE` — детальная картинка, `PREVIEW_PICTURE` — картинка анонса, `MORE_PHOTO` — картинка галереи | | `data.name` | string | Имя файла | | `data.createTime` | string \| null | Время создания в формате ISO 8601 со смещением часового пояса, либо `null` | | `data.detailUrl` | string | Адрес изображения — путь от адреса портала, начинающийся с `/`, или абсолютный `http`/`https` URL. Без сессии портала адрес может быть недоступен. Это недоверенные данные — правила в разделе [Изображения товара](/docs/entities/catalog-products/images) | ## Пример ответа ```json { "success": true, "data": { "id": 38993, "productId": 7257, "type": "MORE_PHOTO", "name": "photo.png", "createTime": "2026-10-08T23:59:02+03:00", "detailUrl": "https://cdn-ru.bitrix24.ru/b00000000/iblock/2ba/2bae996b883855a3997fde84f01c7aee/photo.png" } } ``` ## Пример ответа при ошибке 400 — неизвестный `type`, пустое имя файла, содержимое не в base64 или лишнее поле в теле: ```json { "success": false, "error": { "code": "INVALID_PARAMS", "message": "type, fileName and base64 fileContent are required" } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|----------| | 400 | `INVALID_PARAMS` | Тело не прошло проверку: неизвестный `type`, пустое или отсутствующее `fileName`, `fileContent` не в base64 или в теле есть другое поле | | 400 | `INVALID_PARAMS` | `productId` не является каноническим положительным целым числом, например `abc`, `0` или значение за пределами безопасного диапазона JavaScript | | 404 | `ENTITY_NOT_FOUND` | Товара с таким `productId` нет | | 413 | `PAYLOAD_TOO_LARGE` | Тело запроса больше 40 MiB | | 422 | `BITRIX_ERROR` | Битрикс24 не принял файл, например имя с расширением не картинки — `note.txt` | | 422 | `BITRIX_ERROR` | Новое изображение не сохранено: при замене `DETAIL_PICTURE` или `PREVIEW_PICTURE` осталась прежняя картинка. Сообщение — `Product image was not saved` | | 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен или вернул ответ, не прошедший проверку формы и безопасности | | 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` | | 401 | `INVALID_API_KEY` | Ключ неверен | | 401 | `TOKEN_MISSING` | К ключу не привязаны токены Битрикс24 | | 403 | `SCOPE_DENIED` | У ключа нет скоупа `catalog` | | 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ работает в режиме только чтения. Для загрузки и удаления нужен ключ с правом записи | | 403 | `BITRIX_ACCESS_DENIED` | Битрикс24 запретил доступ к каталогу | | 429 | `RATE_LIMITED` | Превышен лимит запросов. Повторите после срока из заголовка `Retry-After` | | 429 | `OPERATION_TIME_LIMIT` | Исчерпан лимит времени операций Битрикс24. Повторите после срока из заголовка `Retry-After` | | 503 | `BITRIX_TIMEOUT` | Битрикс24 не ответил вовремя, и исход записи неизвестен. Перед повтором проверьте список изображений товара | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности - **Замена детальной картинки и картинки анонса.** У товара одна детальная картинка и одна картинка анонса. Повторная загрузка `DETAIL_PICTURE` или `PREVIEW_PICTURE` заменяет прежнюю: в ответе новый `id`, а прежний `id` больше не читается. `MORE_PHOTO` добавляет картинку в галерею. - **Содержимое файла не проверяется.** Текст с именем `photo.png` сохраняется как картинка. Проверяйте, что `fileContent` — изображение, до загрузки. - **Одинаковое содержимое — один файл.** Повторная загрузка того же содержимого создаёт изображение с новым `id`, но `name` и `detailUrl` у него от ранее загруженного файла, даже если в `fileName` передано другое имя. ## Смотрите также - [Изображения товара](/docs/entities/catalog-products/images) - [Список изображений товара](/docs/entities/catalog-products/images-list) - [Получить изображение товара](/docs/entities/catalog-products/images-get) - [Удалить изображение товара](/docs/entities/catalog-products/images-delete) - [Товары каталога](/docs/entities/catalog-products)