## Получить поле сотрудника

`GET /v1/userfields/users/:id`

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

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `:id` (path) | number | да | Числовой идентификатор поля (из ответа [`GET /v1/userfields/users`](/docs/userfields/users/list) или [`POST /v1/userfields/users`](/docs/userfields/users/create)). Ведущие нули игнорируются — `007` читается как `7` |

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/userfields/users/6007923" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/userfields/users/6007923" \
  -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/users/6007923',
  {
    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/users/6007923',
  {
    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 | Внутренний идентификатор сущности — всегда `USER` |
| `data.fieldName` | string | Системное имя поля в формате `UF_USR_*`. Под этим же именем поле стоит в схеме сотрудника [`GET /v1/users/fields`](/docs/entities/users/fields) |
| `data.userTypeId` | string | Тип поля. Допустимые значения — [Типы полей](/docs/userfields/users#типы-полей) |
| `data.xmlId` | string\|null | Внешний идентификатор для интеграций. Задаётся вручную при создании или обновлении |
| `data.sort` | string | Порядок сортировки в интерфейсе Битрикс24 |
| `data.multiple` | string | Множественное поле: `"Y"` или `"N"` |
| `data.mandatory` | string | Обязательное при заполнении. У полей сотрудника всегда `"N"` — [Какие свойства применяются](/docs/userfields/users#какие-свойства-применяются) |
| `data.showFilter` | string | Показывать в фильтре. `"N"` — выключен, включённый возвращается как `"E"` — форма хранения Битрикс24. Прочитанные `"N"` и `"E"` можно отправить обратно как есть |
| `data.showInList` | string | Показывать в списке сотрудников. У полей сотрудника всегда `"Y"` |
| `data.editInList` | string | Разрешить редактирование из списка. У полей сотрудника всегда `"Y"` |
| `data.isSearchable` | string | Участие в полнотекстовом поиске. У полей сотрудника всегда `"N"` |
| `data.settings` | object | Настройки поля, специфичные для `userTypeId`. Для `enumeration` — `DISPLAY`, `LIST_HEIGHT`, `CAPTION_NO_VALUE`, `SHOW_NO_VALUE`. Наборы для других типов — в «Известных особенностях» |
| `data.list` | array | Варианты поля типа `enumeration`. Для остальных типов поле отсутствует. Каждый элемент содержит `ID`, `SORT`, `VALUE`, `DEF` и `XML_ID` — все значения строки, `XML_ID` Битрикс24 генерирует сам, если не передан |

Подписи поля — `editFormLabel`, `listColumnLabel`, `listFilterLabel`, `errorMessage`, `helpMessage` — в ответе отсутствуют: их отдаёт только схема сотрудника [`GET /v1/users/fields`](/docs/entities/users/fields), в поле `label`.

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

```json
{
  "success": true,
  "data": {
    "id": 6007923,
    "entityId": "USER",
    "fieldName": "UF_USR_SHIFT",
    "userTypeId": "enumeration",
    "xmlId": null,
    "sort": "200",
    "multiple": "N",
    "mandatory": "N",
    "showFilter": "E",
    "showInList": "Y",
    "editInList": "Y",
    "isSearchable": "N",
    "settings": {
      "DISPLAY": "LIST",
      "LIST_HEIGHT": 1,
      "CAPTION_NO_VALUE": "",
      "SHOW_NO_VALUE": "Y"
    },
    "list": [
      {
        "ID": "3967",
        "SORT": "10",
        "VALUE": "Утро",
        "DEF": "N",
        "XML_ID": "46e4bae66329c39fafcbaef4262d490b"
      },
      {
        "ID": "3969",
        "SORT": "20",
        "VALUE": "Вечер",
        "DEF": "N",
        "XML_ID": "3351c3d103ce376358db5c39019af5c4"
      },
      {
        "ID": "3971",
        "SORT": "30",
        "VALUE": "Ночь",
        "DEF": "N",
        "XML_ID": "160aa32209dc24bfb699010bf2df174a"
      }
    ]
  }
}
```

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

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

```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "User field 999999999 not found"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_ID` | `:id` не является положительным целым числом — запрос отклонён до обращения к порталу |
| 404 | `NOT_FOUND` | Поля с таким `id` нет |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `user.userfield` |
| 401 | `MISSING_API_KEY` | Отсутствует заголовок `X-Api-Key` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

**Карточка собирается из списка.** Ответ — элемент списка полей, отобранный по `id`: набор свойств тот же, что у элемента [списка](/docs/userfields/users/list), дополнительных данных карточка не несёт. Поэтому, если нужны несколько полей сразу, дешевле один запрос списка, чем карточка на каждое поле.

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

- `string` — `SIZE`, `ROWS`, `REGEXP`, `MIN_LENGTH`, `MAX_LENGTH`, `DEFAULT_VALUE`
- `integer` — `SIZE`, `MIN_VALUE`, `MAX_VALUE`, `DEFAULT_VALUE`
- `double` — `PRECISION`, `SIZE`, `MIN_VALUE`, `MAX_VALUE`, `DEFAULT_VALUE`
- `date` — `DEFAULT_VALUE` объектом `{ "TYPE": "NONE", "VALUE": "" }`
- `datetime` — `DEFAULT_VALUE` таким же объектом, `USE_SECOND`, `USE_TIMEZONE`
- `boolean` — `DEFAULT_VALUE`, `DISPLAY`, `LABEL`, `LABEL_CHECKBOX`
- `enumeration` — `DISPLAY`, `LIST_HEIGHT`, `CAPTION_NO_VALUE`, `SHOW_NO_VALUE`
- `file` — `SIZE`, `LIST_WIDTH`, `LIST_HEIGHT`, `MAX_SHOW_SIZE`, `MAX_ALLOWED_SIZE`, `EXTENSIONS`, `TARGET_BLANK`, `DEFAULT_VIEW`
- `employee` — `DEFAULT_VALUE` пустым массивом
- `crm` — флаги привязки `LEAD`, `CONTACT`, `COMPANY`, `DEAL` со значениями `"Y"` / `"N"`

Тип вложенного ключа `DEFAULT_VALUE` тоже зависит от `userTypeId`: пустая строка для `string` и `money`, `null` для `integer` и `double`, число `0` для `boolean`, объект для `date` и `datetime`, пустой массив для `employee`. Опирайтесь на конкретный `userTypeId`, а не на единый набор.

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

- [Список полей сотрудников](/docs/userfields/users/list)
- [Создать поле](/docs/userfields/users/create)
- [Обновить поле](/docs/userfields/users/update)
- [Поля сотрудников](/docs/userfields/users)
- [Пользовательские поля](/docs/userfields)