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

Scope: crm

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

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

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

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

Название
тип

Описание

id*
integer

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

Идентификатор можно получить с помощью методов crm.contact.userfield.add и crm.contact.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 — нет

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

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

Название
тип

Описание

DEFAULT_VALUE
string

Значение по умолчанию

ROWS
integer

Количество строк в поле ввода. Обязательно больше 0 и меньше 50.

Если передавать значение <= 0, то выставится значение 1.

Если передавать значение >= 50, то выставиться значение 50

Название
тип

Описание

DEFAULT_VALUE
integer

Значение по умолчанию

Название
тип

Описание

DEFAULT_VALUE
double

Значение по умолчанию

PRECISION
integer

Точность числа. Обязательно больше или равно 0.

Если передавать невалидное значение, выставится значение 2

Название
тип

Описание

DEFAULT_VALUE
integer

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

При передаче значения выставится значение по правилу:

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

DISPLAY
string

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

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

Название
тип

Описание

DEFAULT_VALUE
object

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

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

где

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

При передаче невалидного значения выставиться:

    VALUE: '',
            TYPE: 'NONE',

Название
тип

Описание

DISPLAY
string

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

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

LIST_HEIGHT

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

Название
тип

Описание

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 = Y)

Название
тип

Описание

LEAD
boolean

Включена ли привязка к Лидам. Возможные значения:

  • Y — да
  • N — нет

CONTACT
boolean

Включена ли привязка к Контактам. Возможные значения:

  • Y — да
  • N — нет

COMPANY
boolean

Включена ли привязка к Компаниям. Возможные значения:

  • Y — да
  • N — нет

DEAL
boolean

Включена ли привязка к Сделкам. Возможные значения:

  • Y — да
  • N — нет

Тип uf_enum_element

Название
тип

Описание

ID
string

Идентификатор элемента списка. При передаче данного параметра будет изменен соответствующий элемент списка, иначе будет добавлен новый элемент списка.

Идентификатор можно узнать с помощью метода crm.contact.userfield.get

DEL
boolean

Флаг, необходимый для удаления элемента списка. Имеет смысл лишь при передаче ID.

Возможные значения:
Y — удалить
N — не удалять

По умолчанию N

VALUE
string

Значение элемента списка

SORT
integer

Индекс сортировки. Обязательно больше или равно 0

DEF
boolean

Является ли элемент списка значением по умолчанию. Возможные значения:

  • Y — да
  • N — нет

Для множественного поля допустимо несколько DEF = Y. Для не множественного значением по умолчанию будет считаться первый переданный элемент списка с DEF = Y

XML_ID
string

Внешний код значения. Обязательно уникальный в рамках элементов списка пользовательского поля

Примеры кода

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

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

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.contact.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.contact.userfield.update
        
BX24.callMethod(
            'crm.contact.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.contact.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>';
        
try {
            $contactUserfieldItemId = 123; // Example ID
            $userfieldFieldsToUpdate = [
                'FIELD_NAME' => 'New Field Name',
                'USER_TYPE_ID' => 'string',
                'SORT' => '100',
                'MULTIPLE' => 'N',
                'MANDATORY' => 'N',
                'SHOW_FILTER' => 'Y',
                'SHOW_IN_LIST' => 'Y',
                'EDIT_IN_LIST' => 'Y',
                'IS_SEARCHABLE' => 'Y',
                'EDIT_FORM_LABEL' => 'New Label',
                'LIST_COLUMN_LABEL' => 'Column Label',
                'LIST_FILTER_LABEL' => 'Filter Label',
                'ERROR_MESSAGE' => 'Error Message',
                'HELP_MESSAGE' => 'Help Message',
                'LIST' => '',
                'SETTINGS' => '',
            ];
        
            $result = $serviceBuilder
                ->getCRMScope()
                ->contactUserfield()
                ->update($contactUserfieldItemId, $userfieldFieldsToUpdate);
        
            if ($result->isSuccess()) {
                print($result->getCoreResponse()->getResponseData()->getResult()[0]);
            } else {
                print("Update failed.");
            }
        } catch (Throwable $e) {
            print("Error: " . $e->getMessage());
        }

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

Текущие элементы списка:

[
            {
                "ID": "115",
                "SORT": "100",
                "VALUE": "Элемент списка #1",
                "DEF": "Y",
                "XML_ID": "XML_ID_1"
            },
            {
                "ID": "116",
                "SORT": "200",
                "VALUE": "Элемент списка #2",
                "DEF": "N",
                "XML_ID": "XML_ID_2"
            },
            {
                "ID": "117",
                "SORT": "300",
                "VALUE": "Элемент списка #3",
                "DEF": "N",
                "XML_ID": "XML_ID_3"
            },
            {
                "ID": "118",
                "SORT": "400",
                "VALUE": "Элемент списка #4",
                "DEF": "N",
                "XML_ID": "XML_ID_4"
            }
        ]

Изменить его следующим образом:

  • удалить элементы списка с ID = 115 и ID = 116
  • изменить элемент списка с ID = 117:
    • VALUE: «Элемент списка #3» -> «Элемент списка #3 (изменено)»
    • SORT: 300 -> 50
  • добавить новый элемент списка «Элемент списка #5»
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"MANDATORY":"N","SHOW_FILTER":"Y","LIST":[{"ID":115,"DEL":"Y"},{"ID":116,"DEL":"Y"},{"ID":117,"VALUE":"Элемент списка #3 (изменено)","SORT":50},{"VALUE":"Элемент списка #5","XML_ID":"XML_ID_5","SORT":500}],"SETTINGS":{"DISPLAY":"DIALOG","LIST_HEIGHT":3},"SORT":1000}}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.contact.userfield.update
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"MANDATORY":"N","SHOW_FILTER":"Y","LIST":[{"ID":115,"DEL":"Y"},{"ID":116,"DEL":"Y"},{"ID":117,"VALUE":"Элемент списка #3 (изменено)","SORT":50},{"VALUE":"Элемент списка #5","XML_ID":"XML_ID_5","SORT":500}],"SETTINGS":{"DISPLAY":"DIALOG","LIST_HEIGHT":3},"SORT":1000},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.contact.userfield.update
        
BX24.callMethod(
            'crm.contact.userfield.update',
            {
                fields: {
                    MANDATORY: "N",
                    SHOW_FILTER: "Y",
                    LIST: [
                        {
                            ID: 115,
                            DEL: "Y"
                        },
                        {
                            ID: 116,
                            DEL: "Y",
                        },
                        {
                            ID: 117,
                            VALUE: "Элемент списка #3 (изменено)",
                            SORT: 50,
                        },
                        {
                            VALUE: "Элемент списка #5",
                            XML_ID: "XML_ID_5",
                            SORT: 500,
                        },
                    ],
                    SETTINGS: {
                        DISPLAY: "DIALOG",
                        LIST_HEIGHT: 3,
                    },
                    SORT: 1000,
                },
            },
            (result) => {
                result.error()
                    ? console.error(result.error())
                    : console.info(result.data())
                ;
            },
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'crm.contact.userfield.update',
            [
                'fields' => [
                    'MANDATORY' => "N",
                    'SHOW_FILTER' => "Y",
                    'LIST' => [
                        [
                            'ID' => 115,
                            'DEL' => "Y"
                        ],
                        [
                            'ID' => 116,
                            'DEL' => "Y",
                        ],
                        [
                            'ID' => 117,
                            'VALUE' => "Элемент списка #3 (изменено)",
                            'SORT' => 50,
                        ],
                        [
                            'VALUE' => "Элемент списка #5",
                            'XML_ID' => "XML_ID_5",
                            'SORT' => 500,
                        ],
                    ],
                    'SETTINGS' => [
                        'DISPLAY' => "DIALOG",
                        'LIST_HEIGHT' => 3,
                    ],
                    'SORT' => 1000,
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

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

HTTP-статус: 200

{
            "result": true,
            "time": {
                "start": 1724419843.518672,
                "finish": 1724419844.120328,
                "duration": 0.6016559600830078,
                "processing": 0.1907808780670166,
                "date_start": "2024-08-23T15:30:43+02:00",
                "date_finish": "2024-08-23T15:30:44+02:00",
                "operating": 0
            }
        }

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

Название
тип

Описание

result
boolean

Корневой элемент ответа, содержит true в случае успеха

time
time

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

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

HTTP-статус: 400

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

Название
тип

Описание

error
string

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

error_description
error_description

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

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

Код

Описание

Значение

-

Parameter 'fields' must be array

Переданный fields не является объектом

-

ID is not defined or invalid

Переданный id меньше нуля или не передан вовсе

-

Access denied

Возникает в случаях, когда:

  • у пользователя нет административных прав
  • пользователь пытается удалить пользовательское поле, не привязанное к контактам

ERROR_NOT_FOUND

The entity with ID 'id' is not found

Пользовательского поля с переданным id не существует

ERROR_CORE

Элемент списка со значением XML_ID=XML_ID уже существует

Переданный XML_ID у элемента списка обязан быть уникальным в рамках элементов списка отдельно взятого пользовательского поля

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

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус

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

Описание

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

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

405

ERROR_BATCH_METHOD_NOT_ALLOWED
Method is not allowed for batch usage

Текущий метод не разрешен для вызова с помощью batch

400

ERROR_BATCH_LENGTH_EXCEEDED
Max batch length exceeded

Превышена максимальная длина параметров, переданных в метод batch

401

NO_AUTH_FOUND
Wrong authorization data

Неверный access-токен или код вебхука

400

INVALID_REQUEST
Https required

Для вызовов методов требуется использовать протокол HTTPS

503

OVERLOAD_LIMIT
REST API is blocked due to overload

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

403

ACCESS_DENIED
REST API is available only on commercial plans

REST API доступен только на коммерческих планах

403

INVALID_CREDENTIALS
Invalid request credentials

У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав

404

ERROR_MANIFEST_IS_NOT_AVAILABLE
Manifest is not available

Манифест недоступен

403

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

Запрос требует более высоких привилегий, чем предоставляет токен вебхука

401

expired_token
The access token provided has expired

Предоставленный access-токен доступа истек

403

user_access_error
The user does not have access to the application

Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям

500

PORTAL_DELETED
Portal was deleted

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

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

Предыдущая
Создать пользовательское поле для контактов
Следующая
Получить пользовательское поле контактов по Id