Для AI-агентов: markdown этой страницы — /docs-content/entities/crm-required-fields/set.md индекс документации — /llms.txt
Установить обязательность поля 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, из списка смарт-процессов. Для встроенных типов используйте именованные ресурсы.
Поля запроса (body)
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
ПолеfieldId |
Типstring | Обяз.да | ОписаниеНепустой исходный идентификатор поля CRM, например comments или opportunity. Правила имён приведены ниже. |
ПолеcategoryId |
Типinteger | Обяз.да, кроме лидов и предложений | ОписаниеНеотрицательный ID из воронок сделок или воронок. Применимость проверяет Битрикс24. |
ПолеrequiredStageIds |
Типstring[] | Обяз.нет | ОписаниеБез параметра — во всей воронке или глобально. Непустой список задаёт стадии. [] снимает настройку. |
Параметры передаются только плоским JSON-телом, без обёртки fields и без параметров строки запроса.
Для лидов и предложений categoryId не передаётся. Остальные типы требуют его. 0 задаёт основную воронку сделок, контактов и компаний. Для счетов и смарт-процессов нужен положительный ID существующей воронки. Эти правила проверяет Битрикс24.
Стандартные поля используют исходные имена CRM. Поле суммы называется opportunity, хотя API сущностей Вайбкод называет его amount. Псевдонимы V1 не преобразуются.
Для пользовательского поля берите исходное значение UF_* из fieldName в пользовательских полях CRM или полях смарт-процесса. Для счетов используется /v1/userfields/invoices. Псевдоним ufCrm... из словаря сущности здесь не используется. Идентификаторы не преобразуются.
Примеры
curl — личный ключ
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-приложение
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 — личный ключ
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-приложение
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 | ОписаниеПоле глобально обязательно по правилам платформы. |
Пример ответа
{
"success": true,
"data": {
"fieldId": "comments",
"categoryId": 0,
"mode": "all",
"requiredStageIds": [],
"globallyRequired": false
}
}
Пример ответа при ошибке
400 — не указан идентификатор поля:
{
"success": false,
"error": {
"code": "INVALID_PARAMS",
"message": "fieldId must be a non-empty string"
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодINVALID_PARAMS |
ОписаниеНекорректная форма параметров или тела. |
| HTTP400 | КодINVALID_FIELDS |
ОписаниеНеизвестное поле тела. |
| HTTP400 | КодUNKNOWN_FILTER_FIELD |
ОписаниеНеизвестный или неверно расположенный параметр запроса. |
| HTTP400 | КодINVALID_ENTITY_TYPE |
ОписаниеНекорректный тип смарт-процесса. |
| HTTP401 | КодTOKEN_MISSING |
ОписаниеНет портальных учётных данных. |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеНет скоупа crm. |
| HTTP403 | КодWRITE_BLOCKED_READONLY_KEY |
ОписаниеЗапись ключом только для чтения. |
| HTTP404 | КодКод Битрикс24 | ОписаниеПоле или контекст не найдены. |
| HTTP409 | КодКод Битрикс24 | ОписаниеКонфликт конфигурации. |
| HTTP422 | КодMETHOD_NOT_YET_AVAILABLE |
ОписаниеВозможность выключена или метод недоступен. В error.release указана линия выпуска. |
| HTTP502 | КодBITRIX_UNAVAILABLE |
ОписаниеНекорректная форма ответа Битрикс24. |
Известные особенности
Снятие настройки не отменяет глобальную обязательность системного поля, установленную Битрикс24. Неизвестные поля и недопустимые сочетания стадий и воронок отклоняет Битрикс24 с исходным кодом и текстом ошибки.