crm.contact.userfield.update
Изменить существующее пользовательское поле контактов
Описание
Метод 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
необязательный
Подпись фильтра в списке.
При передаче строки она устанавливается для каждого языка.
Для языков, у которых явно не указано значение, будет записано ''.
Поле полностью перезаписывает предыдущее значение
LIST_COLUMN_LABEL
string
необязательный
Заголовок в списке.
При передаче строки она устанавливается для каждого языка.
Для языков, у которых явно не указано значение, будет записано ''.
Поле полностью перезаписывает предыдущее значение
EDIT_FORM_LABEL
string
необязательный
Подпись в форме редактирования.
При передаче строки она устанавливается для каждого языка.
Для языков, у которых явно не указано значение, будет записано ''.
Поле полностью перезаписывает предыдущее значение
ERROR_MESSAGE
string
необязательный
Сообщение об ошибке.
При передаче строки она устанавливается для каждого языка.
Для языков, у которых явно не указано значение, будет записано ''.
Поле полностью перезаписывает предыдущее значение
HELP_MESSAGE
string
необязательный
Помощь.
При передаче строки она устанавливается для каждого языка.
Для языков, у которых явно не указано значение, будет записано ''.
Поле полностью перезаписывает предыдущее значение
Тип 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.updatecurl -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.updateBX24.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())
;
},
);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());
}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>';from b24pysdk.errors import BitrixAPIError, BitrixSDKException
try:
bitrix_response = client.crm.contact.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.contact.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.contact.userfield.update: %w", err)
}
// Ответ приходит как json.RawMessage — разберите его
// в структуру под форму ответа, показанную ниже на этой странице.
fmt.Printf("%s\n", res.Result)Ответ
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."
}| Код | Описание | Значение |
|---|---|---|
| — | 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 у элемента списка обязан быть уникальным в рамках элементов списка отдельно взятого пользовательского поля |
