Для AI-агентов: markdown этой страницы — /docs-content/userfields/smart-processes/get.md индекс документации — /llms.txt

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

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_ + entityId + _<суффикс>. У обычного смарт-процесса UF_CRM_<typeId>_<суффикс>, у смарт-счёта UF_CRM_SMART_INVOICE_<суффикс>
Поле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 Код Описание
HTTP400 КодINVALID_ENTITY_TYPE_ID Описание:entityTypeId не является положительным целым числом
HTTP400 КодINVALID_PARAMS Описание:id не является положительным целым числом либо превышает 9007199254740991. Значение записывается только цифрами — без ведущего нуля, знака, дробной части, экспоненты и пробелов. Сообщение: id must be a positive integer. Запрос к Битрикс24 не выполняется
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеУ ключа нет скоупа userfieldconfig — перевыпустите ключ с этим скоупом
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа crm
HTTP404 КодSMART_PROCESS_NOT_FOUND ОписаниеСмарт-процесс с указанным entityTypeId не найден на портале
HTTP404 КодNOT_FOUND ОписаниеУ смарт-процесса из пути нет поля с указанным id: поле удалено или принадлежит другой сущности
HTTP422 КодBITRIX_ERROR ОписаниеПоле удалили между проверкой и чтением — Битрикс24 отвечает «Вы не можете просматривать настройки пользовательских полей»
HTTP401 КодMISSING_API_KEY ОписаниеОтсутствует заголовок X-Api-Key
HTTP401 КодTOKEN_MISSING ОписаниеAPI-ключ не имеет настроенных токенов

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

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

Поле ищется только у смарт-процесса из пути. Идентификатор поля общий для всех сущностей портала, поэтому перед чтением платформа проверяет, что поле с этим id есть у смарт-процесса :entityTypeId. Поле другой сущности и удалённое поле дают одинаковый ответ 404 NOT_FOUND. 404 SMART_PROCESS_NOT_FOUND относится к несуществующему entityTypeId.

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