Для AI-агентов: markdown этой страницы — /docs-content/entities/catalog-services/fields.md индекс документации — /llms.txt
Поля услуги
GET /v1/catalog-services/fields
Возвращает справочник полей услуги каталога с подписями, типами, признаками записи и словарями допустимых значений, а также поля для агрегации и операции пакетного запроса.
Справочник содержит 28 статических полей услуги. Укажите ?iblockId=<ID каталога>, чтобы при успешном ответе Битрикс24 получить также свойства каталога вида propertyNNN. ID каталога можно получить в GET /v1/catalogs. Значения свойств приходят в ответе GET /v1/catalog-services/:id, названия и типы доступны также в GET /v1/catalog-product-properties.
Поля dateCreate, timestampX, dateActiveFrom и dateActiveTo не принимаются в filter: запрос возвращает 400 UNKNOWN_FILTER_FIELD до обращения к Битрикс24. Эти даты можно запрашивать через select и читать в ответе.
Параметры
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
iblockId (query) |
number | нет | ID товарного каталога из GET /v1/catalogs, у этого каталога не заполнен productIblockId. С ним успешный ответ дополняется свойствами каталога propertyNNN. Без параметра, а также когда Битрикс24 отказал в выдаче динамического справочника (например, каталога с таким ID нет), приходят 28 статических полей и предупреждение fields_partial в meta.warnings |
Примеры
curl — личный ключ
curl "https://vibecode.bitrix24.tech/v1/catalog-services/fields?iblockId=25" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl "https://vibecode.bitrix24.tech/v1/catalog-services/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-services/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-services/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 | нет | Активна ли услуга |
available |
boolean | нет | Доступна ли услуга к покупке. Без явного значения услуга создаётся с false |
iblockId |
number | нет¹ | ID товарного каталога. Список: GET /v1/catalogs. Обязателен при создании, задаётся только при создании |
type |
number | да | Тип записи, у услуги всегда 7. Заполняется Битрикс24 |
iblockSectionId |
number | null | нет | ID основного раздела каталога. null — услуга не привязана к разделу. Список: GET /v1/catalog-sections |
iblockSection |
object | нет | Массив ID всех разделов каталога, к которым относится услуга. Приходит в ответе одной услуги, в select списка не поддерживается. Список: GET /v1/catalog-sections |
measure |
number | нет | ID единицы измерения. Список: GET /v1/catalog-measures |
vatIncluded |
boolean | нет | НДС включён в цену |
vatId |
number | нет | ID ставки НДС. Список: GET /v1/catalog-vat-rates |
bundle |
boolean | да | Является ли услуга набором. Вычисляется Битрикс24 |
code |
string | null | нет | Символьный код. null, если не задан |
xmlId |
string | нет | Внешний идентификатор. Если не задан, равен id услуги строкой |
sort |
number | нет | Порядок сортировки. По умолчанию 500 |
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) |
previewText |
string | нет | Текст анонса |
previewTextType |
string | нет | Формат текста анонса: text или html |
detailText |
string | нет | Подробное описание |
detailTextType |
string | нет | Формат подробного описания: text или html |
previewPicture |
object | нет | Изображение анонса |
detailPicture |
object | нет | Детальное изображение |
priceType |
string | нет | Объявлено в справочнике, но в ответах списка и одной услуги не возвращается. Цены услуги задаются в POST /v1/catalog-prices |
propertyNNN |
productproperty | нет | Свойство каталога, где NNN — id свойства из GET /v1/catalog-product-properties. Приходит только с iblockId, у множественных свойств — с multiple: true. Тип приходит от Битрикс24 как есть и в пятёрку типов статических полей не входит |
¹ iblockId доступен для записи только при создании — в справочнике приходит с readonly: false и createOnly: true.
Подписи label и описания description полей приходят на русском. У значений enum подпись label английская, русская приходит отдельным ключом labelRu.
| Поле | Тип | Описание |
|---|---|---|
success |
boolean | Всегда true при успехе |
data.fields.<имя>.type |
string | Тип поля. У 28 статических полей — number, string, boolean, datetime, object. У динамических полей каталога, которые приходят с iblockId, — тип Битрикс24 как есть, например productproperty у свойства каталога |
data.fields.<имя>.label |
string | Короткая подпись поля |
data.fields.<имя>.description |
string | Расширенное описание поля: назначение, где взять список допустимых значений, поведение при записи |
data.fields.<имя>.readonly |
boolean | true — поле заполняется системой и не принимается при создании и изменении |
data.fields.<имя>.createOnly |
boolean | true — поле принимается только при создании, в PATCH отклоняется с READONLY_FIELD. Есть у iblockId |
data.fields.<имя>.writeOnly |
boolean | true — поле принимается на запись. Есть у iblockSection |
data.fields.<имя>.notReturned |
boolean | true — имя поля не поддерживается в select: список и поиск отклоняют его с SELECT_FIELD_NOT_RETURNED. Есть у iblockSection |
data.fields.<имя>.nullable |
boolean | true — поле может прийти со значением null. Ключ присутствует только у таких полей |
data.fields.<имя>.enum |
array | Словарь допустимых значений: массив { value, label, labelRu }. Есть у previewTextType и detailTextType. Отправлять нужно value, подписи предназначены для показа человеку |
data.fields.<имя>.multiple |
boolean | true — динамическое поле каталога хранит несколько значений и приходит массивом. Ключ присутствует только у таких полей |
data.fields.<имя>.items |
array | Элементы списка динамического поля с типом enumeration — как их вернул Битрикс24. Ключ присутствует только у таких полей |
data.fields.<имя>.values |
array | Словарь значений динамического поля: массив { value, label }. Ключ присутствует, когда Битрикс24 вернул такой словарь |
data.fields.<имя>.default |
number | string | boolean | null | Значение по умолчанию динамического поля. Ключ присутствует, когда Битрикс24 вернул его скаляром или null |
data.aggregatable |
string[] | Поля для groupBy в агрегации: iblockSectionId |
data.batch |
string[] | Операции услуги, доступные в пакетном запросе: create, update, delete |
meta.warnings |
array | Предупреждения. Элемент с code: fields_partial приходит без iblockId или когда Битрикс24 не вернул динамический справочник |
Пример ответа
Ответ без iblockId: только статические поля и предупреждение fields_partial.
{
"success": true,
"data": {
"fields": {
"id": {
"type": "number",
"readonly": true,
"label": "Идентификатор услуги",
"description": "Уникальный идентификатор услуги каталога."
},
"iblockId": {
"type": "number",
"readonly": false,
"createOnly": true,
"label": "ID каталога",
"description": "Каталог, которому принадлежит товар. Список: GET /v1/catalogs. Задаётся только при создании — смена через PATCH отклоняется, товар нельзя перенести между каталогами."
},
"type": {
"type": "number",
"readonly": true,
"label": "Тип услуги",
"description": "Тип услуги Битрикс24 (7); устанавливается Битрикс24 и доступен только для чтения."
},
"iblockSectionId": {
"type": "number",
"readonly": false,
"nullable": true,
"label": "ID раздела каталога",
"description": "Основной раздел каталога у услуги; null, если товар не привязан к разделу. Список: GET /v1/catalog-sections."
},
"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" }
]
}
},
"aggregatable": [
"iblockSectionId"
],
"batch": [
"create",
"update",
"delete"
]
},
"meta": {
"warnings": [
{
"code": "fields_partial",
"message": "Dynamic field metadata from Bitrix24 was unavailable; the response carries static schema fields only and some labels may be missing. Retry to obtain the complete set."
}
]
}
}
Пример сокращён до шести полей — по одному на признаки readonly, createOnly, вычисляемый type, nullable, пару writeOnly + notReturned и словарь enum. Статический справочник содержит 28 полей. С iblockId успешный ответ содержит те же статические поля плюс свойства каталога propertyNNN, предупреждения fields_partial в нём нет. У свойства каталога type приходит от Битрикс24 как есть (productproperty), у множественного свойства есть ключ multiple: true, а когда Битрикс24 вернул словарь значений или значение по умолчанию — ключи values, items и default.
Пример ответа при ошибке
401 — не передан ключ:
{
"success": false,
"error": {
"code": "MISSING_API_KEY",
"message": "API key required. Pass via X-Api-Key header."
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| 403 | SCOPE_DENIED |
API-ключ не имеет скоупа catalog |
| 401 | MISSING_API_KEY |
Не передан заголовок X-Api-Key |
| 429 | RATE_LIMITED |
Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики). Повторите после срока из заголовка Retry-After |
Полный список общих ошибок API — Ошибки.
Известные особенности
Для свойств каталога нужен iblockId. Без номера каталога возвращаются статические поля и fields_partial. С ?iblockId=<ID каталога> при успешном ответе Битрикс24 справочник включает свойства propertyNNN, а предупреждение отсутствует. Если Битрикс24 не вернул динамические поля, статический ответ с предупреждением сохраняется.
Часть полей не приходит в списке по умолчанию. Символьный код code, внешний код xmlId, сортировка sort, ставка vatId, тексты, картинки и свойства propertyNNN не возвращаются в ответе GET /v1/catalog-services без явного ?select=. Перечислите нужные имена в select, чтобы получить их в списке. В ответе одной услуги GET /v1/catalog-services/:id они возвращаются всегда.
Описания называют запись товаром. В description части полей — например, iblockId, active и createdBy — услуга называется товаром. Речь идёт об услуге: type у каждой записи этого метода равен 7.