v2/swagger.yaml

@@ -564,25 +564,20 @@ paths:
     get:
       tags:
         - user
-      summary: Список сотрудников
+      summary: Получить список сотрудников
       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
       parameters:
         - name: page
@@ -594,11 +589,14 @@ paths:
         - name: sort
           in: query
           schema: { type: string }
-          description: 'Префикс `-` для DESC. Например `-created_at`, `name`, `-last_login_at`.'
+          description: |
+            Поле сортировки. Для сортировки по убыванию используется префикс `-`.
+            Примеры: `-created_at`, `name`, `-last_login_at`.
         - name: searchQuery
           in: query
           schema: { type: string }
-          description: Сквозной поиск по ФИО / e-mail / телефону / должности.
+          description: |
+            Сквозной поиск по имени, фамилии, e-mail, телефону и должности.
         - name: id
           in: query
           schema:
@@ -607,35 +605,45 @@ paths:
                 format: uuid
               - type: array
                 items: { type: string, format: uuid }
-          description: 'Фильтр по конкретным UUID. Можно массив через `?id[]=...&id[]=...`.'
+          description: |
+            Идентификатор пользователя. Допускается передача нескольких
+            значений в виде массива `?id[]=...&id[]=...`.
         - name: not_id
           in: query
           schema: { type: string, format: uuid }
-          description: Исключить конкретного юзера.
+          description: Исключить пользователя с указанным идентификатором.
         - name: email
           in: query
           schema: { type: string }
+          description: Поиск по электронной почте.
         - name: phone_auth
           in: query
           schema: { type: string }
+          description: Поиск по номеру телефона.
         - name: name
           in: query
           schema: { type: string }
+          description: Поиск по полному имени.
         - name: first_name
           in: query
           schema: { type: string }
+          description: Поиск по имени.
         - name: last_name
           in: query
           schema: { type: string }
+          description: Поиск по фамилии.
         - name: middle_name
           in: query
           schema: { type: string }
+          description: Поиск по отчеству.
         - name: position
           in: query
           schema: { type: string }
+          description: Поиск по должности.
         - name: company
           in: query
           schema: { type: string }
+          description: Поиск по наименованию компании.
         - name: department_id
           in: query
           schema:
@@ -644,51 +652,68 @@ paths:
                 format: uuid
               - type: array
                 items: { type: string, format: uuid }
+          description: Идентификатор подразделения.
         - name: reg_status_id
           in: query
           schema: { type: string }
-          description: Comma-separated `RegStatus` (1=NO_ACCOUNT, 2=INVITED, 3=ACTIVE, 4=BLOCKED).
+          description: |
+            Статус регистрации пользователя. Допустимые значения:
+            `1` — без аккаунта, `2` — приглашён, `3` — активен,
+            `4` — заблокирован. Допускается передача нескольких значений
+            через запятую.
         - name: gender_id
           in: query
           schema: { type: string }
+          description: Идентификатор пола.
         - name: is_boss
           in: query
           schema: { type: boolean }
+          description: Признак руководящей должности.
         - name: is_external
           in: query
           schema: { type: boolean }
+          description: Признак внешнего сотрудника.
         - name: group_id
           in: query
           schema: { type: string, format: uuid }
-          description: Фильтр по статической группе сотрудников.
+          description: Идентификатор группы сотрудников.
         - name: duty_id
           in: query
           schema: { type: string, format: uuid }
+          description: Идентификатор обязанности.
         - name: spec_id
           in: query
           schema: { type: string, format: uuid }
+          description: Идентификатор специализации.
         - name: created_at
           in: query
           schema: { type: string }
-          description: 'Диапазон `from|to` (ISO).'
+          description: |
+            Период создания записи в формате `<начало>|<конец>`,
+            где даты указаны по ISO 8601.
         - name: last_login_at
           in: query
           schema: { type: string }
-          description: 'Диапазон `from|to` (ISO).'
+          description: |
+            Период последнего входа в систему в формате `<начало>|<конец>`.
         - name: user_list_key
           in: query
           schema: { type: string, format: uuid }
-          description: 'Ключ закэшированной выборки (см. `/user-list-cache/set-user-list`).'
+          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`,
+            значения: `isBoss`, `faceUrl`, `iconUrl`, `photoUrl`,
-            `profileCorporateContacts`, `isFavoriteUser`, `contacts`, `statusTypes`.
+            `employment`, `cityName`, `statusText`,
+            `profileCorporateContacts`, `isFavoriteUser`, `contacts`,
+            `statusTypes`.
       responses:
         200:
-          description: Список сотрудников
+          description: Список сотрудников.
           content:
             application/json:
               schema:
@@ -703,37 +728,41 @@ paths:
                   _meta:
                     $ref: '#/components/schemas/_meta'
         401:
-          description: Unauthorized.
+          description: Запрос не авторизован.
 
   /user/search:
     get:
       tags:
         - user
-      summary: Быстрый поиск сотрудников по строке
+      summary: Найти сотрудников по строке поиска
       description: |
-        Лёгкий компактный поиск — возвращает до `limit` юзеров с минимальным
+        Компактный поиск пользователей по строке. Возвращает до `limit`
-        набором полей (id, name, position, departmentName, isBoss, iconUrl,
+        записей с минимальным набором полей, достаточным для отображения
-        employmentId). Использует тот же `UserSearchLogic`, что и сквозной
+        в выпадающих списках и подсказках.
-        поиск UI.
 
-        Поле `users` будет пустым массивом, если у текущего юзера нет права
+        Поле `users` в ответе содержит пустой массив, если параметр `q`
-        `show-structure-names`. Также пустой массив, если `q` не передан или пустой.
+        не передан либо у текущего пользователя отсутствует право
+        `show-structure-names`.
       operationId: userSearch
       parameters:
         - name: q
           in: query
           required: true
           schema: { type: string, maxLength: 255 }
-          description: Строка поиска (ФИО / e-mail / должность / подразделение).
+          description: |
+            Строка поиска. Применяется к полному имени, электронной почте,
+            должности и наименованию подразделения.
         - name: limit
           in: query
-          schema: { type: integer, minimum: 1, maximum: 100, default: 10 }
+          schema: { type: integer, minimum: 1, default: 10 }
+          description: Максимальное количество возвращаемых записей.
         - name: offset
           in: query
           schema: { type: integer, minimum: 0, default: 0 }
+          description: Смещение выборки.
       responses:
         200:
-          description: Результаты поиска
+          description: Результаты поиска.
           content:
             application/json:
               schema:
@@ -7310,26 +7339,34 @@ paths:
   /admin/wallet-transaction/create:
     post:
       tags: [admin-wallet-transaction]
-      summary: Провести начисление/списание по форме
+      summary: Провести начисление или списание по форме
       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, не хватает
           баланса хотя бы у одного юзера; вся операция отменяется.
@@ -7487,34 +7524,36 @@ paths:
   /file/prepare-upload:
     post:
       tags: [file]
-      summary: Зарегистрировать файл и получить signed URL для загрузки
+      summary: Зарегистрировать файл и получить ссылку для загрузки
       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
       requestBody:
         required: true
@@ -7524,7 +7563,7 @@ paths:
               $ref: '#/components/schemas/FilePrepareUploadBody'
       responses:
         200:
-          description: Файл зарегистрирован, ссылка на загрузку готова
+          description: Файл зарегистрирован, ссылка для загрузки получена.
           content:
             application/json:
               schema:
@@ -7535,26 +7574,25 @@ paths:
       tags: [file]
       summary: Подтвердить завершение загрузки файла
       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
       parameters:
         - name: id
           in: query
           required: true
           schema: { type: string, format: uuid }
-          description: UUID файла, полученный из `prepare-upload`.
+          description: |
+            Идентификатор файла, полученный от `/file/prepare-upload`.
       responses:
         200:
-          description: Файл помечен как загруженный
+          description: Загрузка файла подтверждена.
           content:
             application/json:
               schema:
@@ -7563,34 +7601,35 @@ paths:
                   File:
                     $ref: '#/components/schemas/File'
         400:
-          description: Не передан id или невалидный UUID.
+          description: Параметр `id` не передан или имеет некорректный формат.
         404:
-          description: Файл с таким id не найден.
+          description: Файл с указанным идентификатором не найден.
 
   /user-list-cache/set-user-list:
     post:
       tags: [user-list-cache]
-      summary: Закэшировать выборку сотрудников и получить ключ
+      summary: Сохранить выборку сотрудников и получить её идентификатор
       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
         POST /api/v2/user-list-cache/set-user-list
@@ -7598,14 +7637,15 @@ paths:
         Authorization: Bearer hrb_...
 
         {
-          "key": "my-integration-key-2026-05-22",
+          "key": "integration-key-2026-05-22",
           "userList": {
             "usersId": ["25840ad3-a07f-4893-aa70-3a696b79a6f1"]
           }
         }
         ```
 
-        `key` придумываете сами (до 50 символов).
+        Значение `key` формируется клиентом и может содержать
+        до 50 символов.
       operationId: userListCacheSet
       requestBody:
         required: true
@@ -7616,8 +7656,8 @@ paths:
       responses:
         200:
           description: |
-            Успех (`data: true`) или ошибки валидации в стандартном формате
+            Успешное сохранение выборки (`data: true`) либо ошибки валидации
-            `httpJsonResponse`.
+            в стандартном формате `httpJsonResponse`.
           content:
             application/json:
               schema:
@@ -7626,24 +7666,25 @@ paths:
   /user-list-cache/user-list-data:
     get:
       tags: [user-list-cache]
-      summary: Получить состав закэшированной выборки сотрудников
+      summary: Получить состав сохранённой выборки сотрудников
       description: |
-        Возвращает развёрнутый состав выборки по ключу: список пользователей
+        Возвращает развёрнутый состав выборки по её ключу, включая
-        (`users`), список подразделений (`departments`), список групп
+        списки пользователей, подразделений и групп, исходное описание
-        (`userGroups`), исходную форму (`userList`), нормализованные
+        выборки и нормализованные условия. Используется для
-        условия групп и т.д. Полезно для preview перед массовой операцией.
+        предварительного просмотра перед выполнением массовых операций.
 
-        Если ключ протух (24 ч) или не существует — `userList` будет
+        Если ключ не найден или срок его действия истёк, поле `userList`
-        пустым, остальные коллекции — пустыми массивами.
+        возвращается пустым, прочие коллекции — пустыми массивами.
       operationId: userListCacheData
       parameters:
         - name: key
           in: query
           required: true
           schema: { type: string, maxLength: 50 }
+          description: Идентификатор сохранённой выборки.
       responses:
         200:
-          description: Данные выборки
+          description: Состав выборки.
           content:
             application/json:
               schema:
@@ -12912,37 +12953,41 @@ components:
     UserListForm:
       type: object
       description: |
-        Описание выборки сотрудников. Все поля опциональны — указывайте те,
+        Описание выборки сотрудников. Все поля являются опциональными;
-        которыми хотите задать состав. Условия объединяются через OR
+        указанные критерии объединяются по логическому ИЛИ — пользователь
-        (любой из критериев включает юзера).
+        включается в выборку при соответствии хотя бы одному из них.
       properties:
         usersId:
           type: array
-          description: Явный список UUID сотрудников.
+          description: Список идентификаторов пользователей.
           items:
             type: string
             format: uuid
         departmentsId:
           type: array
-          description: UUID подразделений. Включает всех сотрудников этих подразделений.
+          description: |
+            Список идентификаторов подразделений. В выборку включаются
+            все сотрудники указанных подразделений.
           items:
             type: string
             format: uuid
         isDepartmentRecursive:
           type: boolean
           default: false
-          description: Если `true` — захватывает сотрудников вложенных подразделений тоже.
+          description: |
+            При значении `true` в выборку включаются также сотрудники
+            вложенных подразделений.
         userGroupsId:
           type: array
-          description: UUID статических групп сотрудников.
+          description: Список идентификаторов статических групп сотрудников.
           items:
             type: string
             format: uuid
         userGroupConditions:
           type: array
           description: |
-            Динамические условия выборки (как в админке UserGroup). Каждый
+            Динамические условия выборки. Каждый элемент — объект
-            элемент — объект `{condition, operator, values}`.
+            со структурой `{condition, operator, values}`.
           items:
             type: object
         employmentStatuses:
@@ -12954,7 +12999,9 @@ components:
           type: string
           format: uuid
           nullable: true
-          description: UUID `FileProcessing` с распарсенным xlsx — выборка возьмётся оттуда.
+          description: |
+            Идентификатор записи `FileProcessing` с результатом обработки
+            xlsx-файла. При указании выборка формируется из этого результата.
 
     UserListCacheSetBody:
       type: object
@@ -12964,45 +13011,49 @@ components:
           type: string
           maxLength: 50
           description: |
-            Произвольный идентификатор выборки. Этот же ключ потом передаётся
+            Идентификатор выборки. Формируется клиентом. То же значение
-            как `usersListKey` в массовые операции.
+            передаётся в методы массовых операций в качестве `usersListKey`.
-          example: "my-integration-2026-05-22"
+          example: "integration-key-2026-05-22"
         userList:
           $ref: '#/components/schemas/UserListForm'
 
     UserListData:
       type: object
       description: |
-        Развёрнутый состав выборки. Возвращается `GET /user-list-cache/user-list-data`.
+        Развёрнутый состав сохранённой выборки. Возвращается
+        в ответе `GET /user-list-cache/user-list-data`.
       properties:
         userList:
           $ref: '#/components/schemas/UserListForm'
         users:
           type: array
-          description: Развёрнутые юзеры из выборки (с `faceUrl`).
+          description: Пользователи, входящие в выборку.
           items:
             type: object
         departments:
           type: array
-          description: Развёрнутые подразделения.
+          description: Подразделения, указанные в выборке.
           items:
             type: object
         userGroups:
           type: array
-          description: Развёрнутые группы.
+          description: Группы, указанные в выборке.
           items:
             type: object
         userGroupConditions:
           type: array
+          description: Динамические условия выборки.
           items:
             type: object
         userGroupConditionsReadable:
           type: array
+          description: Динамические условия выборки в текстовом представлении.
           items:
             type: object
         userGroupConditionValues:
           type: array
           nullable: true
+          description: Значения, разрешённые в динамических условиях выборки.
           items:
             type: object
         fileProcessing:
@@ -13012,48 +13063,69 @@ components:
 
     File:
       type: object
-      description: Запись файла в HRBox. Полная схема (используется в prepare/finish-upload и nested-объектах).
+      description: Запись о файле, хранящемся в HRBox.
       properties:
         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:
           type: string
-          description: 'Внутренний идентификатор файла в хранилище (обычно `<id>.<ext>`).'
+          description: |
+            Внутренний идентификатор файла в хранилище.
+            Обычно имеет вид `<id>.<ext>`.
         url:
           type: string
           format: uri
-          description: 'Публичный URL вида `https://<tenant>/file/open/<fid>`.'
+          description: |
+            Публичный URL для доступа к файлу.
+            Имеет вид `https://<домен-тенанта>/file/open/<fid>`.
         file_type:
           type: string
           enum: [image, video, document, archive, other]
-        mime_type: { type: string }
+          description: Тип содержимого файла.
+        mime_type:
+          type: string
+          description: MIME-тип файла.
         size:
           type: integer
-          description: Размер в байтах.
+          description: Размер файла в байтах.
         file_status_id:
           type: integer
           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:
           type: object
           nullable: true
-          description: 'Произвольные метаданные (width/height для картинок и т.п.).'
+          description: |
+            Произвольные метаданные файла (например, размеры изображения).
         created_at: { type: string }
         user_id:
           type: string
           format: uuid
-          description: UUID юзера-загрузчика.
+          description: Идентификатор пользователя, загрузившего файл.
         chat_channel_id:
           type: string
           format: uuid
           nullable: true
+          description: |
+            Идентификатор канала чата, к которому привязан файл,
+            если применимо.
 
     FilePrepareUploadBody:
       type: object
@@ -13061,33 +13133,42 @@ components:
       properties:
         name:
           type: string
+          description: Имя файла.
           example: "wallet_import.xlsx"
         ext:
           type: string
+          description: Расширение файла без точки.
           example: "xlsx"
         size:
           type: integer
-          description: Размер в байтах.
+          description: Размер файла в байтах.
           example: 5120
         file_type:
           type: string
           enum: [image, video, document, archive, other]
+          description: Тип содержимого файла.
           example: document
         mime_type:
           type: string
+          description: MIME-тип файла.
           example: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
         is_public:
-          type: integer
+          type: boolean
-          description: '`1` если файл должен быть доступен без авторизации (фото и т.п.), `0` — приватный.'
+          default: false
-          enum: [0, 1]
+          description: |
-          default: 0
+            При значении `true` файл доступен без авторизации.
+            Используется, например, для изображений профиля.
         meta:
           type: object
-          description: 'Произвольные метаданные (например `{"width":100,"height":100}` для картинок).'
+          description: |
+            Произвольные метаданные файла. Например, для изображений
+            могут передаваться размеры: `{"width": 100, "height": 100}`.
         id:
           type: string
           format: uuid
-          description: 'Опционально. Если передать существующий `id`, вернётся та же запись (идемпотентность).'
+          description: |
+            Идентификатор существующей записи о файле. При передаче
+            возвращается имеющаяся запись (идемпотентное поведение).
 
     FilePrepareUploadResponse:
       type: object
@@ -13097,15 +13178,16 @@ components:
         uploadInfo:
           type: object
           description: |
-            Информация для PUT-загрузки бинарника. Отсутствует, если файл
+            Сведения для загрузки содержимого файла. Поле отсутствует
-            уже UPLOADED (повторный prepare-upload с тем же `id`).
+            в ответе, если файл уже находится в статусе UPLOADED.
           properties:
             signedUrl:
               type: string
               format: uri
               description: |
-                Временный URL для PUT-запроса с телом-бинарником.
+                Временная подписанная ссылка для PUT-запроса с содержимым
-                Не требует HRBox-авторизации — это прямая ссылка на S3.
+                файла. Запрос выполняется напрямую в объектное хранилище
+                и не требует авторизации HRBox.
 
     UserApiTokenStatus:
       type: integer