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

Справочник вариантов свойства-списка торгового каталога: чтение списка, получение одного элемента, поиск и справочник полей. Каждая запись — один вариант выпадающего списка: id элемента и его читаемый текст value. Это спутник Свойств товаров каталога: свойство с propertyType: "L" описывает поле, а эта сущность перечисляет варианты, которые в нём можно выбрать.

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

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

Список значений

GET /v1/catalog-product-property-enums

Возвращает варианты одного списочного свойства торгового каталога. Фильтр filter[propertyId] обязателен — справочник читается по одному свойству за раз.

Параметры

Для limit > 50 ответ автоматически собирается из нескольких страниц на стороне сервера. Максимум — 5000 записей за вызов.

Конец выборки определяется по meta.hasMore. Битрикс24 сообщает общее количество, поэтому meta.total и meta.hasMore достоверны — обычный цикл while (hasMore) { offset += limit } работает. Редкий крайний случай: если общее количество не придёт, платформа подставит в meta.total длину полученного окна, и на полной странице hasMore окажется false; подстраховка — сверить data.length с размером страницы.

Примеры

curl — личный ключ

curl "https://vibecode.bitrix24.tech/v1/catalog-product-property-enums?filter[propertyId]=166&limit=1000" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

curl "https://vibecode.bitrix24.tech/v1/catalog-product-property-enums?filter[propertyId]=166&limit=1000" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

const params = new URLSearchParams({ 'filter[propertyId]': '166', limit: '1000' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/catalog-product-property-enums?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
const byId = new Map(data.map(item => [String(item.id), item.value]))
console.log(byId.get('116')) // L

JavaScript — OAuth-приложение

const params = new URLSearchParams({ 'filter[propertyId]': '166', limit: '1000' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/catalog-product-property-enums?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Поля ответа

Поле id каждого элемента — это то, что приходит у товара каталога в propertyNNN.value:

товар.propertyNNN.value  →  String(элемент.id)  →  элемент.value

Свойство не списочного типа (propertyType не равен L) перечисления не имеет: запрос вернёт 200 с пустым data, а не ошибку. Доступ ограничен правами сотрудника в Битрикс24.

Пример ответа

{
  "success": true,
  "data": [
    { "id": 110, "propertyId": 166, "value": "XS", "def": false, "sort": 100, "xmlId": null },
    { "id": 112, "propertyId": 166, "value": "S",  "def": false, "sort": 200, "xmlId": null },
    { "id": 114, "propertyId": 166, "value": "M",  "def": false, "sort": 300, "xmlId": null },
    { "id": 116, "propertyId": 166, "value": "L",  "def": false, "sort": 400, "xmlId": null },
    { "id": 118, "propertyId": 166, "value": "XL", "def": false, "sort": 500, "xmlId": null }
  ],
  "meta": {
    "total": 5,
    "hasMore": false
  }
}

Пример ответа при ошибке

400 — не передан обязательный фильтр:

{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FILTER",
    "message": "GET /v1/catalog-product-property-enums requires filter fields: propertyId. Example: GET /v1/catalog-product-property-enums?filter[propertyId]=..."
  }
}

Ошибки

Полный список общих ошибок API — Ошибки.

Известные особенности

Справочники нескольких свойств забираются одним пакетным запросом — до 50 подвызовов, по одному на propertyId:

{
  "calls": [
    { "id": "sizes", "entity": "catalog-product-property-enums",
      "action": "list", "params": { "filter": { "propertyId": 166 }, "limit": 1000 } },
    { "id": "colors", "entity": "catalog-product-property-enums",
      "action": "list", "params": { "filter": { "propertyId": 162 }, "limit": 1000 } }
  ]
}

Подвызов list с limit больше 50 выходит из нативного пакета Битрикс24 и выполняется отдельным последовательным запросом со своей единицей rate-limit — см. Пакетные запросы. То есть пакетный вызов экономит обращения к API Вайбкод, но не единицы квоты Битрикс24. Явный limit при этом обязателен — см. предупреждение о полноте выдачи выше.

Передать данные между подвызовами одного батча нельзя, поэтому propertyId нужно знать заранее — из GET /v1/catalog-product-properties. Проверка обязательного фильтра на подвызовы батча не распространяется: за состав params в каждом подвызове отвечает вызывающий. Сам Битрикс24 этот фильтр обязательным не считает — подвызов без propertyId вернёт значения всех списочных свойств всех торговых каталогов сразу, то есть ответ, размер которого ничем не ограничен.

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

• Получить значение
• Поиск значений
• Поля значения
• Свойства товаров каталога
• Товары каталога
• Синтаксис фильтрации
• Справочник API