Установить раскладку карточки

PUT /v1/crm/card-config/:entityTypeId

Записывает раскладку секций и полей карточки для указанной области. Полностью заменяет прежнюю раскладку этой области. Тело содержит массив секций data — каждая секция описывает блок карточки и его поля.

Параметр пути

Параметр Тип Описание
entityTypeId number Тип CRM-объекта:
1 — лид
2 — сделка
3 — контакт
4 — компания
7 — предложение
31 — счёт
смарт-процесс — числовой ID типа из `GET /v1/smart-processes`, поле entityTypeId

Поля запроса (body)

Поле Тип Обяз. Описание
data array да Массив секций раскладки в порядке отображения
data[].name string да Внутреннее имя секции
data[].title string да Отображаемое название секции
data[].type string да Всегда section
data[].elements array да Поля секции в порядке отображения
data[].elements[].name string да Имя поля CRM в формате Битрикс24: TITLE, NAME, PHONE, UF_CRM_1234567890 для пользовательских полей. Источник для пользовательских полей: `GET /v1/userfields/:entity`
data[].elements[].optionFlags number нет Флаг поля: 0 — обычное, 1 — поле клиента
data[].elements[].options object нет Параметры конкретного поля, например defaultCountry для PHONE или defaultAddressType для ADDRESS
scope string нет Область раскладки: P — личная (по умолчанию), C — общая
userId number нет Сотрудник, чью личную раскладку записать. По умолчанию — владелец API-ключа. Имеет смысл только при scope=P. Источник: `GET /v1/users`
dealCategoryId number нет Воронка сделок, только для сделок (entityTypeId=2). Источник: `GET /v1/categories/2`
categoryId number нет Воронка смарт-процесса, только для смарт-процессов. Источник: `GET /v1/categories/:entityTypeId`
leadCustomerType number нет Тип лида, только для лидов (entityTypeId=1): 1 — простой, 2 — повторный

Примеры

curl — личный ключ

Terminal 
curl -X PUT "https://vibecode.bitrix24.tech/v1/crm/card-config/3" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "C",
    "data": [
      {
        "name": "section_1",
        "title": "Личные данные",
        "type": "section",
        "elements": [
          { "name": "NAME", "optionFlags": 1 },
          { "name": "LAST_NAME", "optionFlags": 1 }
        ]
      }
    ]
  }'

curl — OAuth-приложение

Terminal 
curl -X PUT "https://vibecode.bitrix24.tech/v1/crm/card-config/3" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "C",
    "data": [
      {
        "name": "section_1",
        "title": "Личные данные",
        "type": "section",
        "elements": [
          { "name": "NAME", "optionFlags": 1 },
          { "name": "LAST_NAME", "optionFlags": 1 }
        ]
      }
    ]
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm/card-config/3', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    scope: 'C',
    data: [
      {
        name: 'section_1',
        title: 'Личные данные',
        type: 'section',
        elements: [
          { name: 'NAME', optionFlags: 1 },
          { name: 'LAST_NAME', optionFlags: 1 },
        ],
      },
    ],
  }),
})

const { success, data } = await res.json()
console.log('Раскладка обновлена:', data.updated)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm/card-config/3', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    scope: 'C',
    data: [
      {
        name: 'section_1',
        title: 'Личные данные',
        type: 'section',
        elements: [
          { name: 'NAME', optionFlags: 1 },
          { name: 'LAST_NAME', optionFlags: 1 },
        ],
      },
    ],
  }),
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Результат записи
data.entityTypeId number Тип объекта из пути
data.scope string Область, в которую записана раскладка: P или C
data.updated boolean Всегда true при успехе

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "entityTypeId": 3,
    "scope": "C",
    "updated": true
  }
}

Пример ответа при ошибке

400 — тело без data:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_DATA",
    "message": "data must be a non-empty array of section objects. Each section: { name, title, type: \"section\", elements: [...] }."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_ENTITY_TYPE_ID entityTypeId в пути не является положительным целым числом
400 INVALID_DATA data отсутствует, не является массивом или является пустым массивом
400 INVALID_SCOPE scope не равен P или C
400 INVALID_USER_ID userId не является положительным целым числом
400 INVALID_DEAL_CATEGORY_ID dealCategoryId не является положительным целым числом
400 INVALID_CATEGORY_ID categoryId не является положительным целым числом
400 INVALID_LEAD_CUSTOMER_TYPE leadCustomerType не равен 1 или 2
502 CRM_CARD_CONFIG_SET_FAILED Битрикс24 не подтвердил запись — например, недостаточно прав или целевая область недоступна
422 BITRIX_ERROR Битрикс24 отклонил тело — например, секция без name или title, элемент без name. Сообщение — в error.message
403 WRITE_BLOCKED_READONLY_KEY Ключ приложения в режиме «только чтение» — запись заблокирована
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Запись полностью заменяет раскладку области. PUT перезаписывает всю раскладку выбранной области целиком, а не отдельные секции. Чтобы изменить часть карточки, прочитайте текущую раскладку через `GET`, измените массив и запишите его обратно.

Флаг optionFlags в теле передаётся числом. При записи используется число (0 или 1). В ответе `GET` для сохранённой раскладки тот же флаг возвращается строкой.

Смотрите также