Обязательные поля 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

GET /v1/deals/fields/required

Читает настройку обязательности одного поля CRM в выбранной воронке.

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

Скоуп crm. Подходит ключ READONLY.

Параметры

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

GET /v1/deals/fields/required

GET /v1/leads/fields/required

GET /v1/contacts/fields/required

GET /v1/companies/fields/required

GET /v1/quotes/fields/required

GET /v1/invoices/fields/required

GET /v1/items/:entityTypeId/fields/required

entityTypeId смарт-процесса — безопасное целое число от 128, из списка смарт-процессов. Для встроенных типов используйте именованные ресурсы.

Параметры передаются в строке запроса. Тело и заголовок Content-Type не отправляются.

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

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

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

Примеры

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

curl -X GET "https://vibecode.bitrix24.tech/v1/deals/fields/required?fieldId=comments&categoryId=0" \
  -H "X-Api-Key: YOUR_API_KEY"

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

curl -X GET "https://vibecode.bitrix24.tech/v1/deals/fields/required?fieldId=comments&categoryId=0" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

const response = await fetch('https://vibecode.bitrix24.tech/v1/deals/fields/required?fieldId=comments&categoryId=0', {
  "method": "GET",
  "headers": {
    "X-Api-Key": "YOUR_API_KEY"
  }
})
const result = await response.json()
console.log(result)

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

const response = await fetch('https://vibecode.bitrix24.tech/v1/deals/fields/required?fieldId=comments&categoryId=0', {
  "method": "GET",
  "headers": {
    "X-Api-Key": "YOUR_APP_KEY",
    "Authorization": "Bearer USER_SESSION_TOKEN"
  }
})
const result = await response.json()
console.log(result)

Поля ответа

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

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

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

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

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

Ошибки

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

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

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

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

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