# Значения списочных свойств каталога

Справочник вариантов свойства-списка торгового каталога: чтение списка, получение одного элемента, поиск и справочник полей. Каждая запись — один вариант выпадающего списка: `id` элемента и его читаемый текст `value`. Это спутник [Свойств товаров каталога](/docs/entities/catalog-product-properties): свойство с `propertyType: "L"` описывает поле, а эта сущность перечисляет варианты, которые в нём можно выбрать.

Отсюда берётся то, чего не даёт ни один эндпоинт товара: **все возможные** значения списочного свойства, а не только выбранное у конкретного товара.

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

## Операции

- [Список значений](./catalog-product-property-enums/list.md) — `GET /v1/catalog-product-property-enums`
- [Получить значение](./catalog-product-property-enums/get.md) — `GET /v1/catalog-product-property-enums/:id`
- [Поиск значений](./catalog-product-property-enums/search.md) — `POST /v1/catalog-product-property-enums/search`
- [Поля значения](./catalog-product-property-enums/fields.md) — `GET /v1/catalog-product-property-enums/fields`

Сущность только для чтения: `POST`, `PATCH`, `DELETE` и `POST /aggregate` не зарегистрированы и отвечают `404`.

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

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | ID элемента перечисления. Именно он приходит у товара каталога в `propertyNNN.value` |
| `propertyId` | number | ID свойства-владельца. Обязателен в фильтре |
| `value` | string | Читаемый текст варианта — тот же, что приходит у товара в `propertyNNN.valueEnum` |
| `def` | boolean | Является ли вариант значением свойства по умолчанию |
| `sort` | number | Индекс сортировки внутри свойства |
| `xmlId` | string | Внешний код. Приходит `null`, если не задан |

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

1. **`filter[propertyId]` обязателен.** Справочник читается по одному свойству за раз. Запрос без этого фильтра отклоняется с `400 MISSING_REQUIRED_FILTER` ещё до обращения к Битрикс24 — на обеих доступных поверхностях: списке и [поиске](./catalog-product-property-enums/search.md). `propertyId` берётся из [`GET /v1/catalog-product-properties`](/docs/entities/catalog-product-properties). Проверка смотрит на **наличие** ключа, а не на форму значения, и не распространяется на подвызовы [пакетного запроса](/docs/batch) — это ограничитель стоимости и подсказка, а не граница доступа: то, что доступно ключу со скоупом `catalog`, доступно ему и без этого фильтра.
2. **Перечисление есть только у `propertyType: "L"`.** Сначала прочитайте тип свойства: [`GET /v1/catalog-product-properties/:id`](/docs/entities/catalog-product-properties/get). Для свойства любого другого типа (`S` строка, `N` число, `F` файл, `E`/`G` привязки) запрос вернёт **пустой список**, а не ошибку.
3. **Связь с полями товара идёт через `id`.** У товара каталога значение свойства-списка приходит в поле `propertyNNN`, где `NNN` — `id` свойства. Внутри — `value` (это `id` элемента перечисления, строкой), `valueEnum` (готовый читаемый текст) и `valueId` (id строки значения). Сопоставление делается по `String(элемент.id) === товар.propertyNNN.value` — `value` у товара строковый, а `id` справочника числовой.
4. **Форма значения у товара зависит от `listType` свойства.** При `listType: "L"` (выпадающий список) приходит объект с тройкой полей выше. При `listType: "C"` (флажок) приходит голый скаляр `"Y"`/`"N"` — это состояние галочки, а не идентификатор варианта. Справочник у такого свойства всё равно есть и возвращает одну запись — подпись отмеченного состояния (например `value: "да"`). Соединять её с товаром по `id` нельзя: товар несёт флаг, а не id элемента. При `multiple: true` та же форма приходит массивом — разворачивать нужно каждый элемент.
5. **Пагинация обычная: `limit` + `offset`, конец выборки — по `meta.hasMore`.** Битрикс24 сообщает общее количество, поэтому `meta.total` и `meta.hasMore` достоверны. Потолок — 5000 записей за вызов, значение по умолчанию — 50. Редкий крайний случай: если общее количество не придёт, платформа подставит в `meta.total` длину полученного окна, и на полной странице `hasMore` окажется `false` — подстраховаться можно, сверив `data.length` с размером страницы.
6. **Все поля доступны только для чтения.** Варианты списка заводятся в интерфейсе Битрикс24. `GET /v1/catalog-product-property-enums/fields` возвращает `batch: []` — записывающих операций у сущности нет.

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

Задача: показать пользователю выпадашку со **всеми** размерами и подсветить тот, что выбран у товара.

1. Узнать `iblockId` каталога: [`GET /v1/catalogs`](/docs/entities/catalogs). Делается один раз и кэшируется.
2. Прочитать схему свойств каталога: [`GET /v1/catalog-product-properties?filter[iblockId]=26`](/docs/entities/catalog-product-properties/list). Здесь важны три поля свойства — `propertyType` (перечисление есть только у `L`), `listType` (объект или голый скаляр у товара) и `multiple` (один объект или массив). Кэшируется вместе с шагом 1.
3. Забрать справочник вариантов: [`GET /v1/catalog-product-property-enums?filter[propertyId]=166&limit=1000`](./catalog-product-property-enums/list.md). Построить карту `String(id) → value`.
4. Прочитать товар: [`GET /v1/catalog-products/160`](/docs/entities/catalog-products/get) — в `property166.value` придёт `"116"`, и карта развернёт его в `L`.

Для одного товара шаг 3 не нужен: текст уже лежит в `property166.valueEnum`. Справочник нужен ровно тогда, когда требуются **все** варианты — выпадашка, фильтр, экспорт.

Справочники для нескольких свойств сразу забираются одним [пакетным запросом](/docs/batch) — до 50 подвызовов, по одному на `propertyId`. Пример тела — в разделе «Известные особенности» на странице [списка значений](./catalog-product-property-enums/list.md). Передать данные между подвызовами одного батча нельзя: поэтому шаг 2 остаётся отдельным кэшируемым вызовом, а батч экономит N справочников по **уже известным** `propertyId`.

## Лимиты

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

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

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