Для AI-агентов: markdown этой страницы — /docs-content/entities/crm-card-layouts/add.md индекс документации — /llms.txt

Создать раскладку карточки CRM

POST /v1/crm/card-layouts/:entityType

Создаёт именованный набор разделов и полей карточки CRM для выбранной аудитории.

Методы в процессе раскатки — появились в обновлении crm 26.1700.0. Облачная доступность зависит от включения возможности Битрикс24. Пока она не открыта для портала, API отвечает 422 METHOD_NOT_YET_AVAILABLE с error.release.

Нужен скоуп crm. Запись требует READWRITE.

Параметры

Параметр Тип Обяз. По умолч. Описание
ПараметрentityType (path) Типstring Обяз.да По умолч.— ОписаниеТип из индекса раздела.

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

Поле Тип Обяз. Описание
ПолеcategoryId Типinteger Обяз.да ОписаниеКатегория из GET /v1/categories, 0 допустим.
Полеfields Типobject Обяз.да ОписаниеИзменяемые поля.
Полеfields.name Типstring Обяз.да ОписаниеНазвание раскладки.
Полеfields.configuration Типobject[] Обяз.да ОписаниеРазделы {name,title,elements}. Элементы {name,optionFlags?,options?}, options — объект.
Полеfields.audience Типobject[] Обяз.да ОписаниеАудитория {type,id}. Типы и права проверяет Битрикс24. ID сотрудника — из пользователей.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/crm/card-layouts/deal" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"categoryId": 0, "fields": {"name": "VIBE-PROBE", "configuration": [{"name": "main", "title": "VIBE-PROBE", "elements": [{"name": "TITLE"}]}], "audience": [{"type": "user", "id": 1}]}}'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/crm/card-layouts/deal" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"categoryId": 0, "fields": {"name": "VIBE-PROBE", "configuration": [{"name": "main", "title": "VIBE-PROBE", "elements": [{"name": "TITLE"}]}], "audience": [{"type": "user", "id": 1}]}}'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm/card-layouts/deal', {
  method: 'POST',
  headers: {"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({"categoryId": 0, "fields": {"name": "VIBE-PROBE", "configuration": [{"name": "main", "title": "VIBE-PROBE", "elements": [{"name": "TITLE"}]}], "audience": [{"type": "user", "id": 1}]}}),
});
console.log(await res.json());

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm/card-layouts/deal', {
  method: 'POST',
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({"categoryId": 0, "fields": {"name": "VIBE-PROBE", "configuration": [{"name": "main", "title": "VIBE-PROBE", "elements": [{"name": "TITLE"}]}], "audience": [{"type": "user", "id": 1}]}}),
});
console.log(await res.json());

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue
Полеdata.id Типnumber ОписаниеЧисловой ID созданной раскладки.

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

JSON 
{
  "success": true,
  "data": {
    "id": 11
  }
}

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

400 — не передана категория:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "categoryId is required"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодMISSING_REQUIRED_FIELDS ОписаниеНет категории или обязательных полей тела.
HTTP400 КодINVALID_PARAMS ОписаниеНеподдерживаемый тип сущности или некорректная форма параметров.
HTTP400 КодUNKNOWN_FILTER_FIELD ОписаниеНеизвестный параметр запроса.
HTTP401 КодMISSING_API_KEY ОписаниеНе передан ключ.
HTTP401 КодTOKEN_MISSING ОписаниеНет учётных данных портала.
HTTP403 КодSCOPE_DENIED ОписаниеНет скоупа crm.
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч запрещает запись на портал.
HTTP422 КодMETHOD_NOT_YET_AVAILABLE ОписаниеВозможность не включена или метода ещё нет. error.release указывает выпуск.
HTTP422 КодBITRIX_ERROR ОписаниеОтказ Битрикс24. Исходный код в error.b24Code, текст в error.message.
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеНет корректного ответа портала. После ошибки записи перечитайте раскладку перед повтором.

Общие ошибки — Ошибки.

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

Переданные массивы заменяются целиком. Пустой массив может быть отклонён Битрикс24 как отсутствующее поле, исходный отказ передаётся в ответе.

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