## Установить обязательность поля CRM

`PUT /v1/deals/fields/required`

Меняет обязательность поля CRM для всех пользователей портала, которые редактируют карточки и сохраняют записи.

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

Скоуп `crm`. Нужен ключ `READWRITE`.

## Параметры

Варианты пути:

`PUT /v1/deals/fields/required`

`PUT /v1/leads/fields/required`

`PUT /v1/contacts/fields/required`

`PUT /v1/companies/fields/required`

`PUT /v1/quotes/fields/required`

`PUT /v1/invoices/fields/required`

`PUT /v1/items/:entityTypeId/fields/required`

`entityTypeId` смарт-процесса — безопасное целое число от 128, из [списка смарт-процессов](/docs/entities/smart-processes/list). Для встроенных типов используйте именованные ресурсы.

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

| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| `fieldId` | string | да | Непустой исходный идентификатор поля CRM, например `comments` или `opportunity`. Правила имён приведены ниже. |
| `categoryId` | integer | да, кроме лидов и предложений | Неотрицательный ID из [воронок сделок](/docs/entities/deal-categories/list) или [воронок](/docs/entities/categories/list). Применимость проверяет Битрикс24. |
| `requiredStageIds` | string[] | нет | Без параметра — во всей воронке или глобально. Непустой список задаёт [стадии](/docs/entities/statuses/list). `[]` снимает настройку. |

Параметры передаются только плоским JSON-телом, без обёртки `fields` и без параметров строки запроса.

Для лидов и предложений `categoryId` не передаётся. Остальные типы требуют его. `0` задаёт основную воронку сделок, контактов и компаний. Для счетов и смарт-процессов нужен положительный ID существующей воронки. Эти правила проверяет Битрикс24.

Стандартные поля используют исходные имена CRM. Поле суммы называется `opportunity`, хотя API сущностей Вайбкод называет его `amount`. Псевдонимы V1 не преобразуются.

Для пользовательского поля берите исходное значение `UF_*` из `fieldName` в [пользовательских полях CRM](/docs/userfields/crm) или [полях смарт-процесса](/docs/userfields/smart-processes). Для счетов используется `/v1/userfields/invoices`. Псевдоним `ufCrm...` из словаря сущности здесь не используется. Идентификаторы не преобразуются.

## Примеры

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

```bash
curl -X PUT "https://vibecode.bitrix24.tech/v1/deals/fields/required" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fieldId": "comments", "categoryId": 0}'
```

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

```bash
curl -X PUT "https://vibecode.bitrix24.tech/v1/deals/fields/required" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fieldId": "comments", "categoryId": 0}'
```

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

```javascript
const response = await fetch('https://vibecode.bitrix24.tech/v1/deals/fields/required', {
  "method": "PUT",
  "headers": {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "body": "{\"fieldId\": \"comments\", \"categoryId\": 0}"
})
const result = await response.json()
console.log(result)
```

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

```javascript
const response = await fetch('https://vibecode.bitrix24.tech/v1/deals/fields/required', {
  "method": "PUT",
  "headers": {
    "X-Api-Key": "YOUR_APP_KEY",
    "Authorization": "Bearer USER_SESSION_TOKEN",
    "Content-Type": "application/json"
  },
  "body": "{\"fieldId\": \"comments\", \"categoryId\": 0}"
})
const result = await response.json()
console.log(result)
```

## Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `success` | boolean | `true` |
| `data.fieldId` | string | Идентификатор поля. |
| `data.categoryId` | integer или null | Воронка или `null` для глобальной настройки. |
| `data.mode` | string | `none` — нет настройки, `all` — целиком, `stages` — на выбранных стадиях. |
| `data.requiredStageIds` | string[] | Стадии обязательности. |
| `data.globallyRequired` | boolean | Поле глобально обязательно по правилам платформы. |

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

```json
{
  "success": true,
  "data": {
    "fieldId": "comments",
    "categoryId": 0,
    "mode": "all",
    "requiredStageIds": [],
    "globallyRequired": false
  }
}
```

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

400 — не указан идентификатор поля:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "fieldId must be a non-empty string"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|---|---|---|
| 400 | `INVALID_PARAMS` | Некорректная форма параметров или тела. |
| 400 | `INVALID_FIELDS` | Неизвестное поле тела. |
| 400 | `UNKNOWN_FILTER_FIELD` | Неизвестный или неверно расположенный параметр запроса. |
| 400 | `INVALID_ENTITY_TYPE` | Некорректный тип смарт-процесса. |
| 401 | `TOKEN_MISSING` | Нет портальных учётных данных. |
| 403 | `SCOPE_DENIED` | Нет скоупа `crm`. |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Запись ключом только для чтения. |
| 404 | Код Битрикс24 | Поле или контекст не найдены. |
| 409 | Код Битрикс24 | Конфликт конфигурации. |
| 422 | `METHOD_NOT_YET_AVAILABLE` | Возможность выключена или метод недоступен. В `error.release` указана линия выпуска. |
| 502 | `BITRIX_UNAVAILABLE` | Некорректная форма ответа Битрикс24. |

[Общие ошибки](/docs/errors).

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

Снятие настройки не отменяет глобальную обязательность системного поля, установленную Битрикс24. Неизвестные поля и недопустимые сочетания стадий и воронок отклоняет Битрикс24 с исходным кодом и текстом ошибки.

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

- [Обязательные поля CRM](/docs/entities/crm-required-fields)
