Для 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 — личный ключ

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

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

Terminal
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 — личный ключ

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-приложение

javascript
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.

JSON
{
  "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 — не передан ключ:

JSON
{
  "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.

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