#Обновить поле

PATCH /v1/items/:entityTypeId/userfields/:id

Обновляет свойства существующего пользовательского поля смарт-процесса. Тип поля (userTypeId) изменить нельзя — для смены типа удалите поле и создайте новое. Передавайте только те поля, которые хотите изменить.

#Параметры

Параметр Тип Обяз. Описание
:entityTypeId (path) number да Идентификатор типа смарт-процесса. Источник: `GET /v1/smart-processes` — поле entityTypeId в каждом элементе массива data
:id (path) number да Числовой идентификатор поля (из ответа `GET /v1/items/:entityTypeId/userfields` или `POST /v1/items/:entityTypeId/userfields`)

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

Поля те же, что и при создании. Передавайте только те, которые хотите изменить.

Поле Тип Описание
label string Подпись поля для отображения. Значение автоматически распространяется на все языки портала
editFormLabel object Подпись в форме редактирования по языкам. Пример: { "ru": "Проект", "en": "Project" }
sort string Порядок сортировки в интерфейсе Битрикс24
multiple string Разрешить несколько значений: "Y" или "N"
mandatory string Обязательное при заполнении: "Y" или "N"
showFilter string Отображать в фильтре: "N" — нет, "I" — точное значение, "E" — маска, "S" — диапазон
showInList string Показывать в списке записей: "Y" или "N"
editInList string Разрешить редактирование прямо из списка: "Y" или "N"
isSearchable string Участвует в полнотекстовом поиске: "Y" или "N"
xmlId string Внешний идентификатор для интеграций
settings object Настройки поля, специфичные для типа. Структура зависит от userTypeId
enum array Варианты для поля типа enumeration. Передавайте все варианты, которые должны остаться, с их id, плюс новые без id. Элемент без id создаётся заново; элемент с id, не переданный в массиве, удаляется

Read-only поля (id, entityId, fieldName, userTypeId) игнорируются при передаче.

#Примеры

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/items/174/userfields/8210" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mandatory": "Y",
    "showFilter": "I"
  }'

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/items/174/userfields/8210" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mandatory": "Y",
    "showFilter": "I"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/items/174/userfields/8210', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    mandatory: 'Y',
    showFilter: 'I',
  }),
})

const { success, data } = await res.json()
console.log('Обновлено:', data.updated)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/items/174/userfields/8210', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    mandatory: 'Y',
    showFilter: 'I',
  }),
})

const { success, data } = await res.json()

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.updated boolean true при успешном обновлении

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

JSON 
{
  "success": true,
  "data": {
    "updated": true
  }
}

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

403 — у ключа нет скоупа userfieldconfig:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "The request requires higher privileges than provided by the webhook token"
  }
}

#Ошибки

HTTP Код Описание
400 INVALID_REQUEST Тело запроса не является объектом
400 INVALID_ENTITY_TYPE_ID :entityTypeId не является положительным целым числом
403 BITRIX_ACCESS_DENIED У ключа нет скоупа userfieldconfig — перевыпустите ключ с этим скоупом
403 SCOPE_DENIED API-ключ не имеет скоупа crm
404 SMART_PROCESS_NOT_FOUND Смарт-процесс с указанным entityTypeId не найден на портале
422 BITRIX_ERROR Поля с указанным id нет — Битрикс24 отвечает «Вы не можете изменить настройки пользовательского поля»
422 BITRIX_ERROR Некорректные значения полей или несовместимые настройки settings
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
401 MISSING_API_KEY Отсутствует заголовок X-Api-Key

Полный список общих ошибок API — Ошибки.

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

Обновление вариантов enumeration. Варианты передаются массивом enum (не list). Чтобы сохранить существующий вариант, передайте его с полем id из ответа `GET /v1/items/:entityTypeId/userfields/:id` — вариант без id создаётся как новый, а пропущенный в массиве удаляется.

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