H-3657: задокументировал user-list-cache (источник usersListKey) #36
+194
@@ -558,6 +558,200 @@ paths:
|
||||
500:
|
||||
description: Server Error
|
||||
|
||||
/user/index:
|
||||
get:
|
||||
tags:
|
||||
- user
|
||||
summary: Список сотрудников
|
||||
description: |
|
||||
Постраничный список активных сотрудников тенанта. Тот же эндпоинт,
|
||||
что использует основной UI HRBox. Видны все сотрудники со
|
||||
`status_id = ACTIVE`, скрытые и не валидные для отображения отфильтрованы.
|
||||
|
||||
### Типичные кейсы
|
||||
|
||||
- Интеграции, которым нужно собрать `user_id` для последующего
|
||||
`POST /user-list-cache/set-user-list` → массового начисления валюты.
|
||||
- Подразделение-специфичные выгрузки (`department_id`).
|
||||
|
||||
### Сортировка
|
||||
|
||||
Поддерживается `?sort=name`, `?sort=-created_at`, `-last_login_at` и т.п.
|
||||
|
||||
### Размер страницы
|
||||
|
||||
Дефолт 10, максимум 20 (`pageSizeLimit = [1, 20]`).
|
||||
operationId: userIndex
|
||||
parameters:
|
||||
- name: page
|
||||
in: query
|
||||
schema: { type: integer, minimum: 1, default: 1 }
|
||||
- name: per-page
|
||||
in: query
|
||||
schema: { type: integer, minimum: 1, maximum: 20, default: 10 }
|
||||
- name: sort
|
||||
in: query
|
||||
schema: { type: string }
|
||||
description: 'Префикс `-` для DESC. Например `-created_at`, `name`, `-last_login_at`.'
|
||||
- name: searchQuery
|
||||
in: query
|
||||
schema: { type: string }
|
||||
description: Сквозной поиск по ФИО / e-mail / телефону / должности.
|
||||
- name: id
|
||||
in: query
|
||||
schema:
|
||||
oneOf:
|
||||
- type: string
|
||||
format: uuid
|
||||
- type: array
|
||||
items: { type: string, format: uuid }
|
||||
description: 'Фильтр по конкретным UUID. Можно массив через `?id[]=...&id[]=...`.'
|
||||
- name: not_id
|
||||
in: query
|
||||
schema: { type: string, format: uuid }
|
||||
description: Исключить конкретного юзера.
|
||||
- name: email
|
||||
in: query
|
||||
schema: { type: string }
|
||||
- name: phone_auth
|
||||
in: query
|
||||
schema: { type: string }
|
||||
- name: name
|
||||
in: query
|
||||
schema: { type: string }
|
||||
- name: first_name
|
||||
in: query
|
||||
schema: { type: string }
|
||||
- name: last_name
|
||||
in: query
|
||||
schema: { type: string }
|
||||
- name: middle_name
|
||||
in: query
|
||||
schema: { type: string }
|
||||
- name: position
|
||||
in: query
|
||||
schema: { type: string }
|
||||
- name: company
|
||||
in: query
|
||||
schema: { type: string }
|
||||
- name: department_id
|
||||
in: query
|
||||
schema:
|
||||
oneOf:
|
||||
- type: string
|
||||
format: uuid
|
||||
- type: array
|
||||
items: { type: string, format: uuid }
|
||||
- name: reg_status_id
|
||||
in: query
|
||||
schema: { type: string }
|
||||
description: Comma-separated `RegStatus` (1=NO_ACCOUNT, 2=INVITED, 3=ACTIVE, 4=BLOCKED).
|
||||
- name: gender_id
|
||||
in: query
|
||||
schema: { type: string }
|
||||
- name: is_boss
|
||||
in: query
|
||||
schema: { type: boolean }
|
||||
- name: is_external
|
||||
in: query
|
||||
schema: { type: boolean }
|
||||
- name: group_id
|
||||
in: query
|
||||
schema: { type: string, format: uuid }
|
||||
description: Фильтр по статической группе сотрудников.
|
||||
- name: duty_id
|
||||
in: query
|
||||
schema: { type: string, format: uuid }
|
||||
- name: spec_id
|
||||
in: query
|
||||
schema: { type: string, format: uuid }
|
||||
- name: created_at
|
||||
in: query
|
||||
schema: { type: string }
|
||||
description: 'Диапазон `from|to` (ISO).'
|
||||
- name: last_login_at
|
||||
in: query
|
||||
schema: { type: string }
|
||||
description: 'Диапазон `from|to` (ISO).'
|
||||
- name: user_list_key
|
||||
in: query
|
||||
schema: { type: string, format: uuid }
|
||||
description: 'Ключ закэшированной выборки (см. `/user-list-cache/set-user-list`).'
|
||||
- name: expand
|
||||
in: query
|
||||
schema: { type: string }
|
||||
description: |
|
||||
Comma-separated extra-fields. Поддерживаются: `isBoss`, `faceUrl`,
|
||||
`iconUrl`, `photoUrl`, `employment`, `cityName`, `statusText`,
|
||||
`profileCorporateContacts`, `isFavoriteUser`, `contacts`, `statusTypes`.
|
||||
responses:
|
||||
200:
|
||||
description: Список сотрудников
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/userProfile'
|
||||
_links:
|
||||
$ref: '#/components/schemas/_links'
|
||||
_meta:
|
||||
$ref: '#/components/schemas/_meta'
|
||||
401:
|
||||
description: Unauthorized.
|
||||
|
||||
/user/search:
|
||||
get:
|
||||
tags:
|
||||
- user
|
||||
summary: Быстрый поиск сотрудников по строке
|
||||
description: |
|
||||
Лёгкий компактный поиск — возвращает до `limit` юзеров с минимальным
|
||||
набором полей (id, name, position, departmentName, isBoss, iconUrl,
|
||||
employmentId). Использует тот же `UserSearchLogic`, что и сквозной
|
||||
поиск UI.
|
||||
|
||||
Поле `users` будет пустым массивом, если у текущего юзера нет права
|
||||
`show-structure-names`. Также пустой массив, если `q` не передан или пустой.
|
||||
operationId: userSearch
|
||||
parameters:
|
||||
- name: q
|
||||
in: query
|
||||
required: true
|
||||
schema: { type: string, maxLength: 255 }
|
||||
description: Строка поиска (ФИО / e-mail / должность / подразделение).
|
||||
- name: limit
|
||||
in: query
|
||||
schema: { type: integer, minimum: 1, maximum: 100, default: 10 }
|
||||
- name: offset
|
||||
in: query
|
||||
schema: { type: integer, minimum: 0, default: 0 }
|
||||
responses:
|
||||
200:
|
||||
description: Результаты поиска
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
q:
|
||||
type: string
|
||||
users:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
id: { type: string, format: uuid }
|
||||
name: { type: string }
|
||||
employmentId: { type: string, format: uuid, nullable: true }
|
||||
position: { type: string }
|
||||
departmentName: { type: string }
|
||||
isBoss: { type: boolean }
|
||||
iconUrl: { type: string, nullable: true }
|
||||
|
||||
/user/items:
|
||||
get:
|
||||
tags:
|
||||
|
||||
Reference in New Issue
Block a user