userfieldconfig.add
Добавить пользовательское поле
Описание
Метод userfieldconfig.add добавляет новое пользовательское поле.
Параметры
moduleId
string
обязательный
Идентификатор модуля, в котором создается поле
field
object
обязательный
Объект с настройками пользовательского поля (подробное описание)
Параметр field
entityId
string
обязательный
Идентификатор объекта, для которого создается поле. Формат зависит от модуля, например CRM_7 для смарт-процесса
fieldName
string
обязательный
Код поля в формате UF_{ИДЕНТИФИКАТОР_ОБЪЕКТА}_{POSTFIX}. Код должен быть уникальным в рамках объекта. Допустимы символы A-Z, 0-9, _. Максимальная длина кода 50 символов
userTypeId
string
обязательный
Идентификатор типа поля. Список доступных типов возвращает метод userfieldconfig.getTypes
xmlId
string
необязательный
Внешний идентификатор поля
sort
integer
необязательный
Индекс сортировки. По умолчанию 100
multiple
boolean
необязательный
Является ли поле множественным. Возможные значения: Y или N. По умолчанию N
mandatory
boolean
необязательный
Является ли поле обязательным. Возможные значения: Y или N. По умолчанию N
showFilter
boolean
необязательный
Показывать ли поле в фильтре. Возможные значения: Y или N. По умолчанию N
editInList
boolean
необязательный
Разрешать ли редактирование значения в списке. Возможные значения: Y или N
isSearchable
boolean
необязательный
Участвуют ли значения поля в поиске. Возможные значения: Y или N
settings
object
необязательный
Дополнительные настройки поля. Набор ключей зависит от userTypeId (подробное описание)
editFormLabel
string
необязательный
Подпись в форме редактирования. При передаче строки используется как общее значение, при передаче lang_map можно задать подпись по языкам
helpMessage
string
необязательный
Текст подсказки. При передаче строки используется как общее значение, при передаче lang_map можно задать подсказку по языкам
enum
uf_enum_element[]
необязательный
Варианты значений для поля типа enumeration
Тип uf_enum_element
value
string
обязательный
Значение варианта списка
def
boolean
необязательный
Флаг значения по умолчанию (Y/N)
sort
integer
необязательный
Индекс сортировки варианта
xmlId
string
необязательный
Внешний идентификатор варианта
Примеры запроса
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"moduleId": "crm",
"field": {
"entityId": "CRM_7",
"fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
"userTypeId": "enumeration",
"multiple": "Y",
"editFormLabel": {
"ru": "Список характеристик",
"en": "List of characteristics"
},
"enum": [
{ "value": "Характеристика 1", "def": "N", "sort": 100 },
{ "value": "Характеристика 2", "def": "Y", "sort": 200 }
]
}
}' \
"https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/userfieldconfig.add"
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"moduleId": "crm",
"field": {
"entityId": "CRM_7",
"fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
"userTypeId": "enumeration",
"multiple": "Y",
"editFormLabel": {
"ru": "Список характеристик",
"en": "List of characteristics"
},
"enum": [
{ "value": "Характеристика 1", "def": "N", "sort": 100 },
{ "value": "Характеристика 2", "def": "Y", "sort": 200 }
]
},
"auth": "**put_access_token_here**"
}' \
"https://**put_your_bitrix24_address**/rest/userfieldconfig.add"
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'
declare const $b24: B24Frame
// Shape of the payload returned in result (match the "response handling" section of the page)
type UserfieldconfigAddResult = {
field: {
id: string
entityId: string
fieldName: string
userTypeId: string
xmlId: string | null
sort: string
multiple: string
mandatory: string
showFilter: string
showInList: string
editInList: string
isSearchable: string
settings: Record<string, unknown>
languageId: Record<string, string>
editFormLabel: Record<string, string | null>
listColumnLabel: Record<string, string | null>
listFilterLabel: Record<string, string | null>
errorMessage: Record<string, string | null>
helpMessage: Record<string, string | null>
enum?: Array<{
id: string
userFieldId: string
value: string
def: string
sort: string
xmlId: string
}>
}
}
try {
const response = await $b24.actions.v2.call.make<UserfieldconfigAddResult>({
method: 'userfieldconfig.add',
params: {
moduleId: 'crm',
field: {
entityId: 'CRM_7',
fieldName: 'UF_CRM_7_NEW_REST_LIST_2026',
userTypeId: 'enumeration',
multiple: 'Y',
editFormLabel: {
ru: 'Список характеристик',
en: 'List of characteristics',
},
enum: [
{ value: 'Characteristic 1', def: 'N', sort: 100 },
{ value: 'Characteristic 2', def: 'Y', sort: 200 },
],
},
},
requestId: Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
} else {
const result = response.getData()!.result
console.info('Created field:', result.field.id, result.field.fieldName)
}
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
async function addUserfield() {
try {
// Initialize the SDK inside a Bitrix24 frame
const $b24 = await B24Js.initializeB24Frame()
const response = await $b24.actions.v2.call.make({
method: 'userfieldconfig.add',
params: {
moduleId: 'crm',
field: {
entityId: 'CRM_7',
fieldName: 'UF_CRM_7_NEW_REST_LIST_2026',
userTypeId: 'enumeration',
multiple: 'Y',
editFormLabel: {
ru: 'Список характеристик',
en: 'List of characteristics',
},
enum: [
{ value: 'Characteristic 1', def: 'N', sort: 100 },
{ value: 'Characteristic 2', def: 'Y', sort: 200 },
],
},
},
requestId: B24Js.Text.getUuidRfc4122()
})
// The payload is available only on a successful response
if (!response.isSuccess) {
console.error(response.getErrorMessages().join('; '))
return
}
const result = response.getData().result
console.info('Created field:', result.field.id, result.field.fieldName)
} catch (error) {
// Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
console.error(error)
}
}
document.addEventListener('DOMContentLoaded', addUserfield)
</script>
from b24pysdk.errors import BitrixAPIError, BitrixSDKException
try:
bitrix_response = client.userfieldconfig.add(
module_id="crm",
field={
"entityId": "CRM_7",
"fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
"userTypeId": "enumeration",
"multiple": "Y",
"editFormLabel": {
"ru": "Список характеристик",
"en": "List of characteristics",
},
"listColumnLabel": {
"ru": "Характеристики",
"en": "Characteristics",
},
"listFilterLabel": {
"ru": "Характеристики",
"en": "Characteristics",
},
"settings": {
"DISPLAY": "LIST",
"LIST_HEIGHT": 1,
},
"enum": [
{
"value": "Характеристика 1",
"def": "N",
"sort": 100,
},
{
"value": "Характеристика 2",
"def": "Y",
"sort": 200,
},
],
},
).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}")
$payload = [
'auth' => '**put_access_token_here**',
'moduleId' => 'crm',
'field' => [
'entityId' => 'CRM_7',
'fieldName' => 'UF_CRM_7_NEW_REST_LIST_2026',
'userTypeId' => 'enumeration',
'multiple' => 'Y',
'editFormLabel' => [
'ru' => 'Список характеристик',
'en' => 'List of characteristics',
],
'enum' => [
['value' => 'Характеристика 1', 'def' => 'N', 'sort' => 100],
['value' => 'Характеристика 2', 'def' => 'Y', 'sort' => 200],
],
],
];
$curl = curl_init('https://**put_your_bitrix24_address**/rest/userfieldconfig.add.json');
curl_setopt_array($curl, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$result = curl_exec($curl);
curl_close($curl);
print_r($result);
BX24.callMethod(
"userfieldconfig.add",
{
moduleId: "crm",
field: {
entityId: "CRM_7",
fieldName: "UF_CRM_7_NEW_REST_LIST_2026",
userTypeId: "enumeration",
multiple: "Y",
editFormLabel: {
ru: "Список характеристик",
en: "List of characteristics",
},
enum: [
{ value: "Характеристика 1", def: "N", sort: 100 },
{ value: "Характеристика 2", def: "Y", sort: 200 },
],
},
},
(result) => {
if (result.error()) {
console.error(result.error());
} else {
console.info(result.data());
}
}
);
require_once('crest.php');
$result = CRest::call(
'userfieldconfig.add',
[
'moduleId' => 'crm',
'field' => [
'entityId' => 'CRM_7',
'fieldName' => 'UF_CRM_7_NEW_REST_LIST_2026',
'userTypeId' => 'enumeration',
'multiple' => 'Y',
'editFormLabel' => [
'ru' => 'Список характеристик',
'en' => 'List of characteristics',
],
'enum' => [
['value' => 'Характеристика 1', 'def' => 'N', 'sort' => 100],
['value' => 'Характеристика 2', 'def' => 'Y', 'sort' => 200],
],
],
]
);
echo '<pre>';
print_r($result);
echo '</pre>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "userfieldconfig.add", b24.Params{
"moduleId": "crm",
"field": b24.Params{
"entityId": "CRM_7",
"fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
"userTypeId": "enumeration",
"multiple": "Y",
"editFormLabel": b24.Params{
"ru": "Список характеристик",
"en": "List of characteristics",
},
"enum": []b24.Params{
{
"value": "Характеристика 1",
"def": "N",
"sort": 100,
},
{
"value": "Характеристика 2",
"def": "Y",
"sort": 200,
},
},
},
})
if err != nil {
return fmt.Errorf("userfieldconfig.add: %w", err)
}
// Метод заворачивает ответ в объект с ключом "field".
raw, ok := b24.Unwrap(res.Result, "field")
if !ok {
return fmt.Errorf("в ответе нет ключа field")
}
var item struct {
ID b24.ID `json:"id"`
EntityID string `json:"entityId"`
FieldName string `json:"fieldName"`
UserTypeID string `json:"userTypeId"`
Sort string `json:"sort"`
Multiple string `json:"multiple"`
}
if err := json.Unmarshal(raw, &item); err != nil {
return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println(item.ID, item.EntityID)
Ответ
HTTP-статус: 200
{
"result": {
"field": {
"id": "6953",
"entityId": "CRM_7",
"fieldName": "UF_CRM_7_NEW_REST_LIST_2026",
"userTypeId": "enumeration",
"xmlId": null,
"sort": "100",
"multiple": "Y",
"mandatory": "N",
"showFilter": "N",
"showInList": "Y",
"editInList": "Y",
"isSearchable": "N",
"settings": {
"DISPLAY": "LIST",
"LIST_HEIGHT": 1,
"CAPTION_NO_VALUE": "",
"SHOW_NO_VALUE": "Y"
},
"languageId": {
"en": "en",
"ru": "ru"
},
"editFormLabel": {
"en": "List of characteristics",
"ru": "Список характеристик"
},
"listColumnLabel": {
"en": null,
"ru": null
},
"listFilterLabel": {
"en": null,
"ru": null
},
"errorMessage": {
"en": null,
"ru": null
},
"helpMessage": {
"en": null,
"ru": null
},
"enum": [
{
"id": "3363",
"userFieldId": "6953",
"value": "Характеристика 1",
"def": "N",
"sort": "100",
"xmlId": "56dff18efcfe25f3bae0117a6b372567"
},
{
"id": "3365",
"userFieldId": "6953",
"value": "Характеристика 2",
"def": "Y",
"sort": "200",
"xmlId": "42e3ebcf5506a65283bf3bf510d8f05a"
}
]
}
},
"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
object
Корневой элемент ответа (подробное описание)
time
time
Информация о времени выполнения запроса
Обработка ошибок
HTTP-статус: 400
{
"error": "",
"error_description": "The 'FIELD_NAME' field is not found."
}
| Код | Описание | Значение |
|---|---|---|
| — | Access denied | Недостаточно прав для создания пользовательского поля |
| — | Вы не можете создавать пользовательские поля | Ошибка может возвращаться, если field.fieldName не начинается с UF_{entityId}_ |
| — | The 'USER_TYPE_ID' field is not found | Не передан обязательный field.userTypeId |
| — | The 'FIELD_NAME' field is not found | Не передан обязательный field.fieldName |
| — | Поле ... уже существует | Переданный field.fieldName уже используется для этого объекта |
| — | Fail to create new user field | Ошибка создания поля на стороне сервера |
| — | Fail to save enumeration field values | Ошибка сохранения значений списка для типа enumeration |

