crm.contact.userfield.add
Создать пользовательское поле для контактов
Описание
Метод crm.contact.userfield.add создает новое пользовательское поле для контактов.
Параметры
fields
object
обязательный
Объект формата:
{
field_1: value_1,
field_2: value_2,
...,
field_n: value_n,
}где:
- field_n — название поля
- value_n — значение поля
Список доступных полей описан ниже.
Некорректное поле в fields будет проигнорировано
Параметр fields
USER_TYPE_ID
string
обязательный
Тип данных пользовательского поля. Возможные значения:
- string — строка
- integer — целое число
- double — число
- boolean — да/нет
- datetime — дата/время
- date — дата
- money — деньги
- url — ссылка
- address — адрес
- enumeration — список
- file — файл
- employee — привязка к сотруднику
- crm_status — привязка к справочнику CRM
- iblock_section — привязка к разделам инф. блоков
- iblock_element — привязка к элементам инф. блоков
- crm — привязка к элементам CRM
- пользовательские типы полей
FIELD_NAME
string
обязательный
Код поля. Уникальный в пределах контактов.
К коду всегда добавляется префикс UF_CRM_, полное имя поля система собирает сама:
- MANAGER_NOTE превращается в UF_CRM_MANAGER_NOTE
- UF_MANAGER_NOTE превращается в UF_CRM_MANAGER_NOTE — префикс UF_ заменяется на UF_CRM_
- UF_CRM_MANAGER_NOTE остается без изменений
Ограничение длины — до 50 символов вместе с префиксом, то есть до 43 символов на код. Если передать более длинное значение, метод вернет ошибку ERROR_CORE.
Допустимые символы: A-Z, 0-9 и _. Строчные буквы приводятся к заглавным, остальные символы вызывают ошибку ERROR_CORE
LABEL
string
необязательный
Название пользовательского поля по умолчанию.
Переданное значение будет выставлено в следующие поля: LIST_FILTER_LABEL, LIST_COLUMN_LABEL, EDIT_FORM_LABEL, ERROR_MESSAGE, HELP_MESSAGE, если в них не передано значение
XML_ID
string
необязательный
Внешний код
LIST_FILTER_LABEL
string
необязательный
Подпись фильтра в списке.
При передаче строки она будет проставлена для всех идентификаторов языка.
При передаче значения типа lang_map для всех непереданных языков будет проставлено значение из LABEL.
По умолчанию значение, переданное в LABEL, проставляется для всех идентификаторов языка
LIST_COLUMN_LABEL
string
необязательный
Заголовок в списке.
При передаче строки она будет проставлена для всех идентификаторов языка.
При передаче значения типа lang_map для всех непереданных языков будет проставлено значение из LABEL.
По умолчанию значение, переданное в LABEL, проставляется для всех идентификаторов языка
EDIT_FORM_LABEL
string
необязательный
Подпись в форме редактирования.
При передаче строки она будет проставлена для всех идентификаторов языка.
При передаче значения типа lang_map для всех непереданных языков будет проставлено значение из LABEL.
По умолчанию значение, переданное в LABEL, проставляется для всех идентификаторов языка
ERROR_MESSAGE
string
необязательный
Сообщение об ошибке.
При передаче строки она будет проставлена для всех идентификаторов языка.
При передаче значения типа lang_map для всех непереданных языков будет проставлено значение из LABEL.
По умолчанию значение, переданное в LABEL, проставляется для всех идентификаторов языка
HELP_MESSAGE
string
необязательный
Помощь.
При передаче строки она будет проставлена для всех идентификаторов языка.
При передаче значения типа lang_map для всех непереданных языков будет проставлено значение из LABEL.
По умолчанию значение, переданное в LABEL, проставляется для всех идентификаторов языка
MULTIPLE
boolean
необязательный
Является ли поле множественным. Возможные значения:
- Y — да
- N — нет
Поля типа boolean не могут быть множественными.
По умолчанию N
MANDATORY
boolean
необязательный
Является ли поле обязательным. Возможные значения:
- Y — да
- N — нет
По умолчанию N
SHOW_FILTER
boolean
необязательный
Показывать ли поле в фильтре. Возможные значения:
- Y — да
- N — нет
По умолчанию N
SETTINGS
object
необязательный
Дополнительные параметры поля. Для каждого типа поля (USER_TYPE_ID) существует свой пул доступных настроек, они описаны ниже
LIST
uf_enum_element[]
необязательный
Список возможных значений для пользовательского поля типа enumeration. Для пользовательских полей другого типа данный параметр не несет смысла.
По умолчанию []
SORT
integer
необязательный
Индекс сортировки. Обязательно больше нуля.
По умолчанию 100
SHOW_IN_LIST
boolean
необязательный
Показывать ли пользовательское поле в списке.
Данный параметр ни на что не влияет в рамках crm.
Возможные значения:
- Y — да
- N — нет
По умолчанию N
EDIT_IN_LIST
boolean
необязательный
Разрешать ли редактирование пользователем. Возможные значения:
- Y — да
- N — нет
По умолчанию Y
IS_SEARCHABLE
boolean
необязательный
Участвуют ли значения поля в поиске.
Данный параметр ни на что не влияет в рамках crm.
Возможные значения:
- Y — да
- N — нет
По умолчанию N
Тип uf_enum_element
VALUE
string
необязательный
Значение элемента списка.
Элементы списка с пустым или отсутствующим VALUE будут проигнорированы
SORT
integer
необязательный
Индекс сортировки. Обязательно больше или равно 0.
По умолчанию 0
DEF
boolean
необязательный
Является ли элемент списка значением по умолчанию. Возможные значения:
- Y — да
- N — нет
Для множественного поля допустимо несколько DEF = Y. Для не множественного значением по умолчанию будет считаться первый переданный элемент списка с DEF = Y.
По умолчанию N
XML_ID
string
необязательный
Внешний код значения. Обязательно уникальный в рамках элементов списка пользовательского поля
Примеры запроса
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields":{"LABEL":"Поле \'Привет, мир!\'","USER_TYPE_ID":"string","FIELD_NAME":"HELLO_WORLD","MULTIPLE":"Y","MANDATORY":"Y","SHOW_FILTER":"Y","SETTINGS":{"DEFAULT_VALUE":"Привет, мир! Значение по умолчанию","ROWS":3},"SORT":1000,"EDIT_IN_LIST":"Y","LIST_FILTER_LABEL":"Привет, мир! Фильтр","LIST_COLUMN_LABEL":{"en":"Hello, World! Column","ru":"Привет, мир! Колонка","de":"Hallo, Welt! Spalte"},"EDIT_FORM_LABEL":{"en":"Hello, World! Edit","ru":"Привет, мир! Редактировать","de":"Hallo, Welt! Bearbeiten"},"ERROR_MESSAGE":{"en":"Hello, World! Error","ru":"Привет, мир! Ошибка","de":"Hallo, Welt! Fehler"},"HELP_MESSAGE":{"en":"Hello, World! Help","ru":"Привет, мир! Помощь","de":"Hallo, Welt! Hilfe"}}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.contact.userfield.addcurl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields":{"LABEL":"Поле \'Привет, мир!\'","USER_TYPE_ID":"string","FIELD_NAME":"HELLO_WORLD","MULTIPLE":"Y","MANDATORY":"Y","SHOW_FILTER":"Y","SETTINGS":{"DEFAULT_VALUE":"Привет, мир! Значение по умолчанию","ROWS":3},"SORT":1000,"EDIT_IN_LIST":"Y","LIST_FILTER_LABEL":"Привет, мир! Фильтр","LIST_COLUMN_LABEL":{"en":"Hello, World! Column","ru":"Привет, мир! Колонка","de":"Hallo, Welt! Spalte"},"EDIT_FORM_LABEL":{"en":"Hello, World! Edit","ru":"Привет, мир! Редактировать","de":"Hallo, Welt! Bearbeiten"},"ERROR_MESSAGE":{"en":"Hello, World! Error","ru":"Привет, мир! Ошибка","de":"Hallo, Welt! Fehler"},"HELP_MESSAGE":{"en":"Hello, World! Help","ru":"Привет, мир! Помощь","de":"Hallo, Welt! Hilfe"}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.contact.userfield.addBX24.callMethod(
'crm.contact.userfield.add',
{
fields: {
LABEL: "Поле \'Привет, мир!\'",
USER_TYPE_ID: "string",
FIELD_NAME: "HELLO_WORLD",
MULTIPLE: "Y",
MANDATORY: "Y",
SHOW_FILTER: "Y",
SETTINGS: {
DEFAULT_VALUE: "Привет, мир! Значение по умолчанию",
ROWS: 3,
},
SORT: 1000,
EDIT_IN_LIST: "Y",
LIST_FILTER_LABEL: "Привет, мир! Фильтр",
LIST_COLUMN_LABEL: {
"en": "Hello, World! Column",
"ru": "Привет, мир! Колонка",
"de": "Hallo, Welt! Spalte"
},
EDIT_FORM_LABEL: {
"en": "Hello, World! Edit",
"ru": "Привет, мир! Редактировать",
"de": "Hallo, Welt! Bearbeiten"
},
ERROR_MESSAGE: {
"en": "Hello, World! Error",
"ru": "Привет, мир! Ошибка",
"de": "Hallo, Welt! Fehler"
},
HELP_MESSAGE: {
"en": "Hello, World! Help",
"ru": "Привет, мир! Помощь",
"de": "Hallo, Welt! Hilfe"
},
},
},
(result) => {
result.error()
? console.error(result.error())
: console.info(result.data())
;
},
);try {
$userfieldItemFields = [
'FIELD_NAME' => 'UF_CRM_example',
'USER_TYPE_ID' => 'string',
'XML_ID' => 'xml_example',
'SORT' => '100',
'MULTIPLE' => 'N',
'MANDATORY' => 'Y',
'SHOW_FILTER' => 'Y',
'SHOW_IN_LIST' => 'Y',
'EDIT_IN_LIST' => 'Y',
'IS_SEARCHABLE' => 'Y',
'EDIT_FORM_LABEL' => 'Example Field',
'LIST_COLUMN_LABEL' => 'Example Column',
'LIST_FILTER_LABEL' => 'Example Filter',
'ERROR_MESSAGE' => 'Error occurred',
'HELP_MESSAGE' => 'Help message',
'LIST' => 'list_value',
'SETTINGS' => 'settings_value',
];
$result = $serviceBuilder
->getCRMScope()
->contactUserfield()
->add($userfieldItemFields);
print($result->getId());
} catch (Throwable $e) {
print('Error: ' . $e->getMessage());
}require_once('crest.php');
$result = CRest::call(
'crm.contact.userfield.add',
[
'fields' => [
'LABEL' => "Поле 'Привет, мир!'",
'USER_TYPE_ID' => "string",
'FIELD_NAME' => "HELLO_WORLD",
'MULTIPLE' => "Y",
'MANDATORY' => "Y",
'SHOW_FILTER' => "Y",
'SETTINGS' => [
'DEFAULT_VALUE' => "Привет, мир! Значение по умолчанию",
'ROWS' => 3,
],
'SORT' => 1000,
'EDIT_IN_LIST' => "Y",
'LIST_FILTER_LABEL' => "Привет, мир! Фильтр",
'LIST_COLUMN_LABEL' => [
'en' => "Hello, World! Column",
'ru' => "Привет, мир! Колонка",
'de' => "Hallo, Welt! Spalte"
],
'EDIT_FORM_LABEL' => [
'en' => "Hello, World! Edit",
'ru' => "Привет, мир! Редактировать",
'de' => "Hallo, Welt! Bearbeiten"
],
'ERROR_MESSAGE' => [
'en' => "Hello, World! Error",
'ru' => "Привет, мир! Ошибка",
'de' => "Hallo, Welt! Fehler"
],
'HELP_MESSAGE' => [
'en' => "Hello, World! Help",
'ru' => "Привет, мир! Помощь",
'de' => "Hallo, Welt! Hilfe"
],
]
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';from b24pysdk.errors import BitrixAPIError, BitrixSDKException
try:
bitrix_response = client.crm.contact.userfield.add(
fields={
"LABEL": "Поле 'Привет, мир!'",
"USER_TYPE_ID": "string",
"FIELD_NAME": "HELLO_WORLD",
"MULTIPLE": "Y",
"MANDATORY": "Y",
"SHOW_FILTER": "Y",
"SETTINGS": {
"DEFAULT_VALUE": "Привет, мир! Значение по умолчанию",
"ROWS": 3,
"DISPLAY": "UI",
"LIST_HEIGHT": 2,
},
"SORT": 1000,
"EDIT_IN_LIST": "Y",
"LIST_FILTER_LABEL": "Привет, мир! Фильтр",
"LIST_COLUMN_LABEL": {
"en": "Hello, World! Column",
"ru": "Привет, мир! Колонка",
"de": "Hallo, Welt! Spalte",
},
"EDIT_FORM_LABEL": {
"en": "Hello, World! Edit",
"ru": "Привет, мир! Редактировать",
"de": "Hallo, Welt! Bearbeiten",
},
"ERROR_MESSAGE": {
"en": "Hello, World! Error",
"ru": "Привет, мир! Ошибка",
"de": "Hallo, Welt! Fehler",
},
"HELP_MESSAGE": {
"en": "Hello, World! Help",
"ru": "Привет, мир! Помощь",
"de": "Hallo, Welt! Hilfe",
},
"LIST": [
{
"VALUE": "Элемент списка #1",
"DEF": "Y",
"XML_ID": "XML_ID_1",
"SORT": 100,
},
{
"VALUE": "Элемент списка #2",
"XML_ID": "XML_ID_2",
"SORT": 200,
},
{
"VALUE": "Элемент списка #3",
"XML_ID": "XML_ID_3",
"SORT": 300,
},
{
"VALUE": "Элемент списка #4",
"XML_ID": "XML_ID_4",
"SORT": 400,
},
],
},
).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}")Ответ
HTTP-статус: 200
{
"result": 399,
"time": {
"start": 1724239307.903115,
"finish": 1724239308.567422,
"duration": 0.6643068790435791,
"processing": 0.20090818405151367,
"date_start": "2024-08-21T13:21:47+02:00",
"date_finish": "2024-08-21T13:21:48+02:00",
"operating": 0
}
}Возвращаемые данные
result
integer
Корневой элемент ответа, содержит идентификатор созданного пользовательского поля
time
time
Информация о времени выполнения запроса
Обработка ошибок
HTTP-статус: 400
{
"error": "",
"error_description": "The 'USER_TYPE_ID' field is not found."
}| Код | Описание | Значение |
|---|---|---|
Access denied |
У пользователя нет административных прав | |
The 'FIELD_NAME' field is not found |
Либо передан пустой FIELD_NAME, либо он не передан вовсе |
|
Имя поля слишком длинное (больше 50-ти символов) |
Полное имя поля вместе с префиксом UF_CRM_ содержит более 50 символов, то есть в FIELD_NAME передано более 43 символов |
|
Имя поля содержит недопустимые символы. Допустимыми являются: A-Z, 0-9 и _ |
Переданный FIELD_NAME содержит символы, кроме A-Z, 0-9 и _ |
|
The 'USER_TYPE_ID' field is not found |
Либо передан пустой USER_TYPE_ID, либо он не передан вовсе |
|
Указан неверный пользовательский тип |
Переданный USER_TYPE_ID не существует |
|
Элемент списка со значением XML_ID=XML_ID уже существует |
Переданные в элементы списка XML_ID не уникальны |
