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

Поля списка

Управляйте набором полей списка: получайте описания полей, создавайте новые, изменяйте и удаляйте. Справочник допустимых типов поля возвращает отдельная операция.

Битрикс24 API: lists.field.* Скоуп: lists

Поля списка

GET /v1/lists/:iblockId/fields

Возвращает описания системных и пользовательских полей списка для подготовки форм и запросов к элементам.

Параметры

Параметр Тип Обяз. По умолч. Описание
iblockId (path) string да — Идентификатор или символьный код списка. Значения — поля ID или CODE метода Список списков
iblockTypeId (query) string нет lists Тип инфоблока. Значения:
lists — обычные списки
lists_socnet — списки рабочих групп
bitrix_processes — служебные бизнес-процессы
structure — тип структуры компании, в котором находится штатный инфоблок графика отсутствий absence
socnetGroupId (query) number нет — Идентификатор рабочей группы для списков типа lists_socnet. Положительное целое число из поля id метода Список рабочих групп

Примеры

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

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

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

Terminal 
curl https://vibecode.bitrix24.tech/v1/lists/149/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/lists/149/fields', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Идентификаторы полей:', Object.keys(data))

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

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

Поля ответа

Ответ содержит справочник полей без постраничной навигации. В пути data.<FIELD_ID> вместо <FIELD_ID> используется идентификатор поля, например NAME или PROPERTY_1197. Поля meta в ответе нет.

Поле Тип Описание
success boolean Всегда true при успехе
data object Справочник: ключ — идентификатор поля FIELD_ID, значение — объект его описания
data.<FIELD_ID>.FIELD_ID string Идентификатор поля для метода Получить поле. У пользовательских полей — PROPERTY_<число>, у системных — символьный код, например NAME
data.<FIELD_ID>.NAME string Название поля для отображения
data.<FIELD_ID>.TYPE string Код типа поля. Расшифровка кодов — Типы полей
data.<FIELD_ID>.IS_REQUIRED string Обязательность заполнения: Y или N
data.<FIELD_ID>.MULTIPLE string Допускает несколько значений: Y или N
data.<FIELD_ID>.SORT number Порядок сортировки в форме
data.<FIELD_ID>.DEFAULT_VALUE string, object или null Значение по умолчанию. Формат зависит от TYPE: например, у N это строка с числом, у S:HTML — объект с ключами TYPE и TEXT
data.<FIELD_ID>.CODE string или null Символьный код пользовательского поля. null, если не задан. У системных полей отсутствует
data.<FIELD_ID>.ID string Числовой идентификатор пользовательского поля строкой — числовая часть FIELD_ID. У системных полей отсутствует
data.<FIELD_ID>.PROPERTY_TYPE string или boolean Базовый тип пользовательского поля: S, N, L, F, G или E. У системных полей — false
data.<FIELD_ID>.PROPERTY_USER_TYPE object или boolean Описание расширенного типа свойства. Содержит его базовый тип PROPERTY_TYPE, код USER_TYPE, название DESCRIPTION и обработчики, состав которых зависит от типа. false, если расширенного типа нет
data.<FIELD_ID>.LINK_IBLOCK_ID string или null Идентификатор связанного списка из поля ID метода Список списков. null, если связи нет. У системных полей отсутствует
data.<FIELD_ID>.ROW_COUNT string Высота поля ввода в строках. У системных полей отсутствует
data.<FIELD_ID>.COL_COUNT string Ширина поля ввода в символах. У системных полей отсутствует
data.<FIELD_ID>.USER_TYPE_SETTINGS object или null Настройки расширенного типа свойства. Состав зависит от TYPE, например height у S:HTML. null, если настроек нет. У системных полей отсутствует
data.<FIELD_ID>.SETTINGS object или boolean Настройки отображения поля в формах. false, если настройки не заданы. Объект возможен и у системного поля
data.<FIELD_ID>.SETTINGS.SHOW_ADD_FORM string Показывать поле при добавлении элемента: Y или N
data.<FIELD_ID>.SETTINGS.SHOW_EDIT_FORM string Показывать поле при изменении элемента: Y или N
data.<FIELD_ID>.SETTINGS.ADD_READ_ONLY_FIELD string Поле доступно только для чтения при добавлении элемента: Y или N
data.<FIELD_ID>.SETTINGS.EDIT_READ_ONLY_FIELD string Поле доступно только для чтения при изменении элемента: Y или N
data.<FIELD_ID>.SETTINGS.SHOW_FIELD_PREVIEW string Показывать поле при предварительном просмотре элемента: Y или N
data.<FIELD_ID>.IBLOCK_ID number Идентификатор списка, которому принадлежит поле. Источник — Список списков
data.<FIELD_ID>.DISPLAY_VALUES_FORM object или array Варианты выбора для типов L, G, E и E:...: ключ — идентификатор варианта, раздела или элемента, значение — название. Если вариантов нет, приходит пустой массив []

Чтобы перебрать описания полей, используйте Object.values(data). Чтобы получить их идентификаторы — Object.keys(data).

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

JSON 
{
  "success": true,
  "data": {
    "NAME": {
      "FIELD_ID": "NAME",
      "SORT": 10,
      "NAME": "Название",
      "IS_REQUIRED": "Y",
      "MULTIPLE": "N",
      "DEFAULT_VALUE": "",
      "TYPE": "NAME",
      "PROPERTY_TYPE": false,
      "PROPERTY_USER_TYPE": false,
      "SETTINGS": false,
      "IBLOCK_ID": 149
    },
    "PROPERTY_1197": {
      "FIELD_ID": "PROPERTY_1197",
      "SORT": 20,
      "NAME": "Приоритет",
      "IS_REQUIRED": "N",
      "MULTIPLE": "N",
      "DEFAULT_VALUE": "0",
      "TYPE": "N",
      "PROPERTY_TYPE": "N",
      "PROPERTY_USER_TYPE": false,
      "CODE": "PRIORITY",
      "ID": "1197",
      "LINK_IBLOCK_ID": null,
      "ROW_COUNT": "1",
      "COL_COUNT": "30",
      "USER_TYPE_SETTINGS": null,
      "SETTINGS": {
        "SHOW_ADD_FORM": "Y",
        "SHOW_EDIT_FORM": "Y",
        "ADD_READ_ONLY_FIELD": "N",
        "EDIT_READ_ONLY_FIELD": "N",
        "SHOW_FIELD_PREVIEW": "N"
      },
      "IBLOCK_ID": 149
    }
  }
}

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

404 — списка с указанным идентификатором не существует:

JSON 
{
  "success": false,
  "error": {
    "code": "LIST_NOT_FOUND",
    "message": "List not found"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_IBLOCK_TYPE iblockTypeId не входит в список допустимых типов
403 BITRIX_ACCESS_DENIED Нет прав на просмотр списка
404 LIST_NOT_FOUND Списка с указанным iblockId не существует
409 LISTS_MODULE_NOT_ENABLED На портале не подключён модуль списков
403 SCOPE_DENIED Ключу не хватает скоупа lists
401 TOKEN_MISSING У ключа нет настроенных токенов

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

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