Создать элемент справочника crm.status.add

Если вы разрабатываете интеграции для Битрикс24 с помощью AI-инструментов (Codex, Claude Code, Cursor), подключите MCP-сервер, чтобы ассистент использовал официальную REST-документацию.

Scope: crm

Кто может выполнять метод: пользователь с правами администратора CRM

Метод crm.status.add создает новый элемент в указанном справочнике CRM: стадия сделки, источник, тип компании и другие.

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

Обязательные параметры отмечены *

Название
тип

Описание

fields*
object

Объект с полями нового элемента справочника. Список доступных полей описан ниже

Параметр fields

Название
тип

Описание

ENTITY_ID*
string

Тип справочника, например DEAL_STAGE, SOURCE. Получить список типов можно методом crm.status.entity.types

STATUS_ID*
string

Код значения статуса. Код должен быть уникальным в рамках справочника. Ограничения по длине и символам зависят от типа справочника

NAME*
string

Название

SORT
integer

Сортировка. По умолчанию 10

COLOR
string

Цвет hex-код, например #39A8EF. Используйте для статусов-стадий

SEMANTICS
string

Группа стадий:

  • "S" — «Успех»,
  • "F" — «Провал»,
  • "" — «В работе».

Используйте для статусов-стадий. По умолчанию передается группа «В работе»

Особенности полей

Ограничения для STATUS_ID

Соблюдайте ограничения по длине и используемым символам для разных типов справочников:

  • STATUS стадии лида. Макс. длина: 21, может содержать только латинские буквы, цифры, знаки тире и подчеркивания.
  • QUOTE_STATUS стадии предложения. Макс. длина: 22, может содержать только латинские буквы, цифры, знаки тире и подчеркивания.
  • DEAL_STAGE стадии сделки. Макс. длина: 22, может содержать только латинские буквы, цифры, знаки тире и подчеркивания.
  • DEAL_STAGE_xx стадии сделки в воронках не по умолчанию. xx — идентификатор воронки. Макс. длина зависит от идентификатора воронки. Может содержать только латинские буквы, цифры, знаки тире и подчеркивания.
  • Для остальных ENTITY_ID, максимальная длина STATUS_ID - 50 символов, содержать может любые символы.

Если добавляется стадия для пользовательской воронки сделок, то к идентификатору статуса будет автоматически добавлен префикс воронки. Это нужно, чтобы определить воронку по идентификатору стадии.

Например, значение DECISION для воронки сделок с идентификатором 1 будет сохранено как С1:DECISION. Система автоматически добавит префикс C1:, соответствующий идентификатору воронки сделок.
При передаче в поле значения сразу с префиксом С1:DECISION оно будет сохранено как С1:DECISION, дополнительный префикс не добавится.

Для смарт-процессов с воронками действует аналогичная логика формирования STATUS_ID из значения и префикса. Префикс воронки можно узнать методом crm.status.entity.types.

Ограничения для SORT

Для корректной работы статусов-стадий сортировка должна соблюдать порядок:

  1. Стадии группы «В работе»
  2. Стадия группы «Успех»
  3. Стадии группы «Провал»

Примеры кода

Как использовать примеры в документации

curl -X POST \
             -H "Content-Type: application/json" \
             -H "Accept: application/json" \
             -d '{"fields":{"ENTITY_ID":"DEAL_STAGE_1","STATUS_ID":"DECISION","NAME":"Принятие решения","SORT":70,"COLOR":"#FFA900"}}' \
             https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.status.add
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"fields":{"ENTITY_ID":"DEAL_STAGE_1","STATUS_ID":"DECISION","NAME":"Принятие решения","SORT":70,"COLOR":"#FFA900"},"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.status.add
        
try
        {
        	const response = await $b24.callMethod(
        		'crm.status.add',
        		{
        			fields: {
        				ENTITY_ID: 'DEAL_STAGE_1',
        				STATUS_ID: 'DECISION',
        				NAME: 'Принятие решения',
        				SORT: 70,
        				COLOR: '#FFA900'
        			}
        		}
        	);
        	
        	const result = response.getData().result;
        	if (result.error())
        		console.error(result.error());
        	else
        		console.dir(result);
        }
        catch( error )
        {
        	console.error('Error:', error);
        }
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'crm.status.add',
                    [
                        'fields' => [
                            'ENTITY_ID' => 'DEAL_STAGE_1',
                            'STATUS_ID' => 'DECISION',
                            'NAME'     => 'Принятие решения',
                            'SORT'     => 70,
                            'COLOR'    => '#FFA900',
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            if ($result->error()) {
                error_log($result->error());
                echo 'Error: ' . $result->error();
            } else {
                echo 'Success: ' . print_r($result->data(), true);
            }
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error adding status: ' . $e->getMessage();
        }
        
BX24.callMethod(
            "crm.status.add",
            {
                fields: {
                    ENTITY_ID: "DEAL_STAGE_1",
                    STATUS_ID: "DECISION",
                    NAME: "Принятие решения",
                    SORT: 70,
                    COLOR: "#FFA900"
                }
            },
            function(result) {
                if(result.error())
                    console.error(result.error());
                else
                    console.dir(result.data());
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'crm.status.add',
            [
                'fields' => [
                    'ENTITY_ID' => 'DEAL_STAGE_1',
                    'STATUS_ID' => 'DECISION',
                    'NAME' => 'Принятие решения',
                    'SORT' => 70,
                    'COLOR' => '#FFA900'
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

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

HTTP-статус: 200

{
            "result": 773,
            "time": {
                "start": 1752215174.862923,
                "finish": 1752215174.916697,
                "duration": 0.053774118423461914,
                "processing": 0.014070987701416016,
                "date_start": "2025-07-11T09:26:14+03:00",
                "date_finish": "2025-07-11T09:26:14+03:00",
                "operating_reset_at": 1752215774,
                "operating": 0
            }
        }

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

Название
тип

Описание

result
integer

Идентификатор созданного элемента справочника

time
time

Информация о времени выполнения запроса

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

HTTP-статус: 400

{
            "error": "Invalid parameters.",
            "error_description": "Переданы некорректные параметры."
        }

Название
тип

Описание

error
string

Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания

error_description
error_description

Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

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

Код

Описание

Значение

400

Access denied.

Нет прав на выполнение операции

400

Invalid parameters.

Переданы некорректные параметры

400

Specified entity type is not supported.

Указан неподдерживаемый тип справочника

400

The field ENTITY_ID is required.

Не указан ENTITY_ID

400

The field STATUS_ID is required.

Не указан STATUS_ID

400

Duplicate STATUS_ID.

Такой STATUS_ID уже существует

400

Error on creating status.

Ошибка при создании элемента

400

Нельзя создать промежуточную стадию после успешной

400

Не заполнено обязательное поле "Заголовок"

Статусы и коды системных ошибок

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически через 10 минут

405

ERROR_BATCH_METHOD_NOT_ALLOWED
Method is not allowed for batch usage

Текущий метод не разрешен для вызова с помощью batch

400

ERROR_BATCH_LENGTH_EXCEEDED
Max batch length exceeded

Превышена максимальная длина параметров, переданных в метод batch

401

NO_AUTH_FOUND
Wrong authorization data

Неверный access-токен или код вебхука

400

INVALID_REQUEST
Https required

Для вызовов методов требуется использовать протокол HTTPS

503

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24

403

ACCESS_DENIED
REST API is available only on commercial plans

REST API доступен только на коммерческих планах

403

INVALID_CREDENTIALS
Invalid request credentials

У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав

404

ERROR_MANIFEST_IS_NOT_AVAILABLE
Manifest is not available

Манифест недоступен

403

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более высоких привилегий, чем предоставляет токен вебхука

401

expired_token
The access token provided has expired

Предоставленный access-токен доступа истек

403

user_access_error
The user does not have access to the application

Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям

500

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение

Предыдущая
Обзор методов
Следующая
Обновить элемент справочника