Каждый PHP-разработчик, работающий с экосистемой Bitrix Framework, должен глубоко понимать работу её ключевых компонентов. В этой статье мы проведем подробный аудит темы «Создать поле универсального списка lists.field.add», проанализируем лучшие практики и покажем, как правильно использовать lists.field.add в реальных задачах.

Создать поле универсального списка lists.field.add

> Scope: lists
>
> Кто может выполнять метод: пользователь с правом «Полный доступ» для нужного списка

Метод lists.field.add создает поле списка.

Список доступных типов полей для универсального списка можно узнать с помощью метода lists.field.type.get

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

Параметр FIELDS {#parametr-fields}

Примеры кода

• cURL (Webhook)

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"IBLOCK_TYPE_ID":"lists","IBLOCK_ID":"123","FIELDS":{"NAME":"Проект","IS_REQUIRED":"Y","MULTIPLE":"N","TYPE":"L","SORT":"10","CODE":"PROJECT","LIST":{"10":{"VALUE":"Планирование","SORT":10,"DEF":"Y"},"20":{"VALUE":"В разработке","SORT":20,"DEF":"N"}},"LIST_TEXT_VALUES":"Тестирование\nЗавершен\nОтложен","SETTINGS":{"SHOW_ADD_FORM":"Y","SHOW_EDIT_FORM":"Y","ADD_READ_ONLY_FIELD":"N","EDIT_READ_ONLY_FIELD":"N","SHOW_FIELD_PREVIEW":"N"}}}' \
    https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webbhook_here**/lists.field.add

• cURL (OAuth)

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"IBLOCK_TYPE_ID":"lists","IBLOCK_ID":"123","FIELDS":{"NAME":"Проект","IS_REQUIRED":"Y","MULTIPLE":"N","TYPE":"L","SORT":"10","CODE":"PROJECT","LIST":{"10":{"VALUE":"Планирование","SORT":10,"DEF":"Y"},"20":{"VALUE":"В разработке","SORT":20,"DEF":"N"}},"LIST_TEXT_VALUES":"Тестирование\nЗавершен\nОтложен","SETTINGS":{"SHOW_ADD_FORM":"Y","SHOW_EDIT_FORM":"Y","ADD_READ_ONLY_FIELD":"N","EDIT_READ_ONLY_FIELD":"N","SHOW_FIELD_PREVIEW":"N"}},"auth":"**put_access_token_here**"}' \
    https://**put_your_bitrix24_address**/rest/lists.field.add

• JS

    try {
        const response = await $b24.callMethod(
            'lists.field.add',
            {
                IBLOCK_TYPE_ID: 'lists',
                IBLOCK_ID: '123',
                FIELDS: {
                    NAME: 'Проект',
                    IS_REQUIRED: 'Y',
                    MULTIPLE: 'N',
                    TYPE: 'L',
                    SORT: '10',
                    CODE: 'PROJECT',
                    LIST: {
                        '10': { VALUE: 'Планирование', SORT: 10, DEF: 'Y' },
                        '20': { VALUE: 'В разработке', SORT: 20, DEF: 'N' }
                    },
                    LIST_TEXT_VALUES: 'Тестирование\nЗавершен\nОтложен',
                    SETTINGS: {
                        SHOW_ADD_FORM: 'Y',
                        SHOW_EDIT_FORM: 'Y',
                        ADD_READ_ONLY_FIELD: 'N',
                        EDIT_READ_ONLY_FIELD: 'N',
                        SHOW_FIELD_PREVIEW: 'N'
                    }
                }
            }
        );

        const result = response.getData().result;
        console.log('Created field with ID:', result);
        processResult(result);
    } catch (error) {
        console.error('Error:', error);
    }

• PHP

    try {
        $response = $b24Service
            ->core
            ->call(
                'lists.field.add',
                [
                    'IBLOCK_TYPE_ID' => 'lists',
                    'IBLOCK_ID' => '123',
                    'FIELDS' => [
                        'NAME' => 'Проект',
                        'IS_REQUIRED' => 'Y',
                        'MULTIPLE' => 'N',
                        'TYPE' => 'L',
                        'SORT' => '10',
                        'CODE' => 'PROJECT',
                        'LIST' => [
                            '10' => ['VALUE' => 'Планирование', 'SORT' => 10, 'DEF' => 'Y'],
                            '20' => ['VALUE' => 'В разработке', 'SORT' => 20, 'DEF' => 'N']
                        ],
                        'LIST_TEXT_VALUES' => 'Тестирование\nЗавершен\nОтложен',
                        'SETTINGS' => [
                            'SHOW_ADD_FORM' => 'Y',
                            'SHOW_EDIT_FORM' => 'Y',
                            'ADD_READ_ONLY_FIELD' => 'N',
                            'EDIT_READ_ONLY_FIELD' => 'N',
                            'SHOW_FIELD_PREVIEW' => 'N'
                        ]
                    ]
                ]
            );

        $result = $response
            ->getResponseData()
            ->getResult();

        echo 'Success: ' . print_r($result, true);
        processData($result);

    } catch (Throwable $e) {
        error_log($e->getMessage());
        echo 'Error adding field: ' . $e->getMessage();
    }

• BX24.js

    BX24.callMethod(
        'lists.field.add',
        {
            'IBLOCK_TYPE_ID': 'lists',
            'IBLOCK_ID': '123',
            'FIELDS': {
                'NAME': 'Проект',
                'IS_REQUIRED': 'Y',
                'MULTIPLE': 'N',
                'TYPE': 'L',
                'SORT': '10',
                'CODE': 'PROJECT',
                // Задаем основные значения с настройками
                'LIST': {
                    '10': { 'VALUE': 'Планирование', 'SORT': 10, 'DEF': 'Y' },
                    '20': { 'VALUE': 'В разработке', 'SORT': 20, 'DEF': 'N' }
                },
                // Добавляем еще значения простой строкой
                'LIST_TEXT_VALUES': 'Тестирование\nЗавершен\nОтложен',
                'SETTINGS': {
                    'SHOW_ADD_FORM': 'Y',
                    'SHOW_EDIT_FORM': 'Y',
                    'ADD_READ_ONLY_FIELD': 'N',
                    'EDIT_READ_ONLY_FIELD': 'N',
                    'SHOW_FIELD_PREVIEW': 'N'
                }
            }
        },
        function(result) {
            if (result.error()) {
                console.error(result.error());
            } else {
                console.log(result.data());
                // Итоговый список будет содержать 5 вариантов:
                // 1. Планирование (по умолчанию), 2. В разработке,
                // 3. Тестирование, 4. Завершен, 5. Отложен
            }
        }
    );

• PHP CRest

    require_once('crest.php');

    $result = CRest::call(
        'lists.field.add',
        [
            'IBLOCK_TYPE_ID' => 'lists',
            'IBLOCK_ID' => '123',
            'FIELDS' => [
                'NAME' => 'Проект',
                'IS_REQUIRED' => 'Y',
                'MULTIPLE' => 'N',
                'TYPE' => 'L',
                'SORT' => '10',
                'CODE' => 'PROJECT',
                'LIST' => [
                    '10' => ['VALUE' => 'Планирование', 'SORT' => 10, 'DEF' => 'Y'],
                    '20' => ['VALUE' => 'В разработке', 'SORT' => 20, 'DEF' => 'N']
                ],
                'LIST_TEXT_VALUES' => 'Тестирование\nЗавершен\nОтложен',
                'SETTINGS' => [
                    'SHOW_ADD_FORM' => 'Y',
                    'SHOW_EDIT_FORM' => 'Y',
                    'ADD_READ_ONLY_FIELD' => 'N',
                    'EDIT_READ_ONLY_FIELD' => 'N',
                    'SHOW_FIELD_PREVIEW' => 'N'
                ]
            ]
        ]
    );

    echo '<PRE>';
    print_r($result);
    echo '</PRE>';

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

HTTP-статус: 200

{
    "result": "PROPERTY_1151",
    "time": {
        "start": 1765317940,
        "finish": 1765317940.172892,
        "duration": 0.17289209365844727,
        "processing": 0,
        "date_start": "2025-12-09T14:05:40+03:00",
        "date_finish": "2025-12-09T14:05:40+03:00",
        "operating_reset_at": 1765318540,
        "operating": 0
    }
}

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

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

HTTP-статус: 400

{
    "error":"ERROR_SAVE_FIELD",
    "error_description":"Please fill the code fields"
}

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

• [](./lists-field-update)
• [](./lists-field-get)
• [](./lists-field-delete)
• [](./lists-field-type-get)