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

GET /v1/userfields/:entity/:id

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

#Параметры

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

#Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/userfields/deals/7115" \
  -H "X-Api-Key: YOUR_API_KEY"

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

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

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

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/userfields/deals/7115',
  {
    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/userfields/deals/7115',
  {
    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_DEAL, CRM_LEAD, CRM_CONTACT, CRM_COMPANY, CRM_QUOTE, CRM_REQUISITE
data.fieldName string Системное имя поля в формате UF_CRM_*
data.userTypeId string Тип поля. Список допустимых значений — `GET /v1/userfields/:entity/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. Для string — SIZE, ROWS, REGEXP, MIN_LENGTH, MAX_LENGTH, DEFAULT_VALUE. Для других типов состав отличается
data.list array Варианты для поля типа enumeration. Для остальных типов поле отсутствует. Каждый элемент содержит ID, SORT, VALUE, DEF, XML_ID
data.editFormLabel object Подпись поля в форме редактирования — объект с ключами по языкам портала
data.listColumnLabel object Заголовок столбца в списке записей — объект с ключами по языкам портала
data.listFilterLabel object Подпись поля в фильтре — объект с ключами по языкам портала
data.errorMessage object Сообщение об ошибке валидации — объект с ключами по языкам портала
data.helpMessage object Подсказка под полем в форме — объект с ключами по языкам портала

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

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

JSON 
{
  "success": true,
  "data": {
    "id": 7115,
    "entityId": "CRM_DEAL",
    "fieldName": "UF_CRM_VIBE_DOC_1779951810",
    "userTypeId": "string",
    "xmlId": null,
    "sort": "100",
    "multiple": "N",
    "mandatory": "N",
    "showFilter": "N",
    "showInList": "Y",
    "editInList": "Y",
    "isSearchable": "N",
    "settings": {
      "SIZE": 20,
      "ROWS": 1,
      "REGEXP": "",
      "MIN_LENGTH": 0,
      "MAX_LENGTH": 0,
      "DEFAULT_VALUE": ""
    },
    "editFormLabel": {
      "ru": "Документационное поле",
      "en": "Документационное поле",
      "ua": "Документационное поле"
    },
    "listColumnLabel": {
      "ru": "Документационное поле",
      "en": "Документационное поле",
      "ua": "Документационное поле"
    },
    "listFilterLabel": {
      "ru": "Документационное поле",
      "en": "Документационное поле",
      "ua": "Документационное поле"
    },
    "errorMessage": {
      "ru": "Документационное поле",
      "en": "Документационное поле",
      "ua": "Документационное поле"
    },
    "helpMessage": {
      "ru": "Документационное поле",
      "en": "Документационное поле",
      "ua": "Документационное поле"
    }
  }
}

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

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

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

#Ошибки

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

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

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

Языковые объекты. Поля editFormLabel, listColumnLabel, listFilterLabel, errorMessage, helpMessage приходят как объекты со значениями по языкам портала Битрикс24 (ru, en, ua, de, fr и другие). Значение устанавливается при создании или обновлении поля через параметр label. Если передать только строку ("label": "Мой заголовок"), Битрикс24 автоматически распространяет её на все доступные языки.

Поле settings. Структура объекта settings зависит от значения userTypeId. Наборы ключей для распространённых типов:

  • string — SIZE, ROWS, REGEXP, MIN_LENGTH, MAX_LENGTH, DEFAULT_VALUE
  • enumeration — DISPLAY, LIST_HEIGHT, CAPTION_NO_VALUE, SHOW_NO_VALUE
  • datetime — DEFAULT_VALUE, USE_SECOND, USE_TIMEZONE

Для других типов — свой набор ключей.

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