Поля товара

GET /v1/catalog-products/fields

Возвращает справочник полей товара с типами и признаком «только для чтения», список полей, доступных для агрегации, а также операции, доступные в пакетном запросе.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/catalog-products/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/catalog-products/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-products/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Полей:', Object.keys(data.fields).length)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-products/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

data.fields — объект, ключ которого совпадает с именем поля, а значение содержит type (тип поля) и readonly (можно ли передать поле при создании и обновлении). data.aggregatable — поля, по которым работает агрегация. data.batch — операции, доступные в пакетном запросе.

Поле Тип RO Описание
id number да Идентификатор товара
name string нет Название товара
active boolean нет Активен ли товар
iblockId number нет¹ ID каталога. Список: `GET /v1/catalogs`. Задаётся только при создании; смена через PATCH отклоняется — товар нельзя перенести между каталогами
iblockSectionId number нет ID раздела каталога. Список: `GET /v1/catalog-sections`
purchasingPrice number нет Закупочная цена
purchasingCurrency string нет Валюта закупочной цены, например RUB. Список: `GET /v1/currencies`
quantity number нет Остаток на складе
weight number нет Вес единицы товара
measure number нет ID единицы измерения
available boolean да Доступен ли товар к покупке. Вычисляется Битрикс24
vatIncluded boolean нет НДС включён в цену
bundle boolean да Является ли товар набором. Вычисляется Битрикс24
canBuyZero boolean нет Разрешить покупку при нулевом остатке
quantityTrace boolean нет Включён учёт количества
subscribe boolean нет Разрешить подписку на товар
barcodeMulti boolean нет Разрешены отдельные штрихкоды для единиц товара
withoutOrder boolean нет Доступен к заказу без наличия на складе
dateActiveFrom datetime нет Дата начала активности товара
dateActiveTo datetime нет Дата окончания активности товара
createdBy number да ID пользователя, создавшего товар. Заполняется системой
modifiedBy number да ID пользователя, изменившего товар. Заполняется системой
dateCreate datetime да Дата создания товара
timestampX datetime да Дата последнего изменения

¹ iblockId доступен для записи только при создании (createOnly) — в справочнике приходит с readonly: false и createOnly: true.

Поле Тип Описание
success boolean Всегда true при успехе
data.fields.<имя>.type string Тип поля: number, string, boolean, datetime
data.fields.<имя>.readonly boolean true — поле заполняется системой и не принимается при создании и обновлении
data.fields.<имя>.createOnly boolean true — поле принимается только при создании; в PATCH отклоняется с READONLY_FIELD (есть у iblockId)
data.aggregatable string[] Поля, по которым работает агрегация
data.batch string[] Операции товара, доступные в пакетном запросе: create, update, delete

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

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "name": { "type": "string", "readonly": false },
      "active": { "type": "boolean", "readonly": false },
      "iblockId": { "type": "number", "readonly": false, "createOnly": true },
      "iblockSectionId": { "type": "number", "readonly": false },
      "purchasingPrice": { "type": "number", "readonly": false },
      "purchasingCurrency": { "type": "string", "readonly": false },
      "quantity": { "type": "number", "readonly": false },
      "weight": { "type": "number", "readonly": false },
      "measure": { "type": "number", "readonly": false },
      "available": { "type": "boolean", "readonly": true },
      "vatIncluded": { "type": "boolean", "readonly": false },
      "bundle": { "type": "boolean", "readonly": true },
      "canBuyZero": { "type": "boolean", "readonly": false },
      "quantityTrace": { "type": "boolean", "readonly": false },
      "subscribe": { "type": "boolean", "readonly": false },
      "barcodeMulti": { "type": "boolean", "readonly": false },
      "withoutOrder": { "type": "boolean", "readonly": false },
      "dateActiveFrom": { "type": "datetime", "readonly": false },
      "dateActiveTo": { "type": "datetime", "readonly": false },
      "createdBy": { "type": "number", "readonly": true },
      "modifiedBy": { "type": "number", "readonly": true },
      "dateCreate": { "type": "datetime", "readonly": true },
      "timestampX": { "type": "datetime", "readonly": true }
    },
    "aggregatable": ["purchasingPrice", "quantity", "iblockSectionId"],
    "batch": ["create", "update", "delete"]
  }
}

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

403 — нет скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'catalog' scope"
  }
}

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа catalog
401 MISSING_API_KEY Не передан заголовок X-Api-Key

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

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

Запись зависит от управления складом. Поля quantity, purchasingPrice и purchasingCurrency помечены в справочнике как доступные для записи, но при включённом на портале управлении складом не применяются при создании и изменении товара — остатки и закупочные цены ведутся складскими документами.

Ответ GET /:id шире справочника. Запрос одного товара по id возвращает дополнительные поля — символьный код, размеры, тип и пользовательские свойства каталога вида propertyNNN. Они не входят в справочник полей и недоступны для фильтрации и сортировки.

Каталог товара (iblockId) неизменяем. Каталог выбирается при создании; Битрикс24 не переносит товар между каталогами через обновление. PATCH со сменой iblockId отклоняется с 400 READONLY_FIELD — раньше такой запрос возвращал 200, но товар оставался в прежнем каталоге (ложный успех).

Поля аудита защищены. createdBy и modifiedBy заполняются Битрикс24 и не принимаются при создании и обновлении — попытка передать их отклоняется с 400 READONLY_FIELD.

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