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

PATCH /v1/userfields/:entity/:id

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

#Параметры

Параметр Тип Обяз. Описание
:entity (path) string да Сущность: deals, leads, contacts, companies, quotes, requisites
:id (path) number да Числовой идентификатор поля (из ответа `GET /v1/userfields/:entity` или `POST /v1/userfields/:entity`)

#Поля запроса (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
list array Варианты для поля типа enumeration. Передавайте все варианты, которые должны остаться, с их ID, плюс новые без ID. Элемент без ID создаётся заново; элемент с ID, не переданный в массиве, удаляется

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

#Примеры

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

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/userfields/deals/7115" \
  -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/userfields/deals/7115" \
  -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/userfields/deals/7115', {
  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/userfields/deals/7115', {
  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
  }
}

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

404 — поле не существует:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "The entity with ID '9999999' is not found."
  }
}

#Ошибки

HTTP Код Описание
400 INVALID_REQUEST Тело запроса не является объектом
400 UNKNOWN_ENTITY :entity не входит в список поддерживаемых сущностей
404 ENTITY_NOT_FOUND Поля с таким id нет
422 BITRIX_ERROR Ошибки Битрикс24: некорректные значения полей, несовместимые настройки settings
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
401 MISSING_API_KEY Отсутствует заголовок X-Api-Key

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

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

Обновление вариантов enumeration. При передаче поля list для типа enumeration необходимо включить все варианты, которые должны остаться в поле. Существующие варианты передаются с их ID из ответа `GET /v1/userfields/:entity/:id` — иначе они будут удалены. Новые варианты передаются без ID.

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