# Свойства товаров каталога

Схема свойств торгового каталога: список, получение, создание, изменение и удаление. Свойство описывает определение пользовательского поля каталога — `id`, название и тип. Это спутник [Товаров каталога](/docs/entities/catalog-products): свойства-списки товара приходят там в полях вида `propertyNNN`, где `NNN` — это `id` свойства. Эта сущность превращает `id` в название и тип — например, свойство `154` → `{ "name": "Наименование по РУ", "propertyType": "S" }`.

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

## Операции

- [Создать свойство](./catalog-product-properties/create.md) — `POST /v1/catalog-product-properties`
- [Список свойств](./catalog-product-properties/list.md) — `GET /v1/catalog-product-properties`
- [Получить свойство](./catalog-product-properties/get.md) — `GET /v1/catalog-product-properties/:id`
- [Обновить свойство](./catalog-product-properties/update.md) — `PATCH /v1/catalog-product-properties/:id`
- [Удалить свойство](./catalog-product-properties/delete.md) — `DELETE /v1/catalog-product-properties/:id`
- [Поиск свойств](./catalog-product-properties/search.md) — `POST /v1/catalog-product-properties/search`
- [Поля свойства](./catalog-product-properties/fields.md) — `GET /v1/catalog-product-properties/fields`

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

| Поле | Описание |
|------|---------|
| `id` | ID свойства. Это `NNN` в ключе `propertyNNN` на товаре каталога |
| `iblockId` | ID каталога. Список: [`GET /v1/catalogs`](/docs/entities/catalogs) |
| `name` | Название свойства для отображения |
| `propertyType` | Базовый тип. Значения: `N` число, `S` строка, `L` список, `F` файл, `E` привязка к элементу, `G` привязка к разделу |
| `active` | Активно ли свойство |
| `sort` | Индекс сортировки |

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

1. **Эта сущность — схема свойств каталога.** Каждая запись описывает определение поля: `id`, `name` и `propertyType`. Свойства-списки товара приходят в [Товарах каталога](/docs/entities/catalog-products) в полях вида `propertyNNN`, где `NNN` совпадает с `id` свойства. По `id` строится сопоставление `id` → название и тип, а значения `propertyNNN` получают подпись.
2. **Фильтр по каталогу ограничивает выдачу одним каталогом.** В `GET /v1/catalog-product-properties` и `POST /v1/catalog-product-properties/search` поле `filter[iblockId]` ограничивает выборку свойствами одного каталога. Значение `iblockId` берётся из [`GET /v1/catalogs`](/docs/entities/catalogs).
3. **Код типа задаёт поведение свойства.** `propertyType` принимает значения `N` число, `S` строка, `L` список, `F` файл, `E` привязка к элементу, `G` привязка к разделу.
4. **Минимум для создания — три поля.** `iblockId`, `name` и `propertyType` обязательны. Остальные поля опциональны и принимают значения по умолчанию.
5. **Тип задаётся только при создании.** Поля `iblockId`, `propertyType` и `userType` доступны для записи только при создании. `PATCH` с любым из них отклоняется с `400 READONLY_FIELD`.
6. **Булевы флаги — значения `true`/`false`.** `active`, `multiple`, `withDescription`, `searchable`, `filtrable`, `isRequired` приходят и принимаются как булевы. Пустые строки приходят как `null`.

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

1. Найти каталог и его `iblockId`: [`GET /v1/catalogs`](/docs/entities/catalogs).
2. Прочитать схему свойств каталога: [`GET /v1/catalog-product-properties?filter[iblockId]=19`](./catalog-product-properties/list.md).
3. Построить сопоставление `id` → `name` по полученным записям.
4. Прочитать товар и сопоставить его поля `propertyNNN`: [`GET /v1/catalog-products/:id`](/docs/entities/catalog-products).
5. Для свойства-списка (`propertyType: "L"`) забрать все возможные варианты: [`GET /v1/catalog-product-property-enums?filter[propertyId]=166&limit=1000`](/docs/entities/catalog-product-property-enums/list).

Шаг 5 нужен, когда требуется весь набор вариантов — выпадашка, фильтр, экспорт. Для одного товара текст выбранного варианта уже приходит в `propertyNNN.valueEnum`. Форму значения у товара задаёт `listType` свойства: `L` — объект `{ value, valueEnum, valueId }`, `C` — голый скаляр `"Y"`/`"N"` (состояние галочки, а не id варианта). При `multiple: true` та же форма приходит массивом.

## Лимиты

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

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

- [Значения списочных свойств](/docs/entities/catalog-product-property-enums)
- [Товары каталога](/docs/entities/catalog-products)
- [Каталоги](/docs/entities/catalogs)
- [API сущностей](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Справочник сущностей](/docs/entities-index)