# Головные товары (SKU)

Головной товар — общая карточка товара с вариациями: название, описание и раздел каталога у него одни, а размеры, цвета и другие варианты хранятся в [вариациях товара](/docs/entities/catalog-offers). Раздел создаёт, читает, изменяет и удаляет головные товары.

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

## Операции

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

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

| Поле | Описание |
|------|---------|
| `name` | Название головного товара |
| `iblockId` | ID товарного каталога. Обязателен в фильтре списка, поиска и агрегации. Список: [`GET /v1/catalogs`](/docs/entities/catalogs) |
| `type` | Тип товара, вычисляется Битрикс24: `6` — головной товар без вариаций, `3` — с вариациями |
| `iblockSectionId` | ID основного раздела каталога. Список: [`GET /v1/catalog-sections`](/docs/entities/catalog-sections) |
| `active` | Активен ли товар |
| `code` | Символьный код товара |

Полный список полей — [`GET /v1/catalog-skus/fields`](./catalog-skus/fields.md).

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

1. **Головной товар и вариации живут в разных каталогах.** Головной товар хранится в товарном каталоге, его вариации — в каталоге вариаций. Каталог вариаций в [`GET /v1/catalogs`](/docs/entities/catalogs) узнаётся по полю `productIblockId`: в нём записан `iblockId` товарного каталога. Вариация ссылается на головной товар полем `parentId`.
2. **Список, поиск и агрегация требуют фильтр по товарному каталогу.** Без `filter[iblockId]` запрос возвращает `400 MISSING_REQUIRED_FILTER`. `iblockId` каталога вариаций отклоняется с `422 BITRIX_ERROR`.
3. **Тип товара меняется сам.** Новый головной товар получает `type: 6`. После привязки первой [вариации](/docs/entities/catalog-offers/create) тип становится `3`. Фильтр по `type` принимает одно точное число — `3` или `6`. Когда у головного товара удалена последняя вариация, он становится обычным товаром с `type: 1` и пропадает из `/v1/catalog-skus` — дальше он читается через [Товары каталога](/docs/entities/catalog-products).
4. **Минимум для создания — два поля.** `name` и `iblockId` обязательны. Поля `type`, `available` и `bundle` вычисляет Битрикс24, передать их нельзя.
5. **Удаление головного товара удаляет и его вариации.** Восстановить их через API нельзя.
6. **Ответ `get` подробнее ответа `list`.** Одна запись по `id` содержит символьный код, тексты, картинки, массив разделов `iblockSection` и свойства каталога вида `propertyNNN`. Список и поиск возвращают сокращённый набор полей. Остальные поля и свойства приходят по явному `select`, кроме `iblockSection` — его в списке нет.
7. **`DELETE` и `PATCH` не проверяют, что по `id` лежит головной товар.** С `id` обычного товара `DELETE` отвечает `204` и удаляет этот товар, а `PATCH` изменяет его и отвечает `404 ENTITY_NOT_FOUND`. Перед записью сверьте запись через [`GET /v1/catalog-skus/:id`](./catalog-skus/get.md): для `id` обычного товара он отвечает `404 ENTITY_NOT_FOUND`.

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

1. Найти товарный каталог и каталог вариаций: [`GET /v1/catalogs`](/docs/entities/catalogs).
2. Создать головной товар: [`POST /v1/catalog-skus`](./catalog-skus/create.md).
3. Добавить к нему вариации с `parentId`: [`POST /v1/catalog-offers`](/docs/entities/catalog-offers/create).
4. Найти головные товары с вариациями: [`GET /v1/catalog-skus?filter[iblockId]=25&filter[type]=3`](./catalog-skus/list.md).
5. Изменить или удалить головной товар: [`PATCH /v1/catalog-skus/:id`](./catalog-skus/update.md) / [`DELETE /v1/catalog-skus/:id`](./catalog-skus/delete.md).

## Лимиты

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

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

- [Вариации товара](/docs/entities/catalog-offers)
- [Товары каталога](/docs/entities/catalog-products)
- [Каталоги](/docs/entities/catalogs)
- [Разделы каталога](/docs/entities/catalog-sections)
- [Свойства товаров каталога](/docs/entities/catalog-product-properties)
- [Цены каталога](/docs/entities/catalog-prices)
- [Синтаксис фильтрации](/docs/filtering)
- [Справочник API](/docs/api-reference)