# Вариации товара

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

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

## Операции

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

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

| Поле | Описание |
|------|---------|
| `name` | Название вариации |
| `iblockId` | ID каталога вариаций — каталога, у которого заполнен `productIblockId`. Обязателен при создании и в фильтре списка, поиска и агрегации. Список: [`GET /v1/catalogs`](/docs/entities/catalogs) |
| `parentId` | Связь с головным товаром. При создании передаётся как `{ "value": "<ID>" }`, в ответе приходит объектом `{ value, valueId }`. ID головного товара — из [`GET /v1/catalog-skus`](/docs/entities/catalog-skus/list) |
| `type` | Тип записи, вычисляется Битрикс24: `4` — вариация привязана к головному товару, `5` — свободная вариация без `parentId` |
| `active` | Активна ли вариация |
| `measure` | ID единицы измерения. Список: [`GET /v1/catalog-measures`](/docs/entities/catalog-measures) |
| `purchasingPrice` | Закупочная цена. Валюта — в `purchasingCurrency` |
| `quantity` | Остаток на складе |

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

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

1. **У вариаций свой каталог.** Товарному каталогу соответствует отдельный каталог вариаций: в [`GET /v1/catalogs`](/docs/entities/catalogs) у него заполнены `productIblockId` — ID товарного каталога — и `skuPropertyId`. Его `iblockId` передаётся при создании вариации и в фильтре списка, поиска и агрегации. С `iblockId` товарного каталога список и создание вариации отвечают `422 BITRIX_ERROR` с текстом `productType is not allowed for this catalog`.
2. **Список, поиск и агрегация требуют фильтр по каталогу.** Без `filter[iblockId]` запрос отклоняется с `400 MISSING_REQUIRED_FILTER` до обращения к Битрикс24.
3. **Связь с головным товаром задаётся при создании.** Поле `parentId` принимает `{ "value": "<ID головного товара>" }`. Без него создаётся свободная вариация с `type: 5`. Изменить связь нельзя: `PATCH` с `parentId` отклоняется с `400 READONLY_FIELD`. Все вариации одного головного товара отбираются фильтром `filter[parentId]=<ID>`.
4. **Фильтр по `type` принимает одно точное значение** — `4` или `5`. Другие числа, массивы и операторы отклоняются с `400 UNSUPPORTED_FILTER`.
5. **Выборка полей включает `iblockId` и `id`.** Если в списке или поиске передаётся `select`, оба поля в нём обязательны. Без `select` список возвращает сокращённый набор полей, а одна запись по `id` — полный, вместе со свойствами каталога вида `propertyNNN`.
6. **Минимум для создания — `name` и `iblockId`.** Без любого из них запрос отклоняется с `400 MISSING_REQUIRED_FIELDS`.
7. **Удаление головного товара удаляет его вариации.** После `DELETE /v1/catalog-skus/:id` вариации этого товара отвечают `404 ENTITY_NOT_FOUND`.
8. **`DELETE` не проверяет, что по `id` лежит вариация.** С `id` обычного товара вызов отвечает `204` и удаляет этот товар. Перед удалением сверьте запись через [`GET /v1/catalog-offers/:id`](./catalog-offers/get.md): для `id` обычного товара он отвечает `404 ENTITY_NOT_FOUND`.

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

1. Найти каталог вариаций и его `iblockId`: [`GET /v1/catalogs`](/docs/entities/catalogs) — запись с заполненным `productIblockId`.
2. Создать или найти головной товар: [`POST /v1/catalog-skus`](/docs/entities/catalog-skus/create) / [`GET /v1/catalog-skus`](/docs/entities/catalog-skus/list).
3. Создать вариации головного товара: [`POST /v1/catalog-offers`](./catalog-offers/create.md) с `parentId`.
4. Посмотреть вариации головного товара: [`GET /v1/catalog-offers?filter[iblockId]=27&filter[parentId]=7189`](./catalog-offers/list.md).
5. Задать цену вариации — `id` вариации передаётся в `productId`: [`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) |

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

- [Головные товары (SKU)](/docs/entities/catalog-skus)
- [Товары каталога](/docs/entities/catalog-products)
- [Цены каталога](/docs/entities/catalog-prices)
- [Каталоги](/docs/entities/catalogs)
- [Единицы измерения](/docs/entities/catalog-measures)
- [Свойства товаров каталога](/docs/entities/catalog-product-properties)
- [Синтаксис фильтрации](/docs/filtering)
- [Справочник API](/docs/api-reference)