# Изображения товара

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

Методы возвращают только штатные изображения товара: детальную картинку, картинку анонса и элементы галереи `MORE_PHOTO`. Файлы из других пользовательских свойств товара типа «Файл» (`propertyNNN`) сюда не входят.

Битрикс24 API: `catalog.productImage.list`, `catalog.productImage.get`
Скоуп: `catalog`

## Операции

| Метод | Путь | Что возвращает |
|-------|------|----------------|
| GET | `/v1/catalog-products/:productId/images` | Снимок метаданных изображений товара одним списком |
| GET | `/v1/catalog-products/:productId/images/:imageId` | Одно изображение, принадлежащее указанному товару |

`productId` и `imageId` — положительные целые числа. Неканоничное или выходящее за безопасный диапазон JavaScript значение возвращает `400 INVALID_PARAMS`.

## Авторизация

Личный ключ передаётся в `X-Api-Key`. Ключ приложения дополнительно требует сессию пользователя в `Authorization: Bearer ...`. Ключ для чтения подходит, если в нём есть скоуп `catalog`.

```bash
curl "https://vibecode.bitrix24.tech/v1/catalog-products/541/images" \
  -H "X-Api-Key: YOUR_API_KEY"

curl "https://vibecode.bitrix24.tech/v1/catalog-products/541/images/93" \
  -H "X-Api-Key: YOUR_API_KEY"
```

## Поля изображения

В каждом объекте ровно шесть полей:

| Поле | Тип | Описание |
|------|-----|----------|
| `id` | number | ID изображения |
| `productId` | number | ID товара-владельца |
| `type` | string | `DETAIL_PICTURE`, `PREVIEW_PICTURE` или `MORE_PHOTO` |
| `name` | string | Имя файла |
| `createTime` | string \| null | Время создания в формате, который вернул Битрикс24, либо `null` |
| `detailUrl` | string | Адрес изображения: корневой относительный путь или абсолютный `http`/`https` URL; доступность без сессии портала не гарантируется |

Нативное поле `downloadUrl` не публикуется: оно может содержать подписанную ссылку. API не проксирует и не загружает файл.

## Ответы

Метод возвращает один снимок изображений товара и не принимает параметры пагинации. Вайбкод сам собирает внутренние страницы Битрикс24. `meta.total` обязан быть равен числу элементов в `data`; если обход страницы прервался, сработал внутренний предел или Битрикс24 вернул несогласованный конверт, Вайбкод отвечает `502`, не публикуя частичные данные. Клиенту не нужно передавать `start`, `limit` или `offset`: таких параметров в контракте маршрута нет.

```json
{
  "success": true,
  "data": [
    {
      "id": 93,
      "productId": 541,
      "type": "DETAIL_PICTURE",
      "name": "product.jpg",
      "createTime": null,
      "detailUrl": "/upload/catalog/product.jpg"
    }
  ],
  "meta": {
    "total": 1
  }
}
```

Одно изображение приходит тем же объектом в `data`, без `meta`.

## Безопасная работа с `detailUrl`

`detailUrl` — недоверенные входные данные. API проверяет только форму URL и возвращает его без нормализации. Не делайте по этому адресу серверный HTTP-запрос: это создаст SSRF-риск. Если путь начинается с `/`, он относится к адресу портала Битрикс24. Для интерфейса передавайте адрес в безопасный клиентский компонент, не загружайте его бэкендом.

## Ошибки

| HTTP | Код | Когда возвращается |
|------|-----|----------------------|
| 400 | `INVALID_PARAMS` | `productId` или `imageId` не является каноническим положительным целым числом |
| 401 | `MISSING_API_KEY` / `INVALID_API_KEY` / `TOKEN_MISSING` | Нет API-ключа, ключ неверен или к нему не привязаны токены Битрикс24 |
| 403 | `SCOPE_DENIED` / `BITRIX_ACCESS_DENIED` | Нет скоупа `catalog` или Битрикс24 запретил доступ |
| 404 | `ENTITY_NOT_FOUND` | Товар или изображение не найдены |
| 429 | `RATE_LIMITED` / `OPERATION_TIME_LIMIT` | Лимит запросов или операционного времени |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 вернул небезопасный или неверный ответ |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 не ответил вовремя; учтите `Retry-After` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Смотрите также

- [Товары каталога](/docs/entities/catalog-products)
- [Получить товар](/docs/entities/catalog-products/get)
- [Цены каталога](/docs/entities/catalog-prices)