hrbox-public/api
5
0
Fork 0
Code Issues Pull Requests 6 Actions Packages Projects Releases Wiki Activity

H-3657: задокументировал user-list-cache (источник usersListKey) #36

Merged
denis merged 4 commits from feature/H-3657 into master 2026-05-28 14:02:48 +00:00
Conversation 4 Commits 4 Files Changed 1
+243 -161
1 changed files with 243 additions and 161 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 58a32b1768 - Show all commits
v2/swagger.yaml
+243 -161
View File
@@ -564,25 +564,20 @@ paths:
get: get:
tags: tags:
- user - user
summary: Список сотрудников summary: Получить список сотрудников
description: | description: |
Постраничный список активных сотрудников тенанта. Тот же эндпоинт, Возвращает постраничный список активных сотрудников тенанта.
что использует основной UI HRBox. Видны все сотрудники со Выдача ограничена пользователями со статусом `ACTIVE`; скрытые
`status_id = ACTIVE`, скрытые и не валидные для отображения отфильтрованы. и не валидные для отображения записи исключаются.
### Типичные кейсы Эндпоинт может использоваться интеграциями для получения
идентификаторов пользователей (`user_id`), которые в дальнейшем
передаются в `/user-list-cache/set-user-list` или другие методы
массовых операций.
- Интеграции, которым нужно собрать `user_id` для последующего Сортировка поддерживается по нескольким полям, включая `name`,
`POST /user-list-cache/set-user-list` → массового начисления валюты. `created_at`, `last_login_at`. Размер страницы по умолчанию — 10,
- Подразделение-специфичные выгрузки (`department_id`). максимально допустимый — 20.
### Сортировка
Поддерживается `?sort=name`, `?sort=-created_at`, `-last_login_at` и т.п.
### Размер страницы
Дефолт 10, максимум 20 (`pageSizeLimit = [1, 20]`).
operationId: userIndex operationId: userIndex
parameters: parameters:
- name: page - name: page
@@ -594,11 +589,14 @@ paths:
- name: sort - name: sort
in: query in: query
schema: { type: string } schema: { type: string }
description: 'Префикс `-` для DESC. Например `-created_at`, `name`, `-last_login_at`.' description: |
Поле сортировки. Для сортировки по убыванию используется префикс `-`.
Примеры: `-created_at`, `name`, `-last_login_at`.
- name: searchQuery - name: searchQuery
in: query in: query
schema: { type: string } schema: { type: string }
description: Сквозной поиск по ФИО / e-mail / телефону / должности. description: |
Сквозной поиск по имени, фамилии, e-mail, телефону и должности.
- name: id - name: id
in: query in: query
schema: schema:
@@ -607,35 +605,45 @@ paths:
format: uuid format: uuid
- type: array - type: array
items: { type: string, format: uuid } items: { type: string, format: uuid }
description: 'Фильтр по конкретным UUID. Можно массив через `?id[]=...&id[]=...`.' description: |
Идентификатор пользователя. Допускается передача нескольких
значений в виде массива `?id[]=...&id[]=...`.
- name: not_id - name: not_id
in: query in: query
schema: { type: string, format: uuid } schema: { type: string, format: uuid }
description: Исключить конкретного юзера. description: Исключить пользователя с указанным идентификатором.
- name: email - name: email
in: query in: query
schema: { type: string } schema: { type: string }
description: Поиск по электронной почте.
- name: phone_auth - name: phone_auth
in: query in: query
schema: { type: string } schema: { type: string }
description: Поиск по номеру телефона.
- name: name - name: name
in: query in: query
schema: { type: string } schema: { type: string }
description: Поиск по полному имени.
- name: first_name - name: first_name
in: query in: query
schema: { type: string } schema: { type: string }
description: Поиск по имени.
- name: last_name - name: last_name
in: query in: query
schema: { type: string } schema: { type: string }
description: Поиск по фамилии.
- name: middle_name - name: middle_name
in: query in: query
schema: { type: string } schema: { type: string }
description: Поиск по отчеству.
- name: position - name: position
in: query in: query
schema: { type: string } schema: { type: string }
description: Поиск по должности.
- name: company - name: company
in: query in: query
schema: { type: string } schema: { type: string }
description: Поиск по наименованию компании.
- name: department_id - name: department_id
in: query in: query
schema: schema:
@@ -644,51 +652,68 @@ paths:
format: uuid format: uuid
- type: array - type: array
items: { type: string, format: uuid } items: { type: string, format: uuid }
description: Идентификатор подразделения.
- name: reg_status_id - name: reg_status_id
in: query in: query
schema: { type: string } schema: { type: string }
description: Comma-separated `RegStatus` (1=NO_ACCOUNT, 2=INVITED, 3=ACTIVE, 4=BLOCKED). description: |
Статус регистрации пользователя. Допустимые значения:
`1` — без аккаунта, `2` — приглашён, `3` — активен,
`4` — заблокирован. Допускается передача нескольких значений
через запятую.
- name: gender_id - name: gender_id
in: query in: query
schema: { type: string } schema: { type: string }
description: Идентификатор пола.
- name: is_boss - name: is_boss
in: query in: query
schema: { type: boolean } schema: { type: boolean }
description: Признак руководящей должности.
- name: is_external - name: is_external
in: query in: query
schema: { type: boolean } schema: { type: boolean }
description: Признак внешнего сотрудника.
- name: group_id - name: group_id
in: query in: query
schema: { type: string, format: uuid } schema: { type: string, format: uuid }
description: Фильтр по статической группе сотрудников. description: Идентификатор группы сотрудников.
- name: duty_id - name: duty_id
in: query in: query
schema: { type: string, format: uuid } schema: { type: string, format: uuid }
description: Идентификатор обязанности.
- name: spec_id - name: spec_id
in: query in: query
schema: { type: string, format: uuid } schema: { type: string, format: uuid }
description: Идентификатор специализации.
- name: created_at - name: created_at
in: query in: query
schema: { type: string } schema: { type: string }
description: 'Диапазон `from|to` (ISO).' description: |
Период создания записи в формате `<начало>|<конец>`,
где даты указаны по ISO 8601.
- name: last_login_at - name: last_login_at
in: query in: query
schema: { type: string } schema: { type: string }
description: 'Диапазон `from|to` (ISO).' description: |
Период последнего входа в систему в формате `<начало>|<конец>`.
- name: user_list_key - name: user_list_key
in: query in: query
schema: { type: string, format: uuid } schema: { type: string, format: uuid }
description: 'Ключ закэшированной выборки (см. `/user-list-cache/set-user-list`).' description: |
Ключ закэшированной выборки пользователей, полученный
от `/user-list-cache/set-user-list`.
- name: expand - name: expand
in: query in: query
schema: { type: string } schema: { type: string }
description: | description: |
Comma-separated extra-fields. Поддерживаются: `isBoss`, `faceUrl`, Список дополнительных полей через запятую. Поддерживаемые
`iconUrl`, `photoUrl`, `employment`, `cityName`, `statusText`, значения: `isBoss`, `faceUrl`, `iconUrl`, `photoUrl`,
`profileCorporateContacts`, `isFavoriteUser`, `contacts`, `statusTypes`. `employment`, `cityName`, `statusText`,
`profileCorporateContacts`, `isFavoriteUser`, `contacts`,
`statusTypes`.
responses: responses:
200: 200:
description: Список сотрудников description: Список сотрудников.
content: content:
application/json: application/json:
schema: schema:
@@ -703,37 +728,41 @@ paths:
_meta: _meta:
$ref: '#/components/schemas/_meta' $ref: '#/components/schemas/_meta'
401: 401:
description: Unauthorized. description: Запрос не авторизован.
/user/search: /user/search:
get: get:
tags: tags:
- user - user
summary: Быстрый поиск сотрудников по строке summary: Найти сотрудников по строке поиска
description: | description: |
Лёгкий компактный поиск — возвращает до `limit` юзеров с минимальным Компактный поиск пользователей по строке. Возвращает до `limit`
набором полей (id, name, position, departmentName, isBoss, iconUrl, записей с минимальным набором полей, достаточным для отображения
employmentId). Использует тот же `UserSearchLogic`, что и сквозной в выпадающих списках и подсказках.
поиск UI.
Поле `users` будет пустым массивом, если у текущего юзера нет права Поле `users` в ответе содержит пустой массив, если параметр `q`
`show-structure-names`. Также пустой массив, если `q` не передан или пустой. не передан либо у текущего пользователя отсутствует право
`show-structure-names`.
operationId: userSearch operationId: userSearch
parameters: parameters:
- name: q - name: q
in: query in: query
required: true required: true
schema: { type: string, maxLength: 255 } schema: { type: string, maxLength: 255 }
description: Строка поиска (ФИО / e-mail / должность / подразделение). description: |
Строка поиска. Применяется к полному имени, электронной почте,
должности и наименованию подразделения.
- name: limit - name: limit
in: query in: query
schema: { type: integer, minimum: 1, maximum: 100, default: 10 } schema: { type: integer, minimum: 1, default: 10 }
description: Максимальное количество возвращаемых записей.
- name: offset - name: offset
in: query in: query
schema: { type: integer, minimum: 0, default: 0 } schema: { type: integer, minimum: 0, default: 0 }
description: Смещение выборки.
responses: responses:
200: 200:
description: Результаты поиска description: Результаты поиска.
content: content:
application/json: application/json:
schema: schema:
@@ -7310,26 +7339,34 @@ paths:
/admin/wallet-transaction/create: /admin/wallet-transaction/create:
post: post:
tags: [admin-wallet-transaction] tags: [admin-wallet-transaction]
summary: Провести начисление/списание по форме summary: Провести начисление или списание по форме
description: | description: |
Массовая операция по выборке сотрудников. Запускается асинхронно Массовая операция по выборке сотрудников. Выполняется асинхронно;
через launcher — баланс и история транзакций обновятся в течение баланс и история транзакций обновляются в течение нескольких секунд
нескольких секунд. после успешного приёма запроса.
### Как получить `usersListKey` ## Получение значения `usersListKey`
1. `POST /api/v2/user-list-cache/set-user-list` с телом 1. Выборка сотрудников сохраняется методом
`{key, userList:{usersId:[...]}}` — кэширует выборку под вашим `POST /api/v2/user-list-cache/set-user-list` с телом
ключом (TTL 24 часа). `{key, userList: {usersId: [...]}}`. Срок жизни сохранённой
2. Этот же `key` отдаёте здесь как `usersListKey`. выборки — 24 часа.
2. Использованное значение `key` передаётся в данный метод
в качестве параметра `usersListKey`.
Подробности и пример — в описании метода `set-user-list`. Подробное описание формата и пример приведены в описании метода
`/user-list-cache/set-user-list`.
### Soft-error состояния (`200 OK` + `message.type=warning`) ## Состояния, возвращаемые с предупреждением
- `"Укажите сотрудников"` — выборка по `usersListKey` пустая Ответ имеет код `200 OK` и содержит `message.type = "warning"`
(ключ протух, не существует или userList отдали через form-urlencoded — в следующих случаях.
см. `set-user-list`).
- `"Укажите сотрудников"` — выборка по `usersListKey` пустая.
Возможные причины: ключ не найден, срок его действия истёк
либо запрос `set-user-list` был выполнен в формате
`application/x-www-form-urlencoded` без последующей корректной
передачи `userList`.
- `"Невозможно провести транзакцию, у некоторых сотрудников - `"Невозможно провести транзакцию, у некоторых сотрудников
недостаточно средств на балансе: <имена>"` — debit, не хватает недостаточно средств на балансе: <имена>"` — debit, не хватает
баланса хотя бы у одного юзера; вся операция отменяется. баланса хотя бы у одного юзера; вся операция отменяется.
@@ -7487,34 +7524,36 @@ paths:
/file/prepare-upload: /file/prepare-upload:
post: post:
tags: [file] tags: [file]
summary: Зарегистрировать файл и получить signed URL для загрузки summary: Зарегистрировать файл и получить ссылку для загрузки
description: | description: |
Первый шаг двухступенчатой загрузки. Создаёт запись `File` в БД и Первый шаг двухэтапной загрузки. Создаёт запись о файле и
возвращает временный signed-URL для PUT-загрузки бинарника напрямую возвращает временную подписанную ссылку для прямой загрузки
в объектное хранилище (S3-совместимое). содержимого в объектное хранилище.
### Полный флоу ## Последовательность вызовов
1. `POST /api/v2/file/prepare-upload` с метаданными файла → получаем 1. `POST /api/v2/file/prepare-upload` с метаданными файла.
`{File, uploadInfo:{signedUrl}}`. В ответе возвращаются запись `File` и объект `uploadInfo`,
2. `PUT <signedUrl>` с телом-бинарником и `Content-Type` файла — содержащий ссылку `signedUrl`.
идёт прямо в S3, минуя HRBox. 2. `PUT <signedUrl>` с содержимым файла в теле запроса
3. `POST /api/v2/file/finish-upload?id=<File.id>` — помечает запись и заголовком `Content-Type`, соответствующим типу файла.
как загруженную (`file_status_id` → UPLOADED). После этого Запрос выполняется напрямую в объектное хранилище.
`File.id` можно использовать в любом флоу, где требуется 3. `POST /api/v2/file/finish-upload?id=<File.id>` — подтверждает
`file_id` (например `POST /admin/wallet-transaction/excel-processing`). завершение загрузки. После этого идентификатор файла может
быть использован в методах, ожидающих параметр `file_id`
(например, `POST /admin/wallet-transaction/excel-processing`).
### Возможные ошибки ## Ошибки валидации
Если файл не прошёл валидацию (тип, размер) — ответ При несоответствии файла ограничениям по типу или размеру
`{error:{message, validation:{...}}}`. На уровне антивируса — возвращается объект вида `{error: {message, validation: {...}}}`.
`UnsafeFileException` 4xx.
### Идемпотентность ## Идемпотентность
Если передать существующий `id` в body — вернётся прежняя запись При передаче в теле запроса значения существующего идентификатора
и новый `signedUrl` (если файл ещё не uploaded). Если файл уже возвращается имеющаяся запись. Если файл ещё не загружен —
uploaded — `uploadInfo` будет отсутствовать. в ответе также присутствует объект `uploadInfo` с новой ссылкой.
Для уже загруженного файла объект `uploadInfo` в ответе отсутствует.
operationId: filePrepareUpload operationId: filePrepareUpload
requestBody: requestBody:
required: true required: true
@@ -7524,7 +7563,7 @@ paths:
$ref: '#/components/schemas/FilePrepareUploadBody' $ref: '#/components/schemas/FilePrepareUploadBody'
responses: responses:
200: 200:
description: Файл зарегистрирован, ссылка на загрузку готова description: Файл зарегистрирован, ссылка для загрузки получена.
content: content:
application/json: application/json:
schema: schema:
@@ -7535,26 +7574,25 @@ paths:
tags: [file] tags: [file]
summary: Подтвердить завершение загрузки файла summary: Подтвердить завершение загрузки файла
description: | description: |
Второй шаг загрузки. Помечает запись `File` как UPLOADED после того, Второй шаг двухэтапной загрузки. Переводит запись о файле
как клиент успешно загрузил бинарник по signedUrl из в состояние UPLOADED после успешной передачи содержимого
`prepare-upload`. До вызова этого метода `file_id` нельзя по ссылке, полученной от `/file/prepare-upload`.
использовать в downstream-флоу (например, при попытке
`wallet-transaction/excel-processing` с не-UPLOADED файлом форма
отклонит запрос с ошибкой «Ошибка загрузки файла»).
### Параметр `id` До вызова этого метода идентификатор файла не может быть
использован в методах, требующих загруженный файл. Например,
Принимается из query (`?id=<uuid>`) или из тела (`{id: <uuid>}`). `POST /admin/wallet-transaction/excel-processing` отклонит
запрос со ссылкой на файл, не имеющий статуса UPLOADED.
operationId: fileFinishUpload operationId: fileFinishUpload
parameters: parameters:
- name: id - name: id
in: query in: query
required: true required: true
schema: { type: string, format: uuid } schema: { type: string, format: uuid }
description: UUID файла, полученный из `prepare-upload`. description: |
Идентификатор файла, полученный от `/file/prepare-upload`.
responses: responses:
200: 200:
description: Файл помечен как загруженный description: Загрузка файла подтверждена.
content: content:
application/json: application/json:
schema: schema:
@@ -7563,34 +7601,35 @@ paths:
File: File:
$ref: '#/components/schemas/File' $ref: '#/components/schemas/File'
400: 400:
description: Не передан id или невалидный UUID. description: Параметр `id` не передан или имеет некорректный формат.
404: 404:
description: Файл с таким id не найден. description: Файл с указанным идентификатором не найден.
/user-list-cache/set-user-list: /user-list-cache/set-user-list:
post: post:
tags: [user-list-cache] tags: [user-list-cache]
summary: Закэшировать выборку сотрудников и получить ключ summary: Сохранить выборку сотрудников и получить её идентификатор
description: | description: |
Кэширует произвольную выборку сотрудников (по `usersId`, Сохраняет в кэше выборку сотрудников, описанную через поля
`departmentsId`, `userGroupsId`, динамическим условиям и т.д.) `UserListForm` (списки идентификаторов пользователей,
и связывает её с переданным `key`. Дальше этот `key` можно подразделений, групп, динамические условия и т.п.), и связывает
отдавать в массовые операции — например в её с переданным ключом `key`. Полученный ключ используется
`POST /api/v2/admin/wallet-transaction/create` как `usersListKey`. в методах массовых операций — например, передаётся в качестве
значения `usersListKey` в `POST /api/v2/admin/wallet-transaction/create`.
Ключ хранится в кеше **сутки** (60 × 1440 секунд). Повторный Время жизни ключа в кэше — 24 часа. Повторный вызов с тем же
вызов с тем же `key` перетирает выборку. значением `key` перезаписывает ранее сохранённую выборку.
### ⚠️ Content-Type обязательно `application/json` ## Требования к формату запроса
Поле `userList` — это вложенный JSON-объект (см. схему Поле `userList` представляет собой вложенный объект.
`UserListForm`). Через `application/x-www-form-urlencoded` Запрос должен передаваться в формате `application/json`.
кастомный `Model::setAttributes` не парсит вложенные JSON-модели, При передаче запроса в формате `application/x-www-form-urlencoded`
и сервер сохранит **пустую** выборку. Внешне ответ будет вложенный объект не разбирается сервером, выборка сохраняется
`{success:true}`, но при попытке провести транзакцию вы получите пустой, а последующие массовые операции возвращают предупреждение
`{type:"warning", text:"Укажите сотрудников"}`. Только JSON. вида `{type: "warning", text: "Укажите сотрудников"}`.
### Пример ## Пример запроса
```json ```json
POST /api/v2/user-list-cache/set-user-list POST /api/v2/user-list-cache/set-user-list
@@ -7598,14 +7637,15 @@ paths:
Authorization: Bearer hrb_... Authorization: Bearer hrb_...
{ {
"key": "my-integration-key-2026-05-22", "key": "integration-key-2026-05-22",
"userList": { "userList": {
"usersId": ["25840ad3-a07f-4893-aa70-3a696b79a6f1"] "usersId": ["25840ad3-a07f-4893-aa70-3a696b79a6f1"]
} }
} }
``` ```
`key` придумываете сами (до 50 символов). Значение `key` формируется клиентом и может содержать
до 50 символов.
operationId: userListCacheSet operationId: userListCacheSet
requestBody: requestBody:
required: true required: true
@@ -7616,8 +7656,8 @@ paths:
responses: responses:
200: 200:
description: | description: |
Успех (`data: true`) или ошибки валидации в стандартном формате Успешное сохранение выборки (`data: true`) либо ошибки валидации
`httpJsonResponse`. в стандартном формате `httpJsonResponse`.
content: content:
application/json: application/json:
schema: schema:
@@ -7626,24 +7666,25 @@ paths:
/user-list-cache/user-list-data: /user-list-cache/user-list-data:
get: get:
tags: [user-list-cache] tags: [user-list-cache]
summary: Получить состав закэшированной выборки сотрудников summary: Получить состав сохранённой выборки сотрудников
description: | description: |
Возвращает развёрнутый состав выборки по ключу: список пользователей Возвращает развёрнутый состав выборки по её ключу, включая
(`users`), список подразделений (`departments`), список групп списки пользователей, подразделений и групп, исходное описание
(`userGroups`), исходную форму (`userList`), нормализованные выборки и нормализованные условия. Используется для
условия групп и т.д. Полезно для preview перед массовой операцией. предварительного просмотра перед выполнением массовых операций.
Если ключ протух (24 ч) или не существует — `userList` будет Если ключ не найден или срок его действия истёк, поле `userList`
пустым, остальные коллекции — пустыми массивами. возвращается пустым, прочие коллекции — пустыми массивами.
operationId: userListCacheData operationId: userListCacheData
parameters: parameters:
- name: key - name: key
in: query in: query
required: true required: true
schema: { type: string, maxLength: 50 } schema: { type: string, maxLength: 50 }
description: Идентификатор сохранённой выборки.
responses: responses:
200: 200:
description: Данные выборки description: Состав выборки.
content: content:
application/json: application/json:
schema: schema:
@@ -12912,37 +12953,41 @@ components:
UserListForm: UserListForm:
type: object type: object
description: | description: |
Описание выборки сотрудников. Все поля опциональны — указывайте те, Описание выборки сотрудников. Все поля являются опциональными;
которыми хотите задать состав. Условия объединяются через OR указанные критерии объединяются по логическому ИЛИ — пользователь
(любой из критериев включает юзера). включается в выборку при соответствии хотя бы одному из них.
properties: properties:
usersId: usersId:
type: array type: array
description: Явный список UUID сотрудников. description: Список идентификаторов пользователей.
items: items:
type: string type: string
format: uuid format: uuid
departmentsId: departmentsId:
type: array type: array
description: UUID подразделений. Включает всех сотрудников этих подразделений. description: |
Список идентификаторов подразделений. В выборку включаются
все сотрудники указанных подразделений.
items: items:
type: string type: string
format: uuid format: uuid
isDepartmentRecursive: isDepartmentRecursive:
type: boolean type: boolean
default: false default: false
description: Если `true` — захватывает сотрудников вложенных подразделений тоже. description: |
При значении `true` в выборку включаются также сотрудники
вложенных подразделений.
userGroupsId: userGroupsId:
type: array type: array
description: UUID статических групп сотрудников. description: Список идентификаторов статических групп сотрудников.
items: items:
type: string type: string
format: uuid format: uuid
userGroupConditions: userGroupConditions:
type: array type: array
description: | description: |
Динамические условия выборки (как в админке UserGroup). Каждый Динамические условия выборки. Каждый элемент — объект
элемент — объект `{condition, operator, values}`. со структурой `{condition, operator, values}`.
items: items:
type: object type: object
employmentStatuses: employmentStatuses:
@@ -12954,7 +12999,9 @@ components:
type: string type: string
format: uuid format: uuid
nullable: true nullable: true
description: UUID `FileProcessing` с распарсенным xlsx — выборка возьмётся оттуда. description: |
Идентификатор записи `FileProcessing` с результатом обработки
xlsx-файла. При указании выборка формируется из этого результата.
UserListCacheSetBody: UserListCacheSetBody:
type: object type: object
@@ -12964,45 +13011,49 @@ components:
type: string type: string
maxLength: 50 maxLength: 50
description: | description: |
Произвольный идентификатор выборки. Этот же ключ потом передаётся Идентификатор выборки. Формируется клиентом. То же значение
как `usersListKey` в массовые операции. передаётся в методы массовых операций в качестве `usersListKey`.
example: "my-integration-2026-05-22" example: "integration-key-2026-05-22"
userList: userList:
$ref: '#/components/schemas/UserListForm' $ref: '#/components/schemas/UserListForm'
UserListData: UserListData:
type: object type: object
description: | description: |
Развёрнутый состав выборки. Возвращается `GET /user-list-cache/user-list-data`. Развёрнутый состав сохранённой выборки. Возвращается
в ответе `GET /user-list-cache/user-list-data`.
properties: properties:
userList: userList:
$ref: '#/components/schemas/UserListForm' $ref: '#/components/schemas/UserListForm'
users: users:
type: array type: array
description: Развёрнутые юзеры из выборки (с `faceUrl`). description: Пользователи, входящие в выборку.
items: items:
type: object type: object
departments: departments:
type: array type: array
description: Развёрнутые подразделения. description: Подразделения, указанные в выборке.
items: items:
type: object type: object
userGroups: userGroups:
type: array type: array
description: Развёрнутые группы. description: Группы, указанные в выборке.
items: items:
type: object type: object
userGroupConditions: userGroupConditions:
type: array type: array
description: Динамические условия выборки.
items: items:
type: object type: object
userGroupConditionsReadable: userGroupConditionsReadable:
type: array type: array
description: Динамические условия выборки в текстовом представлении.
items: items:
type: object type: object
userGroupConditionValues: userGroupConditionValues:
type: array type: array
nullable: true nullable: true
description: Значения, разрешённые в динамических условиях выборки.
items: items:
type: object type: object
fileProcessing: fileProcessing:
@@ -13012,48 +13063,69 @@ components:
File: File:
type: object type: object
description: Запись файла в HRBox. Полная схема (используется в prepare/finish-upload и nested-объектах). description: Запись о файле, хранящемся в HRBox.
properties: properties:
id: { type: string, format: uuid } id: { type: string, format: uuid }
name: { type: string, description: 'Оригинальное имя файла, например `wallet_import.xlsx`.' } name:
ext: { type: string, description: 'Расширение без точки.' } type: string
description: 'Имя файла. Пример: `wallet_import.xlsx`.'
ext:
type: string
description: Расширение файла без точки.
fid: fid:
type: string type: string
description: 'Внутренний идентификатор файла в хранилище (обычно `<id>.<ext>`).' description: |
Внутренний идентификатор файла в хранилище.
Обычно имеет вид `<id>.<ext>`.
url: url:
type: string type: string
format: uri format: uri
description: 'Публичный URL вида `https://<tenant>/file/open/<fid>`.' description: |
Публичный URL для доступа к файлу.
Имеет вид `https://<домен-тенанта>/file/open/<fid>`.
file_type: file_type:
type: string type: string
enum: [image, video, document, archive, other] enum: [image, video, document, archive, other]
mime_type: { type: string } description: Тип содержимого файла.
mime_type:
type: string
description: MIME-тип файла.
size: size:
type: integer type: integer
description: Размер в байтах. description: Размер файла в байтах.
file_status_id: file_status_id:
type: integer type: integer
description: | description: |
Статус загрузки: Статус загрузки файла. Допустимые значения:
* `1` — PREPARED (создан, бинарник не загружен) * `1` — PREPARED, запись создана, содержимое не загружено;
* `5` — UPLOADED (готов к использованию) * `5` — UPLOADED, файл загружен и доступен для использования;
* другие значения — внутренние состояния обработки * иные значения соответствуют внутренним состояниям обработки.
is_public: { type: boolean } is_public:
is_common: { type: boolean } type: boolean
is_system: { type: boolean } description: Доступность файла без авторизации.
is_common:
type: boolean
description: Признак общего файла.
is_system:
type: boolean
description: Признак системного файла.
meta: meta:
type: object type: object
nullable: true nullable: true
description: 'Произвольные метаданные (width/height для картинок и т.п.).' description: |
Произвольные метаданные файла (например, размеры изображения).
created_at: { type: string } created_at: { type: string }
user_id: user_id:
type: string type: string
format: uuid format: uuid
description: UUID юзера-загрузчика. description: Идентификатор пользователя, загрузившего файл.
chat_channel_id: chat_channel_id:
type: string type: string
format: uuid format: uuid
nullable: true nullable: true
description: |
Идентификатор канала чата, к которому привязан файл,
если применимо.
FilePrepareUploadBody: FilePrepareUploadBody:
type: object type: object
@@ -13061,33 +13133,42 @@ components:
properties: properties:
name: name:
type: string type: string
description: Имя файла.
example: "wallet_import.xlsx" example: "wallet_import.xlsx"
ext: ext:
type: string type: string
description: Расширение файла без точки.
example: "xlsx" example: "xlsx"
size: size:
type: integer type: integer
description: Размер в байтах. description: Размер файла в байтах.
example: 5120 example: 5120
file_type: file_type:
type: string type: string
enum: [image, video, document, archive, other] enum: [image, video, document, archive, other]
description: Тип содержимого файла.
example: document example: document
mime_type: mime_type:
type: string type: string
description: MIME-тип файла.
example: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" example: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
is_public: is_public:
type: integer type: boolean
description: '`1` если файл должен быть доступен без авторизации (фото и т.п.), `0` — приватный.' default: false
enum: [0, 1] description: |
default: 0 При значении `true` файл доступен без авторизации.
Используется, например, для изображений профиля.
meta: meta:
type: object type: object
description: 'Произвольные метаданные (например `{"width":100,"height":100}` для картинок).' description: |
Произвольные метаданные файла. Например, для изображений
могут передаваться размеры: `{"width": 100, "height": 100}`.
id: id:
type: string type: string
format: uuid format: uuid
description: 'Опционально. Если передать существующий `id`, вернётся та же запись (идемпотентность).' description: |
Идентификатор существующей записи о файле. При передаче
возвращается имеющаяся запись (идемпотентное поведение).
FilePrepareUploadResponse: FilePrepareUploadResponse:
type: object type: object
@@ -13097,15 +13178,16 @@ components:
uploadInfo: uploadInfo:
type: object type: object
description: | description: |
Информация для PUT-загрузки бинарника. Отсутствует, если файл Сведения для загрузки содержимого файла. Поле отсутствует
уже UPLOADED (повторный prepare-upload с тем же `id`). в ответе, если файл уже находится в статусе UPLOADED.
properties: properties:
signedUrl: signedUrl:
type: string type: string
format: uri format: uri
description: | description: |
Временный URL для PUT-запроса с телом-бинарником. Временная подписанная ссылка для PUT-запроса с содержимым
Не требует HRBox-авторизации — это прямая ссылка на S3. файла. Запрос выполняется напрямую в объектное хранилище
и не требует авторизации HRBox.
UserApiTokenStatus: UserApiTokenStatus:
type: integer type: integer