Создать пользовательское поле для контактов crm.contact.userfield.add
Scope:
crmКто может выполнять метод: администратор
Метод crm.contact.userfield.add создает новое пользовательское поле для контактов.
Параметры метода
Обязательные параметры отмечены *
|
Название |
Описание |
|
fields* |
Объект формата:
где:
Список доступных полей описан ниже. Некорректное поле в |
Параметр fields
Обязательные параметры отмечены *
|
Название |
Описание |
|
USER_TYPE_ID* |
Тип данных пользовательского поля. Возможные значения:
|
|
FIELD_NAME* |
Код поля. Уникальное. Системное ограничение на код поля составляет 20 знаков. К названию пользовательского поля всегда добавляется префикс Допустимые символы: |
|
LABEL |
Название пользовательского поля по умолчанию. Переданное значение будет выставлено в следующие поля: |
|
XML_ID |
Внешний код |
|
Подпись фильтра в списке. При передаче строки она будет проставлена для всех идентификаторов языка. При передаче значения типа По умолчанию значение, переданное в |
|
|
Заголовок в списке. При передаче строки она будет проставлена для всех идентификаторов языка. При передаче значения типа По умолчанию значение, переданное в |
|
|
Подпись в форме редактирования. При передаче строки она будет проставлена для всех идентификаторов языка. При передаче значения типа По умолчанию значение, переданное в |
|
|
Сообщение об ошибке. При передаче строки она будет проставлена для всех идентификаторов языка. При передаче значения типа По умолчанию значение, переданное в |
|
|
Помощь. При передаче строки она будет проставлена для всех идентификаторов языка. При передаче значения типа По умолчанию значение, переданное в |
|
|
MULTIPLE |
Является ли поле множественным. Возможные значения:
Поля типа По умолчанию |
|
MANDATORY |
Является ли поле обязательным. Возможные значения:
По умолчанию |
|
SHOW_FILTER |
Показывать ли поле в фильтре. Возможные значения:
По умолчанию |
|
SETTINGS |
Дополнительные параметры поля. Для каждого типа поля ( |
|
LIST |
Список возможных значений для пользовательского поля типа По умолчанию |
|
SORT |
Индекс сортировки. Обязательно больше нуля. По умолчанию |
|
SHOW_IN_LIST |
Показывать ли пользовательское поле в списке. Данный параметр ни на что не влияет в рамках Возможные значения:
По умолчанию |
|
EDIT_IN_LIST |
Разрешать ли редактирование пользователем. Возможные значения:
По умолчанию |
|
IS_SEARCHABLE |
Участвуют ли значения поля в поиске. Данный параметр ни на что не влияет в рамках Возможные значения:
По умолчанию |
Параметр SETTINGS
У каждого типа пользовательских полей существует свой набор дополнительных настроек. Данный метод поддерживает лишь те, что описаны ниже.
|
Название |
Описание |
|
DEFAULT_VALUE |
Значение по умолчанию. По умолчанию |
|
ROWS |
Количество строк в поле ввода. Обязательно больше 0. По умолчанию |
|
Название |
Описание |
|
DEFAULT_VALUE |
Значение по умолчанию |
|
Название |
Описание |
|
DEFAULT_VALUE |
Значение по умолчанию |
|
PRECISION |
Точность числа. Обязательно больше или равно 0. По умолчанию |
|
Название |
Описание |
|
DEFAULT_VALUE |
Значение по умолчанию, где Возможные значения:
По умолчанию |
|
DISPLAY |
Внешний вид. Возможные значения:
По умолчанию |
|
Название |
Описание |
|
DEFAULT_VALUE |
Значение по умолчанию. Объект формата:
где:
Значение по умолчанию:
|
|
Название |
Описание |
|
DISPLAY |
Внешний вид. Возможные значения:
По умолчанию |
|
LIST_HEIGHT |
Высота списка. Обязательно больше 0. Доступен только при По умолчанию |
|
Название |
Описание |
|
IBLOCK_TYPE_ID |
Идентификатор типа инфоблока. По умолчанию |
|
IBLOCK_ID |
Идентификатор инфоблока. По умолчанию |
|
DEFAULT_VALUE |
Значение по умолчанию. По умолчанию |
|
DISPLAY |
Внешний вид. Возможные значения:
По умолчанию |
|
LIST_HEIGHT |
Высота списка. Обязательно больше 0. По умолчанию |
|
ACTIVE_FILTER |
Показывать ли элементы с включенным флагом активности. Возможные значения:
По умолчанию |
|
Название |
Описание |
|
ENTITY_TYPE |
Идентификатор типа справочника. Используйте По умолчанию |
Если не передать ни одну из следующих опций, то по умолчанию будет включена привязка к лидам (LEAD = Y).
|
Название |
Описание |
|
LEAD |
Включена ли привязка к Лидам. Возможные значения:
По умолчанию |
|
CONTACT |
Включена ли привязка к Контактам. Возможные значения:
По умолчанию |
|
COMPANY |
Включена ли привязка к Компаниям. Возможные значения:
По умолчанию |
|
DEAL |
Включена ли привязка к Сделкам. Возможные значения:
По умолчанию |
Тип uf_enum_element
|
Название |
Описание |
|
VALUE |
Значение элемента списка. Элементы списка с пустым или отсутствующим |
|
SORT |
Индекс сортировки. Обязательно больше или равно 0. По умолчанию |
|
DEF |
Является ли элемент списка значением по умолчанию. Возможные значения:
Для множественного поля допустимо несколько По умолчанию |
|
XML_ID |
Внешний код значения. Обязательно уникальный в рамках элементов списка пользовательского поля |
Примеры кода
Как использовать примеры в документации
Пример создания пользовательского поля типа Строка
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.add
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"}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.contact.userfield.add
BX24.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())
;
},
);
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>';
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());
}
Пример создания пользовательского поля типа Список
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields":{"LABEL":"Пользовательское поле (список)","USER_TYPE_ID":"enumeration","FIELD_NAME":"ENUMERATION_EXAMPLE","MULTIPLE":"N","MANDATORY":"N","SHOW_FILTER":"Y","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}],"SETTINGS":{"DISPLAY":"UI","LIST_HEIGHT":2},"SORT":2000}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.contact.userfield.add
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"fields":{"LABEL":"Пользовательское поле (список)","USER_TYPE_ID":"enumeration","FIELD_NAME":"ENUMERATION_EXAMPLE","MULTIPLE":"N","MANDATORY":"N","SHOW_FILTER":"Y","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}],"SETTINGS":{"DISPLAY":"UI","LIST_HEIGHT":2},"SORT":2000},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.contact.userfield.add
BX24.callMethod(
'crm.contact.userfield.add',
{
fields: {
LABEL: "Пользовательское поле (список)",
USER_TYPE_ID: "enumeration",
FIELD_NAME: "ENUMERATION_EXAMPLE",
MULTIPLE: "N",
MANDATORY: "N",
SHOW_FILTER: "Y",
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,
},
],
SETTINGS: {
DISPLAY: "UI",
LIST_HEIGHT: 2,
},
SORT: 2000,
},
},
(result) => {
result.error()
? console.error(result.error())
: console.info(result.data())
;
},
);
require_once('crest.php');
$result = CRest::call(
'crm.contact.userfield.add',
[
'fields' => [
'LABEL' => "Пользовательское поле (список)",
'USER_TYPE_ID' => "enumeration",
'FIELD_NAME' => "ENUMERATION_EXAMPLE",
'MULTIPLE' => "N",
'MANDATORY' => "N",
'SHOW_FILTER' => "Y",
'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,
],
],
'SETTINGS' => [
'DISPLAY' => "UI",
'LIST_HEIGHT' => 2,
],
'SORT' => 2000,
]
]
);
echo '<PRE>';
print_r($result);
echo '</PRE>';
Обработка ответа
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 |
Корневой элемент ответа, содержит идентификатор созданного пользовательского поля |
|
time |
Информация о времени выполнения запроса |
Обработка ошибок
HTTP-статус: 400
Данный метод может отдавать ошибки не сразу, а собирая несколько и соединяя их между собой строкой: \n.
{
"error": "",
"error_description": "The 'USER_TYPE_ID' field is not found."
}
|
Название |
Описание |
|
error |
Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания |
|
error_description |
Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде |
Возможные коды ошибок
|
Описание |
Значение |
|
|
У пользователя нет административных прав |
|
|
Либо передан пустой |
|
Имя поля слишком длинное (больше 50-ти символов) |
Переданный |
|
Имя поля содержит недопустимые символы. Допустимыми являются: |
Переданный |
|
|
Либо передан пустой |
|
Указан неверный пользовательский тип |
Переданный |
|
Элемент списка со значением XML_ID= |
Переданные в элементы списка |
Статусы и коды системных ошибок
HTTP-статус: 20x, 40x, 50x
Описанные ниже ошибки могут возникнуть при вызове любого метода
|
Статус |
Код |
Описание |
|
|
|
Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24 |
|
|
|
Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24 |
|
|
|
Превышен лимит на интенсивность запросов |
|
|
|
Текущий метод не разрешен для вызова с помощью batch |
|
|
|
Превышена максимальная длина параметров, переданных в метод batch |
|
|
|
Неверный access-токен или код вебхука |
|
|
|
Для вызовов методов требуется использовать протокол HTTPS |
|
|
|
REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24 |
|
|
|
REST API доступен только на коммерческих планах |
|
|
|
У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав |
|
|
|
Манифест недоступен |
|
|
|
Запрос требует более высоких привилегий, чем предоставляет токен вебхука |
|
|
|
Предоставленный access-токен доступа истек |
|
|
|
Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям |
|
|
|
Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта |
Продолжите изучение
- Изменить существующее пользовательское поле контактов crm.contact.userfield.update
- Получить пользовательское поле контактов по Id crm.contact.userfield.get
- Получить список пользовательских полей контактов crm.contact.userfield.list
- Удалить пользовательское поле контактов crm.contact.userfield.delete