Для AI-агентов: markdown этой страницы — /docs-content/entities/catalog-product-property-enums/list.md индекс документации — /llms.txt

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

GET /v1/catalog-product-property-enums

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

Параметры

Параметр Тип Обяз. По умолч. Описание
filter[propertyId] number да — ID свойства-владельца из GET /v1/catalog-product-properties. Без него запрос отклоняется с 400 MISSING_REQUIRED_FILTER до обращения к Битрикс24
filter object нет — Остальные условия фильтрации.
Синтаксис фильтрации. Пример: ?filter[propertyId]=166&filter[def]=true
select string нет — Выборка полей: ?select=id,value. Без select возвращаются все поля элемента
sort string нет — Поле сортировки. Префикс - — по убыванию: ?sort=-sort
limit number нет 50 Количество записей (до 5000)
offset number нет 0 Смещение от начала выборки

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

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

Примеры

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

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

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

Terminal 
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 — личный ключ

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-приложение

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_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив вариантов. Состав полей элемента — см. Поля значения
meta.total number Количество записей, соответствующих фильтру. Если Битрикс24 не сообщил его, приходит длина окна
meta.hasMore boolean Есть ли ещё записи за пределами limit. На границе окна ненадёжен — см. предупреждение выше

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

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

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

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

JSON 
{
  "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 — не передан обязательный фильтр:

JSON 
{
  "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]=..."
  }
}

Ошибки

HTTP Код Описание
400 MISSING_REQUIRED_FILTER В запросе нет ключа filter[propertyId]. Обращения к Битрикс24 не происходит
400 UNKNOWN_FILTER_FIELD Фильтр по полю, которого нет у элемента перечисления. Сообщение содержит список доступных полей
400 UNKNOWN_SORT_FIELD Сортировка по полю, которого нет у элемента перечисления. Сообщение содержит список доступных полей
403 SCOPE_DENIED API-ключ не имеет скоупа catalog
401 MISSING_API_KEY Не передан заголовок X-Api-Key

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

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

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

JSON 
{
  "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 вернёт значения всех списочных свойств всех торговых каталогов сразу, то есть ответ, размер которого ничем не ограничен.

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