## Получить поле `GET /v1/items/:entityTypeId/userfields/:id` Возвращает полное описание одного пользовательского поля смарт-процесса по числовому идентификатору. ## Параметры | Параметр | Тип | Обяз. | Описание | |----------|-----|:-----:|---------| | `:entityTypeId` (path) | number | да | Идентификатор типа смарт-процесса. Источник: [`GET /v1/smart-processes`](/docs/entities/smart-processes) — поле `entityTypeId` в каждом элементе массива `data` | | `:id` (path) | number | да | Числовой идентификатор поля (из ответа [`GET /v1/items/:entityTypeId/userfields`](/docs/userfields/smart-processes/list) или [`POST /v1/items/:entityTypeId/userfields`](/docs/userfields/smart-processes/create)) | ## Примеры ### curl — личный ключ ```bash curl "https://vibecode.bitrix24.tech/v1/items/174/userfields/8210" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth-приложение ```bash 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` — внутренний последовательный идентификатор смарт-процесса (не совпадает с `entityTypeId` из пути) | | `data.fieldName` | string | Системное имя поля в формате `UF_CRM__<суффикс>` | | `data.userTypeId` | string | Тип поля. Список допустимых значений — [`GET /v1/items/:entityTypeId/userfields/types`](/docs/userfields/smart-processes/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 — [Ошибки](/docs/errors). ## Известные особенности **Несуществующее поле даёт `422`, а не `404`.** Если поля с указанным `id` нет (например, оно удалено), Битрикс24 отвечает `422 BITRIX_ERROR` с сообщением «Вы не можете просматривать настройки пользовательских полей» — отдельного `404` для поля не возвращается. `404 SMART_PROCESS_NOT_FOUND` относится только к несуществующему `entityTypeId`. ## Смотрите также - [Список полей смарт-процесса](/docs/userfields/smart-processes/list) - [Каталог типов полей](/docs/userfields/smart-processes/types) - [Создать поле](/docs/userfields/smart-processes/create) - [Обновить поле](/docs/userfields/smart-processes/update) - [Поля смарт-процессов](/docs/userfields/smart-processes) - [Пользовательские поля](/docs/userfields)