Изменить существующее пользовательское поле сделок crm.deal.userfield.update

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

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

Scope: crm

Кто может выполнять метод: администратор CRM

Метод crm.deal.userfield.update обновляет существующее пользовательское поле сделок.

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

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

Название
тип

Описание

id*
integer

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

Идентификатор можно получить с помощью методов crm.deal.userfield.add и crm.deal.userfield.list

fields*
object

Объект формата:

{
    field_1: value_1,
    field_2: value_2,
    ...,
    field_n: value_n,
}

field_n — название поля
value_n — новое значение поля

Список доступных полей описан ниже.

Некорректное поле в fields будет проигнорировано.

В fields нужно передавать только те поля, которые требуется изменить

Параметр fields

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

Параметр `тип`	Описание
MANDATORY `boolean`	Является ли поле обязательным. Возможные значения: `Y` — да `N` — нет
SHOW_FILTER `boolean`	Показывать ли поле в фильтре. Возможные значения: `Y` — да `N` — нет
XML_ID `string`	Внешний код
SETTINGS `object`	Дополнительные параметры поля. Для каждого типа поля `USER_TYPE_ID` существует свой пул доступных настроек, они описаны ниже. Поле перезаписывает лишь переданные значения
LIST `uf_enum_element[]`	Список возможных значений для пользовательского поля типа `enumeration`, описание ниже
SORT `integer`	Индекс сортировки. Обязательно больше нуля
SHOW_IN_LIST `boolean`	Показывать ли пользовательское поле в списке. Данный параметр ни на что не влияет в рамках `crm`. Возможные значения: `Y` — да `N` — нет
EDIT_IN_LIST `boolean`	Разрешать ли редактирование пользователем. Возможные значения: `Y` — да `N` — нет Значение `N` поддерживают не все типы полей в рамках `crm`
IS_SEARCHABLE `boolean`	Участвуют ли значения поля в поиске. Данный параметр ни на что не влияет в рамках `crm`. Возможные значения: `Y` — да `N` — нет
LIST_FILTER_LABEL `string`\|`lang_map`	Подпись фильтра в списке. При передаче строки она устанавливается для каждого языка. Для языков, у которых явно не указано значение, будет записано `''`. Поле полностью перезаписывает предыдущее значение
LIST_COLUMN_LABEL `string`\|`lang_map`	Заголовок в списке. При передаче строки она устанавливается для каждого языка. Для языков, у которых явно не указано значение, будет записано `''`. Поле полностью перезаписывает предыдущее значение
EDIT_FORM_LABEL `string`\|`lang_map`	Подпись в форме редактирования. При передаче строки она устанавливается для каждого языка. Для языков, у которых явно не указано значение, будет записано `''`. Поле полностью перезаписывает предыдущее значение
ERROR_MESSAGE `string`\|`lang_map`	Сообщение об ошибке
HELP_MESSAGE `string`\|`lang_map`	Помощь

Параметр SETTINGS

У каждого типа пользовательских полей существует свой набор дополнительных настроек. Данный метод поддерживает лишь те, что описаны ниже.

string

integer

double

boolean

date|datetime

enumeration

iblock_section|iblock_element

crm_status

crm

Название `тип`	Описание
DEFAULT_VALUE `string`	Значение по умолчанию
ROWS `integer`	Количество строк в поле ввода. Обязательно больше 0

Название `тип`	Описание
DEFAULT_VALUE `integer`	Значение по умолчанию

Название `тип`	Описание
DEFAULT_VALUE `double`	Значение по умолчанию
PRECISION `integer`	Точность числа. Обязательно больше или равно 0

Название
тип

Описание

DEFAULT_VALUE
integer

Значение по умолчанию, где 1 — да, 0 — нет.

Возможные значения:

>= 1 -> 1
<= 0 -> 0

DISPLAY
string

Внешний вид. Возможные значения:

CHECKBOX — флажок
RADIO — радиокнопки
DROPDOWN — выпадающий список

Название
тип

Описание

DEFAULT_VALUE
object

Значение по умолчанию.
Объект формата:

{
    VALUE: datetime|date,
    TYPE: 'NONE'|'NOW'|'FIXED',
}

где:

VALUE — значение по умолчанию типа datetime или date
TYPE — тип значения по умолчанию:
- NONE — не выставлять значение по умолчанию
- NOW — использовать текущее время/дату
- FIXED — использовать время/дату из VALUE

Название
тип

Описание

DISPLAY
string

Внешний вид. Возможные значения:

LIST — список
UI — набираемый список
CHECKBOX — флажки
DIALOG — диалог выбора сущностей

LIST_HEIGHT

Высота списка. Обязательно больше 0.

Доступен только при DISPLAY = LIST или DISPLAY = UI

Название `тип`	Описание
IBLOCK_TYPE_ID `string`	Идентификатор типа инфоблока
IBLOCK_ID `string`	Идентификатор инфоблока
DEFAULT_VALUE `string`	Значение по умолчанию
DISPLAY `string`	Внешний вид. Возможные значения: `DIALOG` — диалог `UI` — набираемый список `LIST` — список `CHECKBOX` — флажки
LIST_HEIGHT `integer`	Высота списка. Обязательно больше 0
ACTIVE_FILTER `boolean`	Показывать ли элементы с включенным флагом активности. Возможные значения: `Y` — да `N` — нет

Название
тип

Описание

ENTITY_TYPE
string

Идентификатор типа справочника.

Используйте crm.status.entity.types, чтобы узнать возможные значения

Название `тип`	Описание
LEAD `boolean`	Включена ли привязка к Лидам. Возможные значения: `Y` — да `N` — нет
CONTACT `boolean`	Включена ли привязка к Контактам. Возможные значения: `Y` — да `N` — нет
COMPANY `boolean`	Включена ли привязка к Компаниям. Возможные значения: `Y` — да `N` — нет
DEAL `boolean`	Включена ли привязка к Сделкам. Возможные значения: `Y` — да `N` — нет

Параметр LIST

Название `тип`	Описание
VALUE `string`	Значение элемента списка. Элементы списка с пустым или отсутствующим `VALUE` будут проигнорированы
SORT `integer`	Индекс сортировки. Обязательно больше или равно 0
DEF `boolean`	Является ли элемент списка значением по умолчанию. Возможные значения: `Y` — да `N` — нет Для множественного поля допустимо несколько `DEF = Y`. Для не множественного, дефолтным будет считаться первый переданный элемент списка с `DEF = Y`
XML_ID `string`	Внешний код значения. Обязательно уникальный в рамках элементов списка пользовательского поля

Примеры кода

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

Пример изменения пользовательского поля типа Строка

cURL (Webhook)

cURL (OAuth)

BX24.js

PHP

Python

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"id":536,"fields":{"MANDATORY":"N","SHOW_FILTER":"N","SETTINGS":{"DEFAULT_VALUE":"Привет, мир! Значение по умолчанию (изменено)","ROWS":10},"SORT":2000,"EDIT_IN_LIST":"N","LIST_FILTER_LABEL":"Привет, мир! Фильтр (изменено)","LIST_COLUMN_LABEL":{"en":"Hello, World! Column (changed)","ru":"Привет, мир! Колонка (изменено)","de":"Hallo, Welt! Spalte (geändert)"},"EDIT_FORM_LABEL":{"en":"Hello, World! Edit (changed)","ru":"Привет, мир! Редактировать (изменено)","de":"Hallo, Welt! Bearbeiten (geändert)"},"ERROR_MESSAGE":{"en":"Hello, World! Error (changed)","ru":"Привет, мир! Ошибка (изменено)","de":"Hallo, Welt! Fehler (geändert)"},"HELP_MESSAGE":{"en":"Hello, World! Help (changed)","ru":"Привет, мир! Помощь (изменено)","de":"Hallo, Welt! Hilfe (geändert)"}}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.deal.userfield.update

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"id":536,"fields":{"MANDATORY":"N","SHOW_FILTER":"N","SETTINGS":{"DEFAULT_VALUE":"Привет, мир! Значение по умолчанию (изменено)","ROWS":10},"SORT":2000,"EDIT_IN_LIST":"N","LIST_FILTER_LABEL":"Привет, мир! Фильтр (изменено)","LIST_COLUMN_LABEL":{"en":"Hello, World! Column (changed)","ru":"Привет, мир! Колонка (изменено)","de":"Hallo, Welt! Spalte (geändert)"},"EDIT_FORM_LABEL":{"en":"Hello, World! Edit (changed)","ru":"Привет, мир! Редактировать (изменено)","de":"Hallo, Welt! Bearbeiten (geändert)"},"ERROR_MESSAGE":{"en":"Hello, World! Error (changed)","ru":"Привет, мир! Ошибка (изменено)","de":"Hallo, Welt! Fehler (geändert)"},"HELP_MESSAGE":{"en":"Hello, World! Help (changed)","ru":"Привет, мир! Помощь (изменено)","de":"Hallo, Welt! Hilfe (geändert)"}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.deal.userfield.update

BX24.callMethod(
    'crm.deal.userfield.update',
    {
        id: 536,
        fields: {
            MANDATORY: "N",
            SHOW_FILTER: "N",
            SETTINGS: {
                DEFAULT_VALUE: "Привет, мир! Значение по умолчанию (изменено)",
                ROWS: 10,
            },
            SORT: 2000,
            EDIT_IN_LIST: "N",
            LIST_FILTER_LABEL: "Привет, мир! Фильтр (изменено)",
            LIST_COLUMN_LABEL: {
                "en": "Hello, World! Column (changed)",
                "ru": "Привет, мир! Колонка (изменено)",
                "de": "Hallo, Welt! Spalte (geändert)"
            },
            EDIT_FORM_LABEL: {
                "en": "Hello, World! Edit (changed)",
                "ru": "Привет, мир! Редактировать (изменено)",
                "de": "Hallo, Welt! Bearbeiten (geändert)"
            },
            ERROR_MESSAGE: {
                "en": "Hello, World! Error (changed)",
                "ru": "Привет, мир! Ошибка (изменено)",
                "de": "Hallo, Welt! Fehler (geändert)"
            },
            HELP_MESSAGE: {
                "en": "Hello, World! Help (changed)",
                "ru": "Привет, мир! Помощь (изменено)",
                "de": "Hallo, Welt! Hilfe (geändert)"
            },
        },
    },
    (result) => {
        result.error()
            ? console.error(result.error())
            : console.info(result.data())
        ;
    },
);

require_once('crest.php');

$result = CRest::call(
    'crm.deal.userfield.update',
    [
        'id' => 536,
        'fields' => [
            'MANDATORY' => "N",
            'SHOW_FILTER' => "N",
            'SETTINGS' => [
                'DEFAULT_VALUE' => "Привет, мир! Значение по умолчанию (изменено)",
                'ROWS' => 10,
            ],
            'SORT' => 2000,
            'EDIT_IN_LIST' => "N",
            'LIST_FILTER_LABEL' => "Привет, мир! Фильтр (изменено)",
            'LIST_COLUMN_LABEL' => [
                'en' => "Hello, World! Column (changed)",
                'ru' => "Привет, мир! Колонка (изменено)",
                'de' => "Hallo, Welt! Spalte (geändert)"
            ],
            'EDIT_FORM_LABEL' => [
                'en' => "Hello, World! Edit (changed)",
                'ru' => "Привет, мир! Редактировать (изменено)",
                'de' => "Hallo, Welt! Bearbeiten (geändert)"
            ],
            'ERROR_MESSAGE' => [
                'en' => "Hello, World! Error (changed)",
                'ru' => "Привет, мир! Ошибка (изменено)",
                'de' => "Hallo, Welt! Fehler (geändert)"
            ],
            'HELP_MESSAGE' => [
                'en' => "Hello, World! Help (changed)",
                'ru' => "Привет, мир! Помощь (изменено)",
                'de' => "Hallo, Welt! Hilfe (geändert)"
            ],
        ]
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';

from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.crm.deal.userfield.update(
        bitrix_id=536,
        fields={
            "MANDATORY": "N",
            "SHOW_FILTER": "N",
            "SETTINGS": {
                "DEFAULT_VALUE": "Привет, мир! Значение по умолчанию (изменено)",
                "ROWS": 10,
            },
            "SORT": 2000,
            "EDIT_IN_LIST": "N",
            "LIST_FILTER_LABEL": "Привет, мир! Фильтр (изменено)",
            "LIST_COLUMN_LABEL": {
                "en": "Hello, World! Column (changed)",
                "ru": "Привет, мир! Колонка (изменено)",
                "de": "Hallo, Welt! Spalte (geändert)",
            },
            "EDIT_FORM_LABEL": {
                "en": "Hello, World! Edit (changed)",
                "ru": "Привет, мир! Редактировать (изменено)",
                "de": "Hallo, Welt! Bearbeiten (geändert)",
            },
            "ERROR_MESSAGE": {
                "en": "Hello, World! Error (changed)",
                "ru": "Привет, мир! Ошибка (изменено)",
                "de": "Hallo, Welt! Fehler (geändert)",
            },
            "HELP_MESSAGE": {
                "en": "Hello, World! Help (changed)",
                "ru": "Привет, мир! Помощь (изменено)",
                "de": "Hallo, Welt! Hilfe (geändert)",
            },
        },
    ).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}")

// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "crm.deal.userfield.update", b24.Params{
	"id": 536,
	"fields": b24.Params{
		"MANDATORY":   "N",
		"SHOW_FILTER": "N",
		"SETTINGS": b24.Params{
			"DEFAULT_VALUE": "Привет, мир! Значение по умолчанию (изменено)",
			"ROWS":          10,
		},
		"SORT":              2000,
		"EDIT_IN_LIST":      "N",
		"LIST_FILTER_LABEL": "Привет, мир! Фильтр (изменено)",
		"LIST_COLUMN_LABEL": b24.Params{
			"en": "Hello, World! Column (changed)",
			"ru": "Привет, мир! Колонка (изменено)",
			"de": "Hallo, Welt! Spalte (geändert)",
		},
		"EDIT_FORM_LABEL": b24.Params{
			"en": "Hello, World! Edit (changed)",
			"ru": "Привет, мир! Редактировать (изменено)",
			"de": "Hallo, Welt! Bearbeiten (geändert)",
		},
		"ERROR_MESSAGE": b24.Params{
			"en": "Hello, World! Error (changed)",
			"ru": "Привет, мир! Ошибка (изменено)",
			"de": "Hallo, Welt! Fehler (geändert)",
		},
		"HELP_MESSAGE": b24.Params{
			"en": "Hello, World! Help (changed)",
			"ru": "Привет, мир! Помощь (изменено)",
			"de": "Hallo, Welt! Hilfe (geändert)",
		},
	},
})
if err != nil {
	return fmt.Errorf("crm.deal.userfield.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": 1753790234.592207,
        "finish": 1753790234.762644,
        "duration": 0.17043709754943848,
        "processing": 0.11566615104675293,
        "date_start": "2025-07-29T14:57:14+03:00",
        "date_finish": "2025-07-29T14:57:14+03:00",
        "operating_reset_at": 1753790834,
        "operating": 0.11564803123474121
    }
}

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

Название `тип`	Описание
result `boolean`	Корневой элемент ответа, содержит `true` в случае успеха
time `time`	Информация о времени выполнения запроса

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

HTTP-статус: 400

{
    "error": "",
    "error_description": "Access denied."
}

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

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

Код	Описание	Значение
`400`	`Parameter 'fields' must be array`	Переданный `fields` не является объектом
`400`	`ID is not defined or invalid`	Переданный `id` меньше нуля или не передан вовсе
`403`	`Access denied`	Возникает в случаях, когда: у пользователя нет административных прав пользователь пытается изменить пользовательское поле, не привязанное к сделкам
`ERROR_NOT_FOUND`	`The entity with ID 'id' is not found`	Пользовательского поля с переданным `id` не существует
`ERROR_CORE`	`Элемент списка со значением XML_ID='XML_ID' уже существует`	Переданный `XML_ID` у элемента списка обязан быть уникальным в рамках элементов списка отдельно взятого пользовательского поля

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

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

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

Была ли статья полезна?

Добавить пользовательское поле

Получить пользовательское поле сделок по Id

Изменить существующее пользовательское поле сделок crm.deal.userfield.update

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

Параметр fieldsПараметр fields

Параметр SETTINGSПараметр SETTINGS

Параметр LISTПараметр LIST

Примеры кодаПримеры кода

Пример изменения пользовательского поля типа СтрокаПример изменения пользовательского поля типа Строка

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

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

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

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

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

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

Была ли статья полезна?

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

Параметр fields

Параметр SETTINGS

Параметр LIST

Примеры кода

Пример изменения пользовательского поля типа Строка

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

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

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

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

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

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