Раскладка карточки CRM

Управление раскладкой полей в карточках CRM-сущностей: лиды, сделки, контакты, компании, смарт-процессы. Позволяет прочитать текущую конфигурацию секций и полей, перезаписать её, сбросить к настройкам по умолчанию или принудительно применить общую раскладку ко всем сотрудникам. У раскладки нет отдельного числового id: она адресуется набором значений — тип объекта entityTypeId, область scope, сотрудник userId и уточнения extras.

Битрикс24 API: crm.item.details.configuration.* Скоуп: crm

Получить раскладку карточки

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

Возвращает текущую раскладку секций и полей карточки для указанного типа CRM-объекта и области. Отдаёт массив секций либо null, если явной конфигурации ещё не было.

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

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

Параметры запроса

Параметр Тип Описание
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 "https://vibecode.bitrix24.tech/v1/crm/card-config/2?scope=C&dealCategoryId=9" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/crm/card-config/2?scope=C&dealCategoryId=9" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm/card-config/2?scope=C&dealCategoryId=9', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data } = await res.json()
if (data === null) {
  console.log('Явной раскладки нет — используется раскладка по умолчанию')
} else {
  console.log('Секций в раскладке:', data.length)
}

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm/card-config/2?scope=C&dealCategoryId=9', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array | null Массив секций раскладки. null — явной конфигурации ещё не было
data[].name string Внутреннее имя секции
data[].title string Отображаемое название секции
data[].type string Всегда section
data[].elements array Поля секции в порядке отображения
data[].elements[].name string Имя поля CRM в формате Битрикс24
data[].elements[].optionFlags string Флаг поля: "0" — обычное, "1" — поле клиента
data[].elements[].options object Параметры конкретного поля, если заданы

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

Раскладка задана явно:

JSON 
{
  "success": true,
  "data": [
    {
      "name": "main",
      "title": "О сделке",
      "type": "section",
      "elements": [
        { "name": "TITLE", "optionFlags": "0" },
        { "name": "STAGE_ID", "optionFlags": "0" },
        { "name": "OPPORTUNITY_WITH_CURRENCY", "optionFlags": "0" }
      ]
    }
  ]
}

Явной конфигурации для области ещё не было:

JSON 
{
  "success": true,
  "data": null
}

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

400 — недопустимое значение scope:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_SCOPE",
    "message": "scope must be \"P\" (personal) or \"C\" (common)."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_ENTITY_TYPE_ID entityTypeId в пути не является положительным целым числом
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
422 BITRIX_ERROR Битрикс24 не распознал тип объекта — например, для несуществующего entityTypeId. Сообщение — в error.message
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

data: null отличается от пустой раскладки. null означает, что для указанной области ещё не было явной конфигурации, и карточка рисуется встроенной раскладкой по умолчанию. Пустой массив [] означает явно сохранённую пустую раскладку. Ветку data === null в коде стоит обрабатывать отдельно.

В ответе optionFlags приходит строкой. Для ранее сохранённых раскладок значение флага возвращается как строка "0" или "1". При записи через `PUT` флаг передаётся числом.

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