Изменить вид карточки v 3.0 crm.<тип>.detailpagelayout.update

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Scope: crm

Кто может выполнять метод: любой пользователь — свой личный вид; общий и дополнительные виды — пользователь с правом изменять общий вид карточки этого типа объекта, например администратор CRM; личный вид другого пользователя — администратор CRM

Метод относится к REST 3.0. Особенности вызова и формат ответа новой версии API описаны в обзоре REST 3.0.

Метод crm.<тип>.detailpagelayout.update изменяет личный, общий или дополнительный вид карточки элемента CRM. Тип объекта задает сегмент <тип> в имени метода.

У личного и общего вида меняется только набор разделов и полей configuration. У дополнительного вида можно изменить также название name и аудиторию audience. Метод меняет только переданные ключи fields, а каждый переданный ключ заменяет значение целиком: новый массив configuration заменяет все разделы, новый массив audience — всех участников.

Имя метода для типа объекта

Тип объекта

Метод

Сделка

crm.deal.detailpagelayout.update

Лид

crm.lead.detailpagelayout.update

Контакт

crm.contact.detailpagelayout.update

Компания

crm.company.detailpagelayout.update

Предложение

crm.quote.detailpagelayout.update

Счет

crm.smartinvoice.detailpagelayout.update

Документ CRM

crm.smartdocument.detailpagelayout.update

Документ КЭДО

crm.smartb2edocument.detailpagelayout.update

Смарт-процесс

crm.smartprocess<entityTypeId>.detailpagelayout.update, например crm.smartprocess1038.detailpagelayout.update

Для смарт-процесса в имя метода подставляется идентификатор его типа entityTypeId. Идентификаторы типов можно получить методом crm.type.list. Методы видов карточки есть у смарт-процесса при любых настройках типа. У моей компании этих методов нет.

Имя метода пишется в нижнем регистре: crm.deal.detailpagelayout.update, а не crm.deal.detailPageLayout.update. На имя в другом регистре метод отвечает ошибкой «Метод не найден».

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

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

Название
тип

Описание

id*
string

Идентификатор вида карточки — строка:

  • C<categoryId>:personal — личный вид, например C69:personal
  • C<categoryId>:common — общий вид, например C69:common
  • число в строке, например "17", — дополнительный вид

У лида и предложения воронок нет, их личный и общий вид — personal и common. Для повторных лидов у лида есть отдельные виды personal_returning_customer и common_returning_customer.

Вид должен относиться к воронке из categoryId. Идентификаторы личного и общего вида возвращают методы crm.<тип>.detailpagelayout.getpersonallayoutid и crm.<тип>.detailpagelayout.getcommonlayoutid, дополнительных — метод crm.<тип>.detailpagelayout.list

categoryId*
integer

Идентификатор воронки. Виды карточки хранятся отдельно для каждой воронки.

Значение зависит от типа объекта:

  • лид и предложение — только 0, воронок у них нет
  • сделка, контакт и компания — идентификатор воронки, 0 — воронка по умолчанию
  • счет, документы и смарт-процесс — идентификатор воронки. Значение 0 метод заменяет идентификатором воронки по умолчанию

Идентификаторы воронок сделок, контактов, компаний и смарт-процессов можно получить методом crm.<тип>.category.list

userId
integer

Идентификатор пользователя, чей вид изменить. Нужен, чтобы изменить личный вид другого пользователя. Передавать идентификатор другого пользователя может только администратор CRM.

По умолчанию — пользователь, который вызывает метод.

Идентификаторы пользователей можно получить методом user.get

fields*
object

Новые значения вида (подробное описание)

Параметр fields

Передайте хотя бы один ключ.

Название
тип

Описание

configuration
object[]

Разделы карточки в порядке вывода (подробное описание). Массив заменяет все разделы вида, поэтому передавайте конфигурацию целиком. Текущую конфигурацию возвращает метод crm.<тип>.detailpagelayout.get

name
string

Новое название дополнительного вида, до 100 символов. У личного и общего вида названия нет

audience
object[]

Новый список участников дополнительного вида, хотя бы один (подробное описание). Список заменяет прежний целиком. Пользователь, который вызывает метод, в аудиторию сам не попадает. У личного и общего вида аудитории нет

Параметр configuration

Массив разделов карточки в порядке вывода. Каждый раздел — объект:

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

Название
тип

Описание

name*
string

Код раздела, уникальный в пределах вида, например main

title*
string

Заголовок раздела в карточке

elements*
object[]

Поля раздела в порядке вывода (подробное описание). Можно передать пустой массив

Поле раздела

Название
тип

Описание

name*
string

Имя поля в карточке: TITLE, STAGE_ID, OPPORTUNITY_WITH_CURRENCY, пользовательское поле UF_CRM_1687529546. Имена пишутся в верхнем регистре и не совпадают с именами полей элемента в REST 3.0

optionFlags
integer

Показывать ли поле, когда оно не заполнено.

Возможные значения:

  • 1 — показывать всегда
  • 0 — показывать, только если поле заполнено

options
object

Настройки поля в формате {"настройка": "значение"}, например {"defaultCountry": "RU"} для телефона. Набор настроек зависит от поля. Настройки полей есть в конфигурации вида, которую возвращает метод crm.<тип>.detailpagelayout.get

Метод не проверяет, есть ли поле с таким именем у типа объекта: вид с неизвестным именем поля сохранится. Готовые имена полей и их настройки возьмите из конфигурации общего вида — ее возвращает метод crm.<тип>.detailpagelayout.get с идентификатором из crm.<тип>.detailpagelayout.getcommonlayoutid.

Параметр audience

Массив участников, которым доступен дополнительный вид. Участник — объект:

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

Название
тип

Описание

type*
string

Тип участника.

Возможные значения:

  • user — сотрудник. Идентификатор можно получить методом user.get
  • department — отдел вместе с подотделами. Идентификатор можно получить методом department.get
  • project — группа или проект. Идентификатор можно получить методом sonet_group.get
  • structure-node — узел структуры компании вместе с дочерними узлами

id*
integer

Идентификатор участника, положительное число

В аудитории может быть до 1000 участников.

Примеры кода

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

Вызов нового API отличается добавлением параметра /api/ в запросе:

https://{адрес_установки}/rest/api/{id_пользователя}/{токен_вебхука}/crm.smartprocess1038.detailpagelayout.update

Примеры меняют название и аудиторию дополнительного вида 17 смарт-процесса с идентификатором типа 1038: вид становится доступен отделу 47 и сотруднику 29. Для другого типа объекта замените имя метода по таблице выше.

curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"categoryId":0,"id":"17","fields":{"name":"Карточка для закупок и склада","audience":[{"type":"department","id":47},{"type":"user","id":29}]}}' \
https://**put_your_bitrix24_address**/rest/api/**put_your_user_id_here**/**put_your_webhook_here**/crm.smartprocess1038.detailpagelayout.update
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"categoryId":0,"id":"17","fields":{"name":"Карточка для закупок и склада","audience":[{"type":"department","id":47},{"type":"user","id":29}]},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/api/crm.smartprocess1038.detailpagelayout.update

Методы CRM пока не входят в список методов REST 3.0, который знает $b24.actions.v3.call.make: такой вызов вернет ошибку SDK JSSDK_CORE_METHOD_NOT_SUPPORT_IN_API_V3. Вызывайте метод через HTTP-клиент REST 3.0 — $b24.getHttpClient(ApiVersion.v3).call.

import { ApiVersion, Text } from '@bitrix24/b24jssdk'
import type { B24Frame } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

type LayoutChangeResult = {
  result: boolean
}

try {
  const response = await $b24.getHttpClient(ApiVersion.v3).call<LayoutChangeResult>(
    'crm.smartprocess1038.detailpagelayout.update',
    {
      categoryId: 0,
      id: '17',
      fields: {
        name: 'Карточка для закупок и склада',
        audience: [
          { type: 'department', id: 47 },
          { type: 'user', id: 29 },
        ],
      },
    },
    Text.getUuidRfc4122()
  )

  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Layout updated:', result.result)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}

Методы CRM пока не входят в список методов REST 3.0, который знает $b24.actions.v3.call.make. Вызывайте метод через HTTP-клиент REST 3.0 — $b24.getHttpClient(B24Js.ApiVersion.v3).call.

<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function updateLayout() {
    try {
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.getHttpClient(B24Js.ApiVersion.v3).call(
        'crm.smartprocess1038.detailpagelayout.update',
        {
          categoryId: 0,
          id: '17',
          fields: {
            name: 'Карточка для закупок и склада',
            audience: [
              { type: 'department', id: 47 },
              { type: 'user', id: 29 },
            ],
          },
        },
        B24Js.Text.getUuidRfc4122()
      )

      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Layout updated:', result.result)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', updateLayout)
</script>

У методов CRM нет готовых оберток в b24pysdk, и SDK отправляет в REST 3.0 только методы из списка Config().api_v3_methods. Добавьте метод в этот список и вызовите его через bitrix_token.call_method с prefer_version=3.

from b24pysdk import Config
from b24pysdk.errors import BitrixSDKException
from b24pysdk.errors.v3 import BitrixAPIError

method = "crm.smartprocess1038.detailpagelayout.update"
Config().configure(api_v3_methods=Config().api_v3_methods | {method})

try:
    response = bitrix_token.call_method(
        api_method=method,
        params={
            "categoryId": 0,
            "id": "17",
            "fields": {
                "name": "Карточка для закупок и склада",
                "audience": [
                    {"type": "department", "id": 47},
                    {"type": "user", "id": 29},
                ],
            },
        },
        prefer_version=3,
    )
    result = response["result"]
    print(result["result"])
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"code: {error.code}",
        f"message: {error.error.message}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")

SDK пока не поддерживает вызовы по адресу /rest/api/. Используйте прямой HTTP-запрос, например через cURL или fetch.

try {
    $response = $b24Service
        ->core
        ->call(
            'crm.smartprocess1038.detailpagelayout.update',
            [
                'categoryId' => 0,
                'id' => '17',
                'fields' => [
                    'name' => 'Карточка для закупок и склада',
                    'audience' => [
                        ['type' => 'department', 'id' => 47],
                        ['type' => 'user', 'id' => 29],
                    ],
                ],
            ]
        );

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

    print_r($result);
} catch (Throwable $e) {
    echo $e->getMessage();
}

SDK пока не поддерживает вызовы по адресу /rest/api/. Используйте прямой HTTP-запрос, например через cURL или fetch.

BX24.callMethod(
    'crm.smartprocess1038.detailpagelayout.update',
    {
        categoryId: 0,
        id: '17',
        fields: {
            name: 'Карточка для закупок и склада',
            audience: [
                { type: 'department', id: 47 },
                { type: 'user', id: 29 },
            ],
        },
    },
    result => {
        if (result.error())
            console.error(result.error());
        else
            console.dir(result.data());
    }
);

SDK пока не поддерживает вызовы по адресу /rest/api/. Используйте прямой HTTP-запрос, например через cURL или fetch.

require_once('crest.php');

$result = CRest::call(
    'crm.smartprocess1038.detailpagelayout.update',
    [
        'categoryId' => 0,
        'id' => '17',
        'fields' => [
            'name' => 'Карточка для закупок и склада',
            'audience' => [
                ['type' => 'department', 'id' => 47],
                ['type' => 'user', 'id' => 29],
            ],
        ],
    ]
);

echo '<PRE>';
print_r($result);
echo '</PRE>';
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "crm.smartprocess1038.detailpagelayout.update", b24.Params{
	"categoryId": 0,
	"id":         "17",
	"fields": b24.Params{
		"name": "Карточка для закупок и склада",
		"audience": []b24.Params{
			{"type": "department", "id": 47},
			{"type": "user", "id": 29},
		},
	},
})
if err != nil {
	return fmt.Errorf("crm.smartprocess1038.detailpagelayout.update: %w", err)
}

var answer struct {
	Result bool `json:"result"`
}
if err := json.Unmarshal(res.Result, &answer); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println(answer.Result)

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

HTTP-статус: 200

{
    "result": {
        "result": true
    },
    "time": {
        "start": 1793706651,
        "finish": 1793706651.905107,
        "duration": 0.9051070213317871,
        "processing": 0,
        "date_start": "2026-11-03T14:50:51+03:00",
        "date_finish": "2026-11-03T14:50:51+03:00",
        "operating_reset_at": 1793707200,
        "operating": 0
    }
}

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

Название
тип

Описание

result
object

Объект с данными ответа

result.result
boolean

true, если вид изменен

time
time

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

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

HTTP-статус: 400

{
    "error": {
        "code": "INVALID_LAYOUT_AUDIENCE",
        "message": "Invalid form layout audience."
    }
}

Название
тип

Описание

error.code
string

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

error.message
string

Текстовое описание ошибки

error.validation
array

Массив c деталями ошибки. Присутствует только в ошибках валидации данных BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION

error.validation[].field
string

Название поля, в котором возникла ошибка валидации

error.validation[].message
string

Описание ошибки, связанной с указанным полем

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

Ошибки видов карточки приходят с короткими кодами без префикса BITRIX_REST_V3_, например LAYOUT_NOT_FOUND, и с текстом на английском языке. HTTP-статус у таких ошибок разный, он указан рядом с кодом. Ошибки с кодами BITRIX_REST_V3_* приходят со статусом 400.

Неверная конфигурация вида

Код ошибки: INVALID_LAYOUT_CONFIGURATION, HTTP-статус: 400

Поле

Описание ошибки

Как исправить

-

Invalid form layout configuration.

Не передавайте name для личного и общего вида. Проверьте, что name не длиннее 100 символов, а configuration — не пустой массив

Неверная аудитория вида

Код ошибки: INVALID_LAYOUT_AUDIENCE, HTTP-статус: 400

Поле

Описание ошибки

Как исправить

-

Invalid form layout audience.

Не передавайте audience для личного и общего вида. Проверьте, что audience — не пустой массив и в нем не больше 1000 участников

Неверный идентификатор вида

Код ошибки: INVALID_LAYOUT_ID, HTTP-статус: 400

Поле

Описание ошибки

Как исправить

-

Invalid form layout ID.

Проверьте формат id и воронку: идентификатор вида должен относиться к воронке из categoryId

Вид карточки не найден

Код ошибки: LAYOUT_NOT_FOUND, HTTP-статус: 404

Поле

Описание ошибки

Как исправить

-

The form layout was not found.

Проверьте id: дополнительного вида нет, он в другой воронке или у пользователя нет к нему доступа

Ошибки валидации запроса

Код ошибки: BITRIX_REST_V3_EXCEPTION_VALIDATION_REQUESTVALIDATIONEXCEPTION

Поле

Описание ошибки

Как исправить

categoryId

Обязательное поле categoryId не указано

Передайте categoryId. Для лида и предложения — 0

categoryId

В поле categoryId требуется тип данных int для такого запроса

Передайте categoryId числом, а не строкой

categoryId

Значение поля должно быть не меньше, чем 0

Передайте 0 или идентификатор воронки

userId

Значение поля должно быть не меньше, чем 1

Передайте идентификатор существующего пользователя или не передавайте userId

id

Обязательное поле id не указано

Передайте идентификатор вида

id

В поле id требуется тип данных string для такого запроса

Передайте id строкой, например "17"

fields

Обязательное поле fields не указано

Передайте в fields хотя бы один ключ. Ошибка приходит и на пустой объект fields

Ошибки валидации объекта

Код ошибки: BITRIX_REST_V3_EXCEPTION_VALIDATION_DTOVALIDATIONEXCEPTION

Поле

Описание ошибки

Как исправить

audience.0.type

Значение поля не содержится в списке допустимых значений: user, department, project, structure-node

Передайте один из типов участника из описания параметра

configuration.0.elements

Не заполнено обязательное поле "elements"

Передайте в каждом разделе name, title и elements

Ошибка неизвестного поля

Код ошибки: BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION

Поле

Описание ошибки

Как исправить

-

Неизвестное поле #FIELD# для сущности LayoutFieldsDto

Уберите лишний ключ. Запрос принимает id, categoryId, userId и fields

Неподдерживаемая воронка

Код ошибки: UNSUPPORTED_CONTEXT, HTTP-статус: 400

Поле

Описание ошибки

Как исправить

-

This form layout context is not supported.

Проверьте categoryId: у лида и предложения передавайте 0, у остальных типов — идентификатор существующей воронки этого типа объекта

Нет доступа

Код ошибки: PERMISSION_DENIED, HTTP-статус: 403

Поле

Описание ошибки

Как исправить

-

Insufficient permissions to work with this form layout.

Общий и дополнительные виды изменяет пользователь с правом изменять общий вид карточки, личный вид другого пользователя — администратор CRM

Ошибка сохранения

Код ошибки: STORAGE_FAILED, HTTP-статус: 500

Поле

Описание ошибки

Как исправить

-

Could not complete the operation on the form layout.

Повторите запрос позже. Если ошибка повторяется, обратитесь в поддержку

Изменения применены частично

Код ошибки: CONSISTENCY_FAILURE, HTTP-статус: 500

Поле

Описание ошибки

Как исправить

-

Form layout changes were partially applied.

Часть изменений сохранилась. Прочитайте вид методом crm.<тип>.detailpagelayout.get и повторите изменение

Метод не найден

Код ошибки: BITRIX_REST_V3_EXCEPTION_METHODNOTFOUNDEXCEPTION, HTTP-статус 404

Поле

Описание ошибки

Как исправить

-

Метод #METHOD# не найден

Проверьте имя метода: оно пишется в нижнем регистре, например crm.deal.detailpagelayout.update. У моей компании методов видов карточки нет. Для смарт-процесса проверьте entityTypeId методом crm.type.list

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

HTTP-статус: 4xx, 5xx

Описанные ниже ошибки возвращает сам REST API, а не логика конкретного метода. Они могут прийти в ответ на любой метод.

Статус

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

Описание

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

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

401

NO_AUTH_FOUND
Wrong authorization data

В запросе нет авторизационных данных: не передан ни access-токен, ни код вебхука

401

INVALID_REQUEST
Https required

Методы вызываются только по протоколу HTTPS

401

OVERLOAD_LIMIT
REST API is blocked due to overload

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

401

ACCESS_DENIED
REST is available only on commercial plans

REST API доступен только на коммерческих тарифах. У вебхука текст ошибки другой — REST is available only by subscription

401

INVALID_CREDENTIALS
Invalid request credentials

Не найден активный вебхук с указанным идентификатором пользователя и секретным кодом

404

ERROR_METHOD_NOT_FOUND
Method not found!

Метод с таким именем не найден. Имя написано с ошибкой, метода нет в REST API или он недоступен без нужного скоупа

401

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

Запрос требует более широких прав, чем есть у токена: у вебхука это выданные ему права, у приложения — скоуп. У приложения текст ошибки заканчивается на provided by the access token

401

expired_token
The access token provided has expired

Срок действия access-токена истек

401

user_access_error
The user does not have access to the application

Приложение установлено, но администратор Битрикс24 открыл доступ к нему только конкретным пользователям

403

PORTAL_DELETED
Portal was deleted

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

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