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

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

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

Создать свойство товара

POST /v1/catalog-product-properties

Создаёт свойство товара в каталоге. Поля передаются плоско в корне JSON. В ответ приходит полный объект созданного свойства.

Поля запроса (body)

Поле Тип Обяз. Описание
iblockId number да ID каталога. Список: GET /v1/catalogs
name string да Название свойства для отображения
propertyType string да Базовый тип. N число, S строка, L список, F файл, E привязка к элементу, G привязка к разделу
code string нет Символьный код. Латинские буквы, цифры, подчёркивание. Первый символ не цифра
active boolean нет Активно ли свойство. По умолчанию true
sort number нет Индекс сортировки
defaultValue string нет Значение по умолчанию
userType string нет Пользовательский тип, например directory, DateTime, Money, HTML
userTypeSettings object нет Настройки пользовательского типа
listType string нет Вид списка. L выпадающий, C флажки
multiple boolean нет Множественное значение
multipleCnt number нет Число полей ввода для множественных значений
withDescription boolean нет Поле описания значения
searchable boolean нет Участвует в поиске
filtrable boolean нет Участвует в фильтре
isRequired boolean нет Обязательное к заполнению
linkIblockId number нет ID связанного каталога для типов привязки
fileType string нет Допустимые расширения файлов для типа F
xmlId string нет Внешний идентификатор
hint string нет Подсказка к полю

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-product-properties" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "iblockId": 19,
    "name": "Материал",
    "propertyType": "S"
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/catalog-product-properties" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "iblockId": 19,
    "name": "Материал",
    "propertyType": "S"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-product-properties', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    iblockId: 19,
    name: 'Материал',
    propertyType: 'S',
  }),
})

const { success, data } = await res.json()
console.log('Property ID:', data.id)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-product-properties', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    iblockId: 19,
    name: 'Материал',
    propertyType: 'S',
  }),
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Полный объект созданного свойства. Набор полей — как у `GET /v1/catalog-product-properties/:id`

Идентификатор созданного свойства id совпадает с NNN в ключе propertyNNN, которым значение этого свойства приходит у товара в Товары каталога:

propertyNNN  →  property659

NNN — значение поля id. По нему строится сопоставление id → name для подписи значений propertyNNN.

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

Показаны основные поля.

JSON 
{
  "success": true,
  "data": {
    "id": 659,
    "iblockId": 19,
    "name": "Материал",
    "propertyType": "S",
    "code": "s12",
    "active": true,
    "sort": null,
    "defaultValue": null,
    "userType": "directory",
    "userTypeSettings": {
      "group": "N",
      "multiple": "N",
      "size": 1,
      "tableName": "b_hlbd_categories",
      "width": 0
    },
    "listType": "L",
    "multiple": false,
    "multipleCnt": null,
    "withDescription": null,
    "searchable": false,
    "filtrable": false,
    "isRequired": false,
    "linkIblockId": null,
    "fileType": null,
    "xmlId": null,
    "hint": null,
    "timestampX": "2026-03-19T18:23:02.000Z"
  }
}

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

422 — не передано обязательное поле:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required fields: name"
  }
}

Ошибки

HTTP Код Описание
422 BITRIX_ERROR Не передано обязательное поле — сообщение перечисляет недостающие (Required fields: name, Required fields: propertyType)
422 BITRIX_ERROR Каталог с указанным iblockId не найден (Iblock Not Found)
400 READONLY_FIELD В теле передано поле только для чтения, например id или timestampX
403 SCOPE_DENIED Ключу не хватает скоупа catalog
401 MISSING_API_KEY Не передан заголовок X-Api-Key

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

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