# Обязательные поля CRM

Чтение, установка и снятие обязательности одного поля CRM. Запись меняет карточки и сохранение записей для **всех пользователей портала**.

Битрикс24 API: `crm.<entity>.field.required.{get,set,clear}`
Скоуп: `crm`

> **Метод в процессе раскатки — выходит в обновлении `crm 26.2000.0`.** Доступен не на всех порталах. Если возможность выключена или у портала нет метода, API вернёт `422 METHOD_NOT_YET_AVAILABLE` с `error.release`. Сам номер выпуска не гарантирует доступность.

## Операции

- [Прочитать обязательность](./crm-required-fields/get.md) — `GET /v1/deals/fields/required`
- [Установить обязательность](./crm-required-fields/set.md) — `PUT /v1/deals/fields/required`
- [Снять обязательность](./crm-required-fields/clear.md) — `DELETE /v1/deals/fields/required`

## Ресурсы

Для следующих ресурсов используется один суффикс `/fields/required`:

- `/v1/deals/fields/required`
- `/v1/leads/fields/required`
- `/v1/contacts/fields/required`
- `/v1/companies/fields/required`
- `/v1/quotes/fields/required`
- `/v1/invoices/fields/required`
- `/v1/items/:entityTypeId/fields/required`

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

| Поле | Описание |
|---|---|
| `fieldId` | Исходный идентификатор поля CRM, например `comments` или `opportunity`. Список полей: [словарь сущности](/docs/entities/deals/fields). |
| `categoryId` | Идентификатор воронки: [воронки сделок](/docs/entities/deal-categories/list) или [воронки](/docs/entities/categories/list). |
| `requiredStageIds` | Идентификаторы стадий: [статусы](/docs/entities/statuses/list). Без `requiredStageIds` поле становится обязательным во всей воронке или глобально для сущности без стадий. Непустой список задаёт стадии. `[]` снимает настройку. |
| `entityTypeId` | Тип смарт-процесса в пути `/v1/items/:entityTypeId/fields/required`, из [GET /v1/smart-processes](/docs/entities/smart-processes/list). Встроенные типы используют именованные ресурсы из раздела «Ресурсы». |
| `mode` | Поле ответа: `none` — нет настройки, `all` — целиком, `stages` — на выбранных стадиях. |
| `globallyRequired` | Поле ответа: поле глобально обязательно по правилам платформы. |

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

1. Чтение доступно ключу `READONLY`. Для изменения нужен `READWRITE`. Поле, воронку, стадии и права проверяет Битрикс24.
2. Стандартные поля используют исходные имена CRM. Поле суммы называется `opportunity`, хотя API сущностей Вайбкод называет его `amount`. Псевдонимы V1 не преобразуются.
3. Для пользовательского поля берите исходное значение `UF_*` из `fieldName` в [пользовательских полях CRM](/docs/userfields/crm) или [полях смарт-процесса](/docs/userfields/smart-processes). Для счетов используется `/v1/userfields/invoices`. Псевдоним `ufCrm...` из словаря сущности здесь не используется. Идентификаторы не преобразуются.
4. После снятия настройки системное поле может оставаться глобально обязательным.

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

1. Возьмите исходное имя поля: стандартное — из [словаря сущности](/docs/entities/deals/fields), пользовательское — `UF_*` из [пользовательских полей CRM](/docs/userfields/crm).
2. Прочитайте текущую настройку: [`GET /v1/deals/fields/required`](./crm-required-fields/get.md).
3. Установите обязательность: [`PUT /v1/deals/fields/required`](./crm-required-fields/set.md). Чтобы поле было обязательным не во всей воронке, передайте `requiredStageIds`.
4. Снимите настройку, когда она больше не нужна: [`DELETE /v1/deals/fields/required`](./crm-required-fields/clear.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Полей за вызов | Одно — `fieldId` |
| Передача параметров | Чтение и снятие — в строке запроса. Установка — плоским JSON-телом без обёртки `fields` |
| Частота запросов | общая для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Поля CRM-сущностей](/docs/userfields/crm)
- [Поля смарт-процессов](/docs/userfields/smart-processes)
- [Ошибки](/docs/errors)