# Пользователи

Управление сотрудниками портала: список, получение по ID, приглашение нового, обновление, деактивация. Сущность хранит контактные данные, должность, отдел и пользовательские поля (UF) сотрудника.

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

## Операции

- [Создать сотрудника](./users/create.md) — `POST /v1/users`
- [Пригласить сотрудника](./users/invite.md) — `POST /v1/users/invite`
- [Список сотрудников](./users/list.md) — `GET /v1/users`
- [Получить сотрудника](./users/get.md) — `GET /v1/users/:id`
- [Профиль текущего сотрудника](./users/me.md) — `GET /v1/users/me`
- [Обновить сотрудника](./users/update.md) — `PATCH /v1/users/:id`
- [Деактивировать сотрудника](./users/delete.md) — `DELETE /v1/users/:id`
- [Поиск сотрудников](./users/search.md) — `POST /v1/users/search`
- [Поля сотрудника](./users/fields.md) — `GET /v1/users/fields`
- [Агрегация сотрудников](./users/aggregate.md) — `POST /v1/users/aggregate`

## Ключевые поля

| Поле | Описание |
|------|---------|
| `id` | Идентификатор сотрудника |
| `name` / `lastName` / `secondName` | Имя, фамилия, отчество |
| `email` | Email — обязательно при создании, должен быть уникальным среди всех сотрудников портала |
| `active` | Признак активности: `true` — работает, `false` — деактивирован |
| `workPosition` | Должность |
| `departmentId` | Массив ID отделов сотрудника. Список: `GET /v1/departments` |
| `personalPhone` / `personalMobile` / `workPhone` | Телефоны |
| `isAdmin` | Признак администратора портала (только чтение). Наполняется **только в [`GET /v1/users/me`](/docs/entities/users/me)**, с тремя состояниями: `true` — администратор, `false` — не администратор, `null` — определить не удалось (временный сбой, профиль всё равно возвращается, и это не ошибка) — пригоден для серверной проверки прав. **В `GET /v1/users/:id` и списке `GET /v1/users` поле недоступно**: `user.get` его не возвращает (`data.isAdmin` = `undefined`), вердикт отдаётся только для текущего пользователя сессии. |

Полный список полей — [`GET /v1/users/fields`](/docs/entities/users/fields).

## Что нужно знать перед работой

1. **Создание требует email.** Поле `email` обязательное и должно быть уникальным для всего портала. Дубль вернёт `BITRIX_ERROR: wrong_email` без явного указания причины — этот код Битрикс24 использует для нескольких разных кейсов (см. ниже).
2. **Два эндпоинта для создания.** [`POST /v1/users`](/docs/entities/users/create) — обычная entity-форма, проксирует ошибки Битрикс24 как есть. [`POST /v1/users/invite`](/docs/entities/users/invite) — обёртка с предзаполнением `departmentId: [1]` для штатных сотрудников и явной валидацией email на стороне Вайбкод (`EMAIL_REQUIRED`, `EMAIL_INVALID`). Для интеграций предпочтительнее `/invite` — у него понятные коды ошибок.
3. **PATCH и DELETE требуют прав администратора портала.** Битрикс24 применяет обновление сотрудника только если у владельца ключа есть админские права на портале. Без них Битрикс24 возвращает `result: false`, Вайбкод оборачивает это в `403 UPDATE_FAILED` с подсказкой в поле `hint`.
4. **`DELETE /v1/users/:id` — это деактивация.** Эндпоинт снимает у сотрудника доступ к порталу, но сохраняет всю запись и её связи (ответственный за сделки, автор комментариев, участник чатов). Под капотом маппится на обновление поля активности (`active: false`), в ответе явный маркер `deactivated: true`. Восстановить доступ — `PATCH /v1/users/:id { active: true }`. Данные не теряются.
5. **Поля только для чтения.** `id`, `isOnline`, `isAdmin`, `lastLogin`, `dateRegister`, `lastActivityDate`, `userType`, `timestampX` заполняются системой. Попытка передать их в `PATCH /v1/users/:id` отклоняется заранее с `400 READONLY_FIELD` — вызов Битрикс24 не происходит.
6. **`WORK_*` / `PERSONAL_*` обычно не приходят, а пустые поля Битрикс24 опускает.** Стандартные заполненные поля (`name`, `email`, `active`, `departmentId`, `timeZone`, `userType` и др.) — `camelCase`. Поля `WORK_COMPANY`, `WORK_DEPARTMENT`, `PERSONAL_STATE`, `PERSONAL_ZIP` и аналогичные на практике в ответе **отсутствуют** (Битрикс24 не возвращает незаполненные поля); если такое поле всё же приходит — оно сохраняет исходное имя `UPPER_SNAKE_CASE` (не камелкейсится). То есть ключа может **не быть вовсе** — не полагайтесь на его присутствие.
7. **«Пусто» в datetime-полях закодировано тремя способами.** `timestampX` и `lastActivityDate` (объявлены `datetime`) приходят **пустым объектом `{}`**, а не строкой/`null` (`new Date(u.timestampX)` → `Invalid Date`; `if (u.lastActivityDate)` — **истинно** даже без активности). `lastActivityDate` к тому же может **отсутствовать** как ключ. `lastLogin` отдаёт `null`, когда входа не было. `dateRegister` — ISO-строка всегда (полночь UTC). Проверяйте «активность была» сравнением типа (`typeof x === 'string'`), а не truthy-проверкой.
8. **Внешние сотрудники (extranet).** При создании пользователя экстранета `EXTRANET: "Y"` обязательное поле `SONET_GROUP_ID` (массив ID рабочих групп) вместо `departmentId`. `/invite` явно отдаёт `400 SONET_GROUP_ID_REQUIRED`, если оба не переданы.

## Типичный сценарий

1. Найти сотрудника по части имени или email: [`GET /v1/users?filter[NAME]=Иван`](/docs/entities/users/list).
2. Получить полные данные одного: [`GET /v1/users/:id`](/docs/entities/users/get).
3. Пригласить нового через Вайбкод-обёртку: [`POST /v1/users/invite`](/docs/entities/users/invite).
4. Обновить должность или отдел: [`PATCH /v1/users/:id`](/docs/entities/users/update).
5. Если сотрудник уволился — деактивировать: [`DELETE /v1/users/:id`](/docs/entities/users/delete). Восстановить — `PATCH /v1/users/:id { active: true }`.

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Авто-пагинация | включается при `limit > 50` |
| `offset` на больших выборках | рекомендуется `limit ≤ 500` при `offset ≥ 2500` |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Rate limit | общий для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Отделы](/docs/entities/departments)
- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Справочник API](/docs/api-reference)