Для 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 — личный ключ
curl "https://vibecode.bitrix24.tech/v1/catalog-skus/fields?iblockId=25" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
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 — личный ключ
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-приложение
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 } — в ответе только статические поля |
Пример ответа
{
"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:
{
"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 они возвращаются всегда.