#Получить поле

GET /v1/items/:entityTypeId/userfields/:id

Возвращает полное описание одного пользовательского поля смарт-процесса по числовому идентификатору.

#Параметры

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

#Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/items/174/userfields/8210" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/items/174/userfields/8210" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/items/174/userfields/8210',
  {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { success, data } = await res.json()
console.log(data.fieldName, data.userTypeId)

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

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/items/174/userfields/8210',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { success, data } = await res.json()

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Объект поля
data.id number Числовой идентификатор поля
data.entityId string Внутренний идентификатор вида CRM_<typeId>, где typeId — внутренний последовательный идентификатор смарт-процесса (не совпадает с entityTypeId из пути)
data.fieldName string Системное имя поля в формате UF_CRM_<typeId>_<суффикс>
data.userTypeId string Тип поля. Список допустимых значений — `GET /v1/items/:entityTypeId/userfields/types`
data.xmlId string|null Внешний идентификатор для интеграций. Задаётся вручную при создании
data.sort string Порядок сортировки в интерфейсе Битрикс24
data.multiple string Множественное поле: "Y" или "N"
data.mandatory string Обязательное при заполнении: "Y" или "N"
data.showFilter string Отображать в фильтре: "N" — нет, "I" — точное значение, "E" — маска, "S" — диапазон
data.showInList string Показывать в списке записей: "Y" или "N"
data.editInList string Разрешить редактирование прямо из списка: "Y" или "N"
data.isSearchable string Участвует ли в полнотекстовом поиске: "Y" или "N"
data.settings object Настройки поля, специфичные для userTypeId. Состав ключей зависит от типа
data.languageId object Языки портала: ключ и значение — код языка ({ "ru": "ru", … })
data.editFormLabel object Подпись поля в форме редактирования. Объект по языкам портала: значение в нужной локали, остальные — ""
data.listColumnLabel object Заголовок столбца в списке записей. Объект по языкам; если не задан — значения null
data.listFilterLabel object Подпись поля в фильтре. Объект по языкам; если не задан — значения null
data.errorMessage object Сообщение об ошибке валидации. Объект по языкам; если не задан — значения null
data.helpMessage object Подсказка под полем в форме. Объект по языкам; если не задан — значения null
data.enum array Только для типа enumeration: варианты значений. Каждый элемент содержит id, userFieldId, value, def, sort, xmlId

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

Языковые объекты (languageId, editFormLabel, listColumnLabel, listFilterLabel, errorMessage, helpMessage) приходят на все языки портала. В примере оставлен ru и … вместо остальных.

JSON 
{
  "success": true,
  "data": {
    "id": 3351,
    "entityId": "CRM_3",
    "fieldName": "UF_CRM_3_1628508893",
    "userTypeId": "string",
    "xmlId": null,
    "sort": "100",
    "multiple": "N",
    "mandatory": "N",
    "showFilter": "E",
    "showInList": "Y",
    "editInList": "Y",
    "isSearchable": "Y",
    "settings": {
      "SIZE": 20,
      "ROWS": 1,
      "REGEXP": "",
      "MIN_LENGTH": 0,
      "MAX_LENGTH": 0,
      "DEFAULT_VALUE": ""
    },
    "languageId": { "ru": "ru", "…": "…" },
    "editFormLabel": { "ru": "Строка1", "…": "" },
    "listColumnLabel": { "ru": null, "…": null },
    "listFilterLabel": { "ru": null, "…": null },
    "errorMessage": { "ru": null, "…": null },
    "helpMessage": { "ru": null, "…": null }
  }
}

Для поля типа enumeration в ответе дополнительно приходит массив enum с вариантами:

JSON 
"enum": [
  { "id": "1347", "userFieldId": "3929", "value": "1", "def": "N", "sort": "100", "xmlId": "a84972a4857b64f963b165785b3c20d0" }
]

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

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_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 отвечает «Вы не можете просматривать настройки пользовательских полей»
401 MISSING_API_KEY Отсутствует заголовок X-Api-Key
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

Несуществующее поле даёт 422, а не 404. Если поля с указанным id нет (например, оно удалено), Битрикс24 отвечает 422 BITRIX_ERROR с сообщением «Вы не можете просматривать настройки пользовательских полей» — отдельного 404 для поля не возвращается. 404 SMART_PROCESS_NOT_FOUND относится только к несуществующему entityTypeId.

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