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

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

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

## Операции

- [Получить раскладку](./crm-card-config/get.md) — `GET /v1/crm/card-config/:entityTypeId`
- [Установить раскладку](./crm-card-config/set.md) — `PUT /v1/crm/card-config/:entityTypeId`
- [Сбросить раскладку](./crm-card-config/reset.md) — `DELETE /v1/crm/card-config/:entityTypeId`
- [Общая раскладка для всех](./crm-card-config/force-common.md) — `POST /v1/crm/card-config/:entityTypeId/force-common`

## Ключевые поля

| Поле | Описание |
|------|---------|
| `entityTypeId` | Тип CRM-объекта в пути:<br>`1` — лид<br>`2` — сделка<br>`3` — контакт<br>`4` — компания<br>`7` — предложение<br>`31` — счёт<br>смарт-процесс — числовой ID типа из [`GET /v1/smart-processes`](/docs/entities/smart-processes), поле `entityTypeId` |
| `scope` | Область раскладки: `P` — личная (по умолчанию), `C` — общая |
| `userId` | Сотрудник, чья личная раскладка читается или записывается. По умолчанию — владелец API-ключа. Имеет смысл только при `scope=P` |
| `dealCategoryId` | Воронка сделок, только для сделок (`entityTypeId=2`). Источник: [`GET /v1/categories/2`](/docs/entities/categories) |
| `categoryId` | Воронка смарт-процесса, только для смарт-процессов. Источник: [`GET /v1/categories/:entityTypeId`](/docs/entities/categories) |
| `leadCustomerType` | Тип лида, только для лидов (`entityTypeId=1`): `1` — простой, `2` — повторный |

Значения `dealCategoryId`, `categoryId` и `leadCustomerType` можно передать на верхнем уровне запроса или внутри объекта `extras`. Оба варианта дают одинаковый результат.

## Структура раскладки

Тело `PUT` содержит массив секций `data`. Каждая секция описывает блок карточки и его поля.

```json
{
  "name": "section_1",
  "title": "Личные данные",
  "type": "section",
  "elements": [
    { "name": "NAME", "optionFlags": 1 },
    { "name": "LAST_NAME", "optionFlags": 1 },
    { "name": "PHONE", "optionFlags": 1, "options": { "defaultCountry": "GB" } }
  ]
}
```

| Поле секции | Описание |
|------|---------|
| `name` | Внутреннее имя секции |
| `title` | Отображаемое название секции |
| `type` | Всегда `section` |
| `elements` | Массив полей в порядке отображения |
| `elements[].name` | Имя поля CRM в формате Битрикс24: `TITLE`, `NAME`, `PHONE`, `UF_CRM_1234567890` для пользовательских полей. Источник для пользовательских полей: [`GET /v1/userfields/:entity`](/docs/userfields) |
| `elements[].optionFlags` | Флаг поля: `0` — обычное, `1` — поле клиента |
| `elements[].options` | Параметры конкретного поля, например `defaultCountry` для `PHONE` или `defaultAddressType` для `ADDRESS` |

## Что нужно знать перед работой

1. **`scope` регистрозависим.** Допустимы только `P` (личная) и `C` (общая). Любое другое значение возвращает `400 INVALID_SCOPE`, а не откат к значению по умолчанию.
2. **`userId` имеет смысл только при `scope=P`.** Для общей раскладки (`scope=C`) сервер его принимает, но не использует.
3. **`data: null` в ответе — это не пустая раскладка.** `null` означает, что для указанной области ещё не было явной конфигурации, и Битрикс24 показывает встроенную раскладку по умолчанию. Пустой массив `[]` означает явно сохранённую пустую раскладку.
4. **Имена полей в `elements[].name` — в формате Битрикс24, UPPER_SNAKE_CASE.** Например `TITLE`, `STAGE_ID`, `OPPORTUNITY_WITH_CURRENCY`, `UF_CRM_1234567890`.
5. **`force-common` не принимает `scope` и `userId`.** Метод удаляет личные раскладки всех сотрудников и оставляет общую.

## Типичный сценарий

Единая настройка карточки контакта под партнёрскую программу и применение её ко всем сотрудникам.

1. Добавить пользовательские поля: [`POST /v1/userfields/contacts`](/docs/userfields).
2. Прочитать текущую общую раскладку: [`GET /v1/crm/card-config/3?scope=C`](./crm-card-config/get.md).
3. Записать новую общую раскладку с секцией «Партнёрка» и нужными полями: [`PUT /v1/crm/card-config/3`](./crm-card-config/set.md) со `scope: "C"`.
4. Сбросить личные раскладки сотрудников, чтобы все увидели единый макет: [`POST /v1/crm/card-config/3/force-common`](./crm-card-config/force-common.md).

## Лимиты

Раскладка хранится по одной на область: `scope` плюс `userId` для личной и `extras` для воронки или типа лида. Пагинации нет — `GET` возвращает всю раскладку одной выборкой. Общий лимит частоты запросов к API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization).

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

- [Смарт-процессы](/docs/entities/smart-processes)
- [Воронки](/docs/entities/categories)
- [Пользовательские поля](/docs/userfields)
- [Сделки](/docs/entities/deals)
- [Контакты](/docs/entities/contacts)
- [Справочник API](/docs/api-reference)