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

Поля головного товара

GET /v1/catalog-skus/fields

Возвращает справочник полей головного товара с подписями, типами, признаками доступности на чтение и запись, описаниями и словарями enum там, где набор значений фиксирован, список полей для группировки в агрегации и операции, доступные в пакетном запросе.

Поля dateCreate, timestampX, dateActiveFrom и dateActiveTo не принимаются в filter: запрос возвращает 400 UNKNOWN_FILTER_FIELD до обращения к Битрикс24. Эти даты можно запрашивать через select и читать в ответе.

Параметры

Параметр Тип Обяз. Описание
iblockId (query) number нет ID информационного блока товарного каталога: поле catalogs[].iblockId из GET /v1/catalogs, а не catalogs[].id записи каталога. С ним справочник дополняется свойствами каталога propertyNNN и полем priceType. Без него, а также с iblockId каталога вариаций или несуществующего каталога приходят 24 статических поля и предупреждение fields_partial в meta.warnings

В примерах iblockId=25 — значение catalogs[].iblockId товарного каталога. Если у записи каталога id отличается, подставьте значение iblockId.

Примеры

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

Terminal
curl "https://vibecode.bitrix24.tech/v1/catalog-skus/fields?iblockId=25" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal
curl "https://vibecode.bitrix24.tech/v1/catalog-skus/fields?iblockId=25" \
  -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-skus/fields?iblockId=25', {
  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-skus/fields?iblockId=25', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

data.fields — объект, ключ которого совпадает с именем поля, а значение содержит тип, признаки доступности на запись, подпись для отображения и — у полей с фиксированным набором значений — их словарь. Состав ключей разобран в таблице после списка полей. data.aggregatable — поля для groupBy в агрегации. data.batch — операции, доступные в пакетном запросе.

Поле Тип RO Описание
id number да Идентификатор головного товара
name string нет Название головного товара. Обязательно при создании
active boolean нет Активен ли товар
iblockId number нет¹ ID товарного каталога. Список: GET /v1/catalogs. Обязателен при создании, задаётся только при создании
iblockSectionId number | null нет ID основного раздела каталога. null — товар не привязан к разделу. Список: GET /v1/catalog-sections
available boolean да Доступен ли товар к покупке. Вычисляется Битрикс24
bundle boolean да Является ли товар набором. Вычисляется Битрикс24
dateActiveFrom datetime нет Дата начала активности. В фильтре не принимается (400 UNKNOWN_FILTER_FIELD)
dateActiveTo datetime нет Дата окончания активности. В фильтре не принимается (400 UNKNOWN_FILTER_FIELD)
createdBy number да ID пользователя, создавшего товар. Список: GET /v1/users
modifiedBy number да ID пользователя, изменившего товар последним. Список: GET /v1/users
dateCreate datetime да Дата создания. В фильтре не принимается (400 UNKNOWN_FILTER_FIELD)
timestampX datetime да Дата последнего изменения. В фильтре не принимается (400 UNKNOWN_FILTER_FIELD)
code string | null нет Символьный код товара. null, если не задан
xmlId string нет Внешний код
previewText string нет Текст анонса
detailText string нет Подробное описание
previewTextType string нет Формат текста анонса: text или html
detailTextType string нет Формат подробного описания: text или html
sort number нет Порядок сортировки
previewPicture object | null нет Картинка анонса. В ответе — объект { id, url, urlMachine } или null. По полю нельзя фильтровать и сортировать
detailPicture object | null нет Детальная картинка, тот же формат. По полю нельзя фильтровать и сортировать
iblockSection object нет Массив ID всех разделов товара. Принимается при создании и изменении. В ответах get, create и update приходит массивом или null. В список и поиск не попадает и в select не поддерживается — имя отвечает предупреждением UNKNOWN_SELECT_FIELD. Список: GET /v1/catalog-sections
type number да Тип товара, вычисляется Битрикс24: 6 — головной товар без вариаций, 3 — с вариациями. В фильтре принимается одно точное число 3 или 6

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

С iblockId товарного каталога в data.fields добавляются поле priceType с типом char и свойства каталога propertyNNN с типом productproperty. Названия и типы свойств — в GET /v1/catalog-product-properties.

Заголовками запроса язык подписей и описаний не переключается. У значений enum подпись label английская, русская приходит отдельным ключом.

Поле Тип Описание
success boolean Всегда true при успехе
data.fields.<имя>.type string Тип поля: number, string, boolean, datetime, object. У свойств каталога — productproperty
data.fields.<имя>.label string Подпись поля. У статических полей — на русском, у свойств каталога совпадает с именем поля
data.fields.<имя>.description string Расширенное описание поля: назначение, где взять список допустимых значений, поведение при записи
data.fields.<имя>.readonly boolean true — поле заполняется системой и не принимается при создании и изменении
data.fields.<имя>.required boolean true — поле обязательно при создании (name, iblockId). Ключ присутствует только у таких полей
data.fields.<имя>.createOnly boolean true — поле принимается только при создании. В PATCH отклоняется с READONLY_FIELD (есть у iblockId)
data.fields.<имя>.writeOnly boolean true — поле принимается на запись и не возвращается в списке и поиске (есть у iblockSection)
data.fields.<имя>.notReturned boolean true — имя не поддерживается в select (есть у iblockSection)
data.fields.<имя>.nullable boolean true — поле может прийти со значением null. Ключ присутствует только у таких полей
data.fields.<имя>.multiple boolean true — свойство каталога хранит несколько значений и приходит массивом. Ключ присутствует только у таких свойств
data.fields.<имя>.enum array Словарь допустимых значений: массив { value, label }. Ключ есть у previewTextType и detailTextType. Отправлять нужно value, label предназначен для показа человеку
data.aggregatable string[] Поля для groupBy в агрегации: iblockSectionId
data.batch string[] Операции головного товара, доступные в пакетном запросе: create, update, delete
meta.warnings array Приходит без iblockId товарного каталога: элемент { code: "fields_partial", message } — в ответе только статические поля

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

JSON
{
  "success": true,
  "data": {
    "fields": {
      "id": {
        "type": "number",
        "readonly": true,
        "label": "Идентификатор товара",
        "description": "Уникальный идентификатор товара каталога."
      },
      "iblockId": {
        "type": "number",
        "readonly": false,
        "createOnly": true,
        "required": true,
        "label": "ID каталога",
        "description": "Каталог, которому принадлежит товар. Список: GET /v1/catalogs. Задаётся только при создании — смена через PATCH отклоняется, товар нельзя перенести между каталогами."
      },
      "code": {
        "type": "string",
        "readonly": false,
        "nullable": true,
        "label": "Символьный код",
        "description": "Символьный код товара; null, если не задан."
      },
      "iblockSection": {
        "type": "object",
        "readonly": false,
        "writeOnly": true,
        "notReturned": true,
        "label": "Разделы каталога",
        "description": "Массив ID разделов каталога, к которым относится товар. Принимается только при создании и обновлении — на чтении основной раздел приходит скаляром iblockSectionId. Список: GET /v1/catalog-sections."
      },
      "previewTextType": {
        "type": "string",
        "readonly": false,
        "label": "Формат текста анонса",
        "description": "Формат поля previewText.",
        "enum": [
          { "value": "text", "label": "Plain text", "labelRu": "Текст" },
          { "value": "html", "label": "HTML", "labelRu": "HTML" }
        ]
      },
      "type": {
        "type": "number",
        "readonly": true,
        "label": "Тип товара Битрикс24",
        "description": "Вычисляется Битрикс24. Новый головной товар сначала пустой SKU; тип меняется после привязки вариаций. В фильтре принимается только точный тип 3 или 6."
      },
      "property293": {
        "type": "productproperty",
        "readonly": false,
        "multiple": true,
        "label": "property293"
      }
    },
    "aggregatable": [
      "iblockSectionId"
    ],
    "batch": [
      "create",
      "update",
      "delete"
    ]
  }
}

Пример сокращён до семи полей — по одному на признаки readonly, createOnly с required, nullable, пару writeOnly + notReturned, словарь enum, вычисляемый тип и свойство каталога с multiple. В ответе приходят все 24 статических поля, а с iblockId товарного каталога — ещё priceType и все свойства каталога.

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

403 — у ключа нет скоупа catalog:

JSON
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'catalog' scope",
    "hint": "This request needs the 'catalog' scope, which the calling key does not carry. Add 'catalog' to this key in the developer cabinet (or through the management API), then repeat the call.",
    "cause": "key_scope_missing",
    "requiredScope": "catalog",
    "keyScopes": ["task", "im"],
    "fix": { "action": "edit_key_scopes", "via": "cabinet" },
    "userMessage": "Ключу приложения не хватает права «Товарный каталог». Добавить его можно в настройках ключа в кабинете разработчика."
  }
}

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа catalog
401 MISSING_API_KEY Не передан заголовок X-Api-Key
429 RATE_LIMITED Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики). Повторите после срока из заголовка Retry-After

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

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

Часть полей не приходит в списке по умолчанию. Символьный код code, внешний код xmlId, сортировка sort, тексты previewText, detailText с их форматами и картинки не возвращаются в ответе GET /v1/catalog-skus без явного select. Перечислите нужные имена в select, чтобы получить их в списке. В ответе одного товара GET /v1/catalog-skus/:id они возвращаются всегда.

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