# Поля сотрудников

Создание, чтение, обновление и удаление пользовательских полей сотрудника — сущности `users`. Поле хранится под именем с префиксом `UF_USR_` и под тем же именем приходит в карточке сотрудника.

Битрикс24 API: `user.userfield.*`
Скоуп: `user.userfield`

## Операции

- [Список полей](/docs/userfields/users/list) — `GET /v1/userfields/users`
- [Получить поле](/docs/userfields/users/get) — `GET /v1/userfields/users/:id`
- [Создать поле](/docs/userfields/users/create) — `POST /v1/userfields/users`
- [Обновить поле](/docs/userfields/users/update) — `PATCH /v1/userfields/users/:id`
- [Удалить поле](/docs/userfields/users/delete) — `DELETE /v1/userfields/users/:id`

Каталога типов у этой сущности нет: запрос `GET /v1/userfields/users/types` отвечает `400 UNSUPPORTED_ACTION`. Тип поля задаётся при создании явно — допустимые значения `userTypeId` перечислены в разделе «Типы полей» ниже.

## Скоуп ключа

Все пять операций требуют у API-ключа скоуп `user.userfield` — это отдельное право, его отмечают при выпуске ключа. Скоупа `user` для этих операций недостаточно: запрос без `user.userfield` отвечает `403 SCOPE_DENIED`.

## Имя поля

`fieldName` при создании обязателен. Имя хранится в верхнем регистре с префиксом `UF_USR_`: переданное `UF_USR_BADGE_NO` сохраняется как есть, `badge_no` становится `UF_USR_BADGE_NO` — регистр и префикс дополняет Битрикс24.

Под этим же именем поле стоит в схеме сотрудника [`GET /v1/users/fields`](/docs/entities/users/fields) и принимается в запросах к сотрудникам — [`POST /v1/users`](/docs/entities/users/create), [`PATCH /v1/users/:id`](/docs/entities/users/update). В отличие от полей CRM, у полей сотрудника имя определения и рабочее имя совпадают. Формат значения по типам — [Пользовательские поля (UF)](/docs/entity-api#пользовательские-поля-uf).

## Подписи поля

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

Строка `label` без явных `editFormLabel`, `listColumnLabel` и `listFilterLabel` подставляется во все три подписи. Чтобы задать разные подписи по языкам портала, передайте объект: `"editFormLabel": { "ru": "Табельный номер", "en": "Badge number" }`.

## Какие свойства применяются

Битрикс24 принимает тело запроса целиком и отвечает успехом, но часть свойств поля сотрудника не применяет — поле читается с прежними значениями. Проверено живыми вызовами на создании и обновлении.

| Свойство | Создание | Обновление |
|----------|----------|------------|
| `sort`, `xmlId`, `settings` | применяется | применяется |
| подписи | принимаются — в ответах раздела их не видно, проверить можно по `label` в схеме сотрудника | принимаются |
| `showFilter` | применяется | применяется |
| `list` — варианты поля `enumeration` | применяется | применяется |
| `multiple` | применяется | не применяется — множественность задаётся один раз при создании |
| `mandatory`, `isSearchable`, `showInList`, `editInList` | не применяется | не применяется |

Поле сотрудника всегда читается с `mandatory: "N"`, `isSearchable: "N"`, `showInList: "Y"`, `editInList: "Y"` — какие бы значения ни были переданы.

## Типы полей

Допустимые значения `userTypeId` — каждое проверено созданием поля:

`string`, `integer`, `double`, `boolean`, `date`, `datetime`, `enumeration`, `money`, `url`, `address`, `file`, `employee`, `crm`, `crm_status`, `iblock_section`, `iblock_element`.

Значение вне этого списка отвечает `422 BITRIX_ERROR`. Состав объекта `settings` зависит от типа — наборы ключей для основных типов приведены на странице [Получить поле](/docs/userfields/users/get).

## Соответствие имён полей

В теле запроса и в ответе свойства поля называются camelCase-именами, а Битрикс24 хранит их в UPPER_CASE. Таблица помогает читать вложенные структуры — `settings` и элементы массива `list`, которые Битрикс24 возвращает «как есть».

| API (camelCase) | Битрикс24 (UPPER_CASE) |
|-----------------|------------------------|
| `id` | `ID` |
| `entityId` | `ENTITY_ID` |
| `fieldName` | `FIELD_NAME` |
| `userTypeId` | `USER_TYPE_ID` |
| `xmlId` | `XML_ID` |
| `sort` | `SORT` |
| `multiple` | `MULTIPLE` |
| `mandatory` | `MANDATORY` |
| `showFilter` | `SHOW_FILTER` |
| `showInList` | `SHOW_IN_LIST` |
| `editInList` | `EDIT_IN_LIST` |
| `isSearchable` | `IS_SEARCHABLE` |
| `label` | `LABEL` |
| `editFormLabel` | `EDIT_FORM_LABEL` |
| `listColumnLabel` | `LIST_COLUMN_LABEL` |
| `listFilterLabel` | `LIST_FILTER_LABEL` |
| `errorMessage` | `ERROR_MESSAGE` |
| `helpMessage` | `HELP_MESSAGE` |
| `settings` | `SETTINGS` |
| `list` | `LIST` |

### Флаги «да/нет»

Свойства `multiple` и `showFilter` присылайте булевыми (`true` / `false`) либо строками `"Y"` / `"N"` — платформа приводит обе формы. В ответе `multiple` читается как `"Y"` или `"N"`, а включённый `showFilter` — как `"E"`: это форма хранения Битрикс24. Прочитанное `"E"` можно отправить обратно как есть — платформа понимает его как «включён», и цикл «прочитал → поменял одно свойство → отправил целиком» фильтр не гасит.

## Типовой сценарий

1. Посмотреть уже созданные поля: [`GET /v1/userfields/users`](/docs/userfields/users/list).
2. Создать поле с обязательными `userTypeId` и `fieldName`: [`POST /v1/userfields/users`](/docs/userfields/users/create).
3. Прочитать его описание — для `enumeration` с вариантами `list`: [`GET /v1/userfields/users/:id`](/docs/userfields/users/get).
4. Убедиться, что поле появилось в схеме сотрудника [`GET /v1/users/fields`](/docs/entities/users/fields), и записать значение сотруднику: [`PATCH /v1/users/:id`](/docs/entities/users/update).
5. Обновить ([`PATCH`](/docs/userfields/users/update)) или удалить ([`DELETE`](/docs/userfields/users/delete)) поле по идентификатору.

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

- [Поля CRM-сущностей](/docs/userfields/crm)
- [Поля смарт-процессов](/docs/userfields/smart-processes)
- [Сотрудники](/docs/entities/users)
- [Поля сотрудника](/docs/entities/users/fields)
- [Скоупы](/docs/scopes)
- [Пользовательские поля](/docs/userfields)