# Товары каталога

Товары торгового каталога: список, получение, создание, изменение и удаление. Товар описывает позицию каталога — название, активность, единицу измерения и флаги продажи. Цены продажи задаются отдельно, в [Ценах каталога](/docs/entities/catalog-prices).

Битрикс24 API: `catalog.product.*`
Скоуп: `catalog`

## Операции

- [Создать товар](./catalog-products/create.md) — `POST /v1/catalog-products`
- [Список товаров](./catalog-products/list.md) — `GET /v1/catalog-products`
- [Получить товар](./catalog-products/get.md) — `GET /v1/catalog-products/:id`
- [Изображения товара](./catalog-products/images.md) — `GET /v1/catalog-products/:productId/images` и `GET /v1/catalog-products/:productId/images/:imageId`
- [Обновить товар](./catalog-products/update.md) — `PATCH /v1/catalog-products/:id`
- [Удалить товар](./catalog-products/delete.md) — `DELETE /v1/catalog-products/:id`
- [Поиск товаров](./catalog-products/search.md) — `POST /v1/catalog-products/search`
- [Поля товара](./catalog-products/fields.md) — `GET /v1/catalog-products/fields`
- [Агрегация товаров](./catalog-products/aggregate.md) — `POST /v1/catalog-products/aggregate`

## Ключевые поля

| Поле | Описание |
|------|---------|
| `name` | Название товара. Отдельного поля `title` у товара нет |
| `iblockId` | ID каталога. Обязателен в фильтре списка и поиска. Список: [`GET /v1/catalogs`](/docs/entities/catalogs) |
| `iblockSectionId` | ID раздела каталога. Список: [`GET /v1/catalog-sections`](/docs/entities/catalog-sections) |
| `active` | Активен ли товар |
| `measure` | ID единицы измерения |
| `purchasingPrice` | Закупочная цена. Валюта — в `purchasingCurrency` |
| `quantity` | Остаток на складе |

## Что нужно знать перед работой

1. **Список и поиск требуют фильтр по каталогу.** В `GET /v1/catalog-products` и `POST /v1/catalog-products/search` поле `filter[iblockId]` обязательно — без него запрос возвращает ошибку. Значение `iblockId` берётся из [`GET /v1/catalogs`](/docs/entities/catalogs).
2. **Выборка полей включает `iblockId`.** Если в запросе списка или поиска передаётся `select`, в нём обязательно должен быть `iblockId`. Без явного `select` приходит сокращённый набор полей — часть имён справочника возвращается только по явному перечислению, они названы в [Полях товара](./catalog-products/fields.md).
3. **Минимум для создания — два поля.** `name` и `iblockId` обязательны. Остальные поля опциональны и принимают значения по умолчанию.
4. **Булевы флаги — значения `true`/`false`.** `active`, `vatIncluded`, `canBuyZero`, `quantityTrace`, `subscribe`, `barcodeMulti`, `withoutOrder` приходят и принимаются как булевы. Поля `available` и `bundle` вычисляются Битрикс24 и доступны только для чтения.
5. **Остаток и закупочная цена зависят от управления складом.** Когда на портале включено управление складом, поля `quantity`, `purchasingPrice` и `purchasingCurrency` при создании и изменении товара не применяются — остатки и закупочные цены ведутся складскими документами. Цены продажи задаются через [Цены каталога](/docs/entities/catalog-prices).
6. **Ответ `get` подробнее ответа `list`.** Одна запись по `id` возвращает дополнительные поля товара — символьный код, размеры, тип, а также пользовательские свойства каталога вида `propertyNNN`. У свойств-списков элемент приходит вместе с названием — в поле `valueEnum` рядом с `valueId` и `value`. Названия и типы самих свойств `propertyNNN` — в [Свойствах товаров каталога](/docs/entities/catalog-product-properties). Список и поиск возвращают сокращённый набор полей, а свойство `propertyNNN` — когда оно названо в `select` своим именем.

## Типичный сценарий

1. Найти каталог и его `iblockId`: [`GET /v1/catalogs`](/docs/entities/catalogs).
2. Посмотреть товары каталога: [`GET /v1/catalog-products?filter[iblockId]=25`](./catalog-products/list.md).
3. Создать или изменить товар: [`POST /v1/catalog-products`](./catalog-products/create.md) / [`PATCH /v1/catalog-products/:id`](./catalog-products/update.md).
4. Задать цену товара: [`POST /v1/catalog-prices`](/docs/entities/catalog-prices/create).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Авто-пагинация | включается при `limit > 50` |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Rate limit | общий для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Цены каталога](/docs/entities/catalog-prices)
- [Каталоги](/docs/entities/catalogs)
- [Разделы каталога](/docs/entities/catalog-sections)
- [Свойства товаров каталога](/docs/entities/catalog-product-properties)
- [Значения списочных свойств](/docs/entities/catalog-product-property-enums)
- [Изображения товара](/docs/entities/catalog-products/images)
- [Синтаксис фильтрации](/docs/filtering)
- [Справочник API](/docs/api-reference)