Изменить поле универсального списка lists.field.update

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: lists

Кто может выполнять метод: пользователь с правом «Полный доступ» для нужного списка

Метод lists.field.update обновляет поле списка.

Тип поля изменить нельзя. Передавайте тот тип, который был задан при создании поля

Параметры метода

Обязательные параметры отмечены *

Название
тип

Описание

IBLOCK_TYPE_ID*
string

Идентификатор типа инфоблока.

Стандартные типы:

  • lists — универсальные списки
  • bitrix_processes — процессы
  • lists_socnet — списки групп

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

Идентификатор можно получить с помощью метода lists.get.iblock.type.id

IBLOCK_ID*
integer

Идентификатор инфоблока.

Идентификатор можно получить с помощью метода lists.get

IBLOCK_CODE*
string

Cимвольный код инфоблока.

Код можно получить с помощью метода lists.get

Необходимо указать хотя бы один из параметров: IBLOCK_ID или IBLOCK_CODE

FIELDS*
array

Массив параметров.

Подробное описание

FIELD_ID*
string

Идентификатор поля. Для пользовательского поля имеет вид PROPERTY_PropertyId. Для системного поля является его символьным кодом.

Идентификатор можно получить с помощью метода lists.field.get

Параметр FIELDS

Обязательные параметры отмечены *

Название
тип

Описание

NAME*
string

Название поля

TYPE*
string

Тип поля. Изменить тип нельзя, передавайте тот, который был задан при создании поля.

Пользовательские поля:

  • S — Строка
  • N — Число
  • L — Список
  • F — Файл
  • G — Привязка к разделам
  • E — Привязка к элементам
  • S:Date — Дата
  • S:DateTime — Дата/Время
  • S:HTML — HTML/текст
  • E:EList — Привязка к элементам в виде списка
  • N:Sequence — Счетчик
  • S:ECrm — Привязка к элементам CRM
  • S:Money — Деньги
  • S:DiskFile — Файл (Диск)
  • S:map_yandex — Привязка к Яндекс.Карте
  • S:employee — Привязка к сотруднику

Системные поля:

  • SORT — Сортировка
  • ACTIVE_FROM — Начало активности
  • ACTIVE_TO — Окончание активности
  • PREVIEW_PICTURE — Изображение для анонса
  • PREVIEW_TEXT — Текст анонса
  • DETAIL_PICTURE — Детальное изображение
  • DETAIL_TEXT — Детальный текст
  • DATE_CREATE — Дата создания
  • CREATED_BY — Кем создан
  • TIMESTAMP_X — Дата изменения
  • MODIFIED_BY — Кем изменен

Значения в полях Дата создания, Дата изменения, Кем создан и Кем изменен заполняются автоматически

IS_REQUIRED
string

Флаг обязательности поля. Возможные значения:

  • Y — да
  • N — нет

MULTIPLE
string

Флаг множественности поля. Возможные значения:

  • Y — да
  • N — нет

Системные поля и поле типа Привязка к Яндекс.Карте не могут быть множественными

SORT
integer

Сортировка

DEFAULT_VALUE

Значение по умолчанию. Если включена настройка ADD_READ_ONLY_FIELD в SETTINGS, параметр становится обязательным

LIST
array

Значения для поля типа Список. Массив в формате {'ID': { 'VALUE': 'Value_1', 'SORT': 10, 'DEF': 'N' }}, где 'ID' — идентификатор, VALUE — отображаемый текст, SORT — порядок сортировки, DEF — признак значения по умолчанию.

Получить идентификатор можно методом lists.field.get

LIST_TEXT_VALUES
string

Альтернативный способ задания значений для поля типа Список. Строка, где значения разделены символом переноса \n

При обновлении поля типа Список можно использовать либо LIST, либо LIST_TEXT_VALUES, либо оба параметра вместе. В этом случае значения из строки добавятся к тем, что уже есть в массиве

LIST_DEF
array

Значение по умолчанию для поля типа Список. Массив принимает идентификатор из LIST

CODE
string

Символьный код поля. Обязателен для пользовательских полей. Для системных полей не используется

SETTINGS
array

Настройки отображения и поведения.

Поддерживаются значения:

  • SHOW_ADD_FORM — показывать в форме добавления
  • SHOW_EDIT_FORM — показывать в форме редактирования
  • ADD_READ_ONLY_FIELD — только для чтения (форма добавления)
  • EDIT_READ_ONLY_FIELD — только для чтения (форма редактирования)
  • SHOW_FIELD_PREVIEW — показать поле при формировании ссылки на элемент списка

Для включения настройки используйте Y, для выключения — N

USER_TYPE_SETTINGS
array

Массив настроек для пользовательских полей. Структура зависит от типа поля:

  • HTML/текст — массив в формате {'height': 200}, где height — высота окна редактора
  • Привязка к элементам в виде списка — массив в формате {'size': 1, 'width': 0, 'group': 'N', 'multiple': 'N'}, где size — высота списка, width — ограничение по ширине (0 - не ограничивать), group — группировка по разделам, multiple — отображение в виде списка множественного выбора
  • Счетчик — массив в формате {'write': 'N', 'VALUE': 1}, где write — разрешение изменять значения, VALUE — текущее значение счетчика
  • Привязка к элементам CRM — массив в формате {'VISIBLE': 'N', 'LEAD': 'N', 'CONTACT': 'N', 'COMPANY': 'N', 'DEAL': 'N'}, где VISIBLE — видимость в карточке CRM, LEAD — лид, CONTACT — контакт, COMPANY — компания, DEAL — сделка

ROW_COUNT
integer

Высота поля

COL_COUNT
integer

Ширина поля

LINK_IBLOCK_ID
integer

Идентификатор связанного списка. Обязателен для типов Привязка к разделам, Привязка к элементам и Привязка к элементам в виде списка

Примеры кода

Как использовать примеры в документации

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"IBLOCK_TYPE_ID":"lists","IBLOCK_ID":"123","FIELD_ID":"PROPERTY_1151","FIELDS":{"NAME":"Статус задачи","SORT":"50","IS_REQUIRED":"N","MULTIPLE":"N","TYPE":"L","LIST":{"1669":{"VALUE":"Планирование","SORT":10},"1671":{"VALUE":"В активной работе","SORT":20},"1673":{"VALUE":"Тестирование","SORT":30},"1675":{"VALUE":"Завершен","SORT":40},"1677":{"VALUE":"Отложен","SORT":50}},"LIST_TEXT_VALUES":"Архив","LIST_DEF":["1671"],"SETTINGS":{"SHOW_ADD_FORM":"Y","SHOW_EDIT_FORM":"Y","ADD_READ_ONLY_FIELD":"N","EDIT_READ_ONLY_FIELD":"Y","SHOW_FIELD_PREVIEW":"N"}}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/lists.field.update
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"IBLOCK_TYPE_ID":"lists","IBLOCK_ID":"123","FIELD_ID":"PROPERTY_1151","FIELDS":{"NAME":"Статус задачи","SORT":"50","IS_REQUIRED":"N","MULTIPLE":"N","TYPE":"L","LIST":{"1669":{"VALUE":"Планирование","SORT":10},"1671":{"VALUE":"В активной работе","SORT":20},"1673":{"VALUE":"Тестирование","SORT":30},"1675":{"VALUE":"Завершен","SORT":40},"1677":{"VALUE":"Отложен","SORT":50}},"LIST_TEXT_VALUES":"Архив","LIST_DEF":["1671"],"SETTINGS":{"SHOW_ADD_FORM":"Y","SHOW_EDIT_FORM":"Y","ADD_READ_ONLY_FIELD":"N","EDIT_READ_ONLY_FIELD":"Y","SHOW_FIELD_PREVIEW":"N"}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/lists.field.update
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

try {
  const response = await $b24.actions.v2.call.make<boolean>({
    method: 'lists.field.update',
    params: {
      IBLOCK_TYPE_ID: 'lists',
      IBLOCK_ID: '123',
      FIELD_ID: 'PROPERTY_1151',
      FIELDS: {
        NAME: 'Task status',
        SORT: '50',
        IS_REQUIRED: 'N',
        MULTIPLE: 'N',
        TYPE: 'L',
        LIST: {
          '1669': { VALUE: 'Planning', SORT: 10 },
          '1671': { VALUE: 'In progress', SORT: 20 },
          '1673': { VALUE: 'Testing', SORT: 30 },
          '1675': { VALUE: 'Done', SORT: 40 },
          '1677': { VALUE: 'On hold', SORT: 50 },
        },
        LIST_TEXT_VALUES: 'Archive',
        LIST_DEF: ['1671'],
        SETTINGS: {
          SHOW_ADD_FORM: 'Y',
          SHOW_EDIT_FORM: 'Y',
          ADD_READ_ONLY_FIELD: 'N',
          EDIT_READ_ONLY_FIELD: 'Y',
          SHOW_FIELD_PREVIEW: 'N',
        },
      },
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Field updated successfully:', result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function updateListField() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'lists.field.update',
        params: {
          IBLOCK_TYPE_ID: 'lists',
          IBLOCK_ID: '123',
          FIELD_ID: 'PROPERTY_1151',
          FIELDS: {
            NAME: 'Task status',
            SORT: '50',
            IS_REQUIRED: 'N',
            MULTIPLE: 'N',
            TYPE: 'L',
            LIST: {
              '1669': { VALUE: 'Planning', SORT: 10 },
              '1671': { VALUE: 'In progress', SORT: 20 },
              '1673': { VALUE: 'Testing', SORT: 30 },
              '1675': { VALUE: 'Done', SORT: 40 },
              '1677': { VALUE: 'On hold', SORT: 50 },
            },
            LIST_TEXT_VALUES: 'Archive',
            LIST_DEF: ['1671'],
            SETTINGS: {
              SHOW_ADD_FORM: 'Y',
              SHOW_EDIT_FORM: 'Y',
              ADD_READ_ONLY_FIELD: 'N',
              EDIT_READ_ONLY_FIELD: 'Y',
              SHOW_FIELD_PREVIEW: 'N',
            },
          },
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Field updated successfully:', result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', updateListField)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

fields = {
    "NAME": "Статус задачи",
    "SORT": "50",
    "IS_REQUIRED": "N",
    "MULTIPLE": "N",
    "TYPE": "L",
    "LIST": {
        "1669": {
            "VALUE": "Планирование",
            "SORT": 10,
        },
        "1671": {
            "VALUE": "В активной работе",
            "SORT": 20,
        },
        "1673": {
            "VALUE": "Тестирование",
            "SORT": 30,
        },
        "1675": {
            "VALUE": "Завершен",
            "SORT": 40,
        },
        "1677": {
            "VALUE": "Отложен",
            "SORT": 50,
        },
    },
    "LIST_TEXT_VALUES": "Архив",
    "LIST_DEF": [
        "1671",
    ],
    "SETTINGS": {
        "SHOW_ADD_FORM": "Y",
        "SHOW_EDIT_FORM": "Y",
        "ADD_READ_ONLY_FIELD": "N",
        "EDIT_READ_ONLY_FIELD": "Y",
        "SHOW_FIELD_PREVIEW": "N",
    },
}

try:
    bitrix_response = client.lists.field.update(
        iblock_type_id="lists",
        iblock_id=123,
        field_id="PROPERTY_1151",
        fields=fields,
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")
try {
    $response = $b24Service
        ->core
        ->call(
            'lists.field.update',
            [
                'IBLOCK_TYPE_ID' => 'lists',
                'IBLOCK_ID' => '123',
                'FIELD_ID' => 'PROPERTY_1151',
                'FIELDS' => [
                    'NAME' => 'Статус задачи',
                    'SORT' => '50',
                    'IS_REQUIRED' => 'N',
                    'MULTIPLE' => 'N',
                    'TYPE' => 'L',
                    'LIST' => [
                        '1669' => ['VALUE' => 'Планирование', 'SORT' => 10],
                        '1671' => ['VALUE' => 'В активной работе', 'SORT' => 20],
                        '1673' => ['VALUE' => 'Тестирование', 'SORT' => 30],
                        '1675' => ['VALUE' => 'Завершен', 'SORT' => 40],
                        '1677' => ['VALUE' => 'Отложен', 'SORT' => 50]
                    ],
                    'LIST_TEXT_VALUES' => 'Архив',
                    'LIST_DEF' => ['1671'],
                    'SETTINGS' => [
                        'SHOW_ADD_FORM' => 'Y',
                        'SHOW_EDIT_FORM' => 'Y',
                        'ADD_READ_ONLY_FIELD' => 'N',
                        'EDIT_READ_ONLY_FIELD' => 'Y',
                        'SHOW_FIELD_PREVIEW' => 'N'
                    ]
                ]
            ]
        );

    $result = $response
        ->getResponseData()
        ->getResult();

    echo 'Success: ' . print_r($result, true);
    processData($result);

} catch (Throwable $e) {
    error_log($e->getMessage());
    echo 'Error updating field: ' . $e->getMessage();
}
BX24.callMethod(
    'lists.field.update',
    {
        'IBLOCK_TYPE_ID': 'lists',
        'IBLOCK_ID': '123',
        'FIELD_ID': 'PROPERTY_1151',
        'FIELDS': {
            'NAME': 'Статус задачи',
            'SORT': '50',
            'IS_REQUIRED': 'N',
            'MULTIPLE': 'N',
            'TYPE': 'L', // Тип менять нельзя, используем тот, что есть
            'LIST': {
                '1669': { 'VALUE': 'Планирование', 'SORT': 10 },
                '1671': { 'VALUE': 'В активной работе', 'SORT': 20 },
                '1673': { 'VALUE': 'Тестирование', 'SORT': 30 },
                '1675': { 'VALUE': 'Завершен', 'SORT': 40 },
                '1677': { 'VALUE': 'Отложен', 'SORT': 50 }
            },
            'LIST_TEXT_VALUES': 'Архив',
            'LIST_DEF': ['1671'], // Задаем новый вариант по умолчанию
            'SETTINGS': {
                'SHOW_ADD_FORM': 'Y',
                'SHOW_EDIT_FORM': 'Y',
                'ADD_READ_ONLY_FIELD': 'N',
                'EDIT_READ_ONLY_FIELD': 'Y',
                'SHOW_FIELD_PREVIEW': 'N'
            }
        }
    },
    function(result) {
        if (result.error()) {
            console.error(result.error());
        } else {
            console.log(result.data());
        }
    }
);
require_once('crest.php');

$result = CRest::call(
    'lists.field.update',
    [
        'IBLOCK_TYPE_ID' => 'lists',
        'IBLOCK_ID' => '123',
        'FIELD_ID' => 'PROPERTY_1151',
        'FIELDS' => [
            'NAME' => 'Статус задачи',
            'SORT' => '50',
            'IS_REQUIRED' => 'N',
            'MULTIPLE' => 'N',
            'TYPE' => 'L',
            'LIST' => [
                '1669' => ['VALUE' => 'Планирование', 'SORT' => 10],
                '1671' => ['VALUE' => 'В активной работе', 'SORT' => 20],
                '1673' => ['VALUE' => 'Тестирование', 'SORT' => 30],
                '1675' => ['VALUE' => 'Завершен', 'SORT' => 40],
                '1677' => ['VALUE' => 'Отложен', 'SORT' => 50]
            ],
            'LIST_TEXT_VALUES' => 'Архив',
            'LIST_DEF' => ['1671'],
            'SETTINGS' => [
                'SHOW_ADD_FORM' => 'Y',
                'SHOW_EDIT_FORM' => 'Y',
                'ADD_READ_ONLY_FIELD' => 'N',
                'EDIT_READ_ONLY_FIELD' => 'Y',
                'SHOW_FIELD_PREVIEW' => 'N'
            ]
        ]
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "lists.field.update", b24.Params{
	"IBLOCK_TYPE_ID": "lists",
	"IBLOCK_ID":      "123",
	"FIELD_ID":       "PROPERTY_1151",
	"FIELDS": b24.Params{
		"NAME":        "Статус задачи",
		"SORT":        "50",
		"IS_REQUIRED": "N",
		"MULTIPLE":    "N",
		"TYPE":        "L",
		"LIST": b24.Params{
			"1669": b24.Params{
				"VALUE": "Планирование",
				"SORT":  10,
			},
			"1671": b24.Params{
				"VALUE": "В активной работе",
				"SORT":  20,
			},
			"1673": b24.Params{
				"VALUE": "Тестирование",
				"SORT":  30,
			},
			"1675": b24.Params{
				"VALUE": "Завершен",
				"SORT":  40,
			},
			"1677": b24.Params{
				"VALUE": "Отложен",
				"SORT":  50,
			},
		},
		"LIST_TEXT_VALUES": "Архив",
		"LIST_DEF":         []string{"1671"},
		"SETTINGS": b24.Params{
			"SHOW_ADD_FORM":        "Y",
			"SHOW_EDIT_FORM":       "Y",
			"ADD_READ_ONLY_FIELD":  "N",
			"EDIT_READ_ONLY_FIELD": "Y",
			"SHOW_FIELD_PREVIEW":   "N",
		},
	},
})
if err != nil {
	return fmt.Errorf("lists.field.update: %w", err)
}

var ok bool
if err := json.Unmarshal(res.Result, &ok); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println("выполнено:", ok)

Обработка ответа

HTTP-статус: 200

{
    "result": true,
    "time": {
        "start": 1765371241,
        "finish": 1765371241.084551,
        "duration": 0.08455109596252441,
        "processing": 0,
        "date_start": "2025-12-09T16:54:01+03:00",
        "date_finish": "2025-12-09T16:54:01+03:00",
        "operating_reset_at": 1765371841,
        "operating": 0
    }
}

Возвращаемые данные

Название
тип

Описание

result
boolean

Возвращает true, если поле обновлено успешно

time
time

Информация о времени выполнения запроса

Обработка ошибок

HTTP-статус: 400

{
    "error":"ERROR_UPDATE_FIELD",
    "error_description":"Error update the field"
}

Название
тип

Описание

error
string

Строковый код ошибки. Состоит из цифр, латинских букв и знака подчеркивания. Может прийти пустым — тогда причину показывает только error_description

error_description
string

Текст ошибки для разработчика. Не показывайте его конечному пользователю без обработки

Возможные коды ошибок

Код

Описание

Значение

ERROR_REQUIRED_PARAMETERS_MISSING

Required parameter X is missing

Обязательный параметр не передан

ERROR_IBLOCK_NOT_FOUND

Iblock not found

Инфоблок не найден

ERROR_UPDATE_FIELD

Error update the field

Ошибка при обновлении поля

ERROR_UPDATE_FIELD

The default value of the field '...' is required

Включена настройка ADD_READ_ONLY_FIELD, но не указано DEFAULT_VALUE

ERROR_UPDATE_FIELD

Incorrect lists specified for '...' property

Ошибка в одном из параметров внутри FIELDS

ACCESS_DENIED

Access denied

Недостаточно прав для обновления поля

Статусы и коды системных ошибок

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

Возникла внутренняя ошибка сервера. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

Сервер вернул неожиданный ответ. Повторите вызов, а если ошибка сохраняется, обратитесь к администратору сервера или в техническую поддержку Битрикс24

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически, когда накопленное время выполнения метода перестает превышать лимит

401

NO_AUTH_FOUND
Wrong authorization data

В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука

401

INVALID_REQUEST
Https required

Методы вызываются только по протоколу HTTPS

401

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка. Чтобы ее снять, обратитесь в техническую поддержку Битрикс24

401

ACCESS_DENIED
REST is available only on commercial plans

REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом

404

ERROR_METHOD_NOT_FOUND
Method not found!

Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа

401

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на provided by the access token

401

expired_token
The access token provided has expired

Срок действия access-токена истек

401

user_access_error
The user does not have access to the application

Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям

403

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть ее на коробочной установке, отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение