v2/swagger.yaml

@@ -74,7 +74,7 @@ tags:
   - name: admin-user-api-token
     description: Methods for admin oversight of personal API tokens. Requires "api-tokens-admin" permission.
   - name: admin-employment
-    description: Methods for admin read-only access to employee employments — primary source of origin_id ↔ user_id mapping for integrations. Requires "user-edit" permission.
+    description: Methods for administrative read-only access to employee employments, including external identifiers used by integrations. Requires "user-edit" permission.
 
 paths:
   /mobile/bind/{id}/{token}:
@@ -7534,15 +7534,21 @@ paths:
   /admin/employment:
     get:
       tags: [admin-employment]
-      summary: Список трудоустройств — admin read-only
+      summary: Получить список трудоустройств
       description: |
-        Постраничный список трудоустройств всего тенанта с фильтрами
-        `EmploymentSearch`. Поведением и набором полей идентичен
-        legacy-эндпоинту `/api/employment` (v1) — перенесён в v2 как
-        основа для интеграций (web-zaim, sokolove и др.) и будущей
-        Vue3-админки.
+        Возвращает постраничный список трудоустройств тенанта с поддержкой
+        фильтрации, сортировки и пагинации. Состав возвращаемых полей и
+        набор параметров фильтрации соответствуют существующему эндпоинту
+        `/api/employment` версии 1.
 
-        ### Главный кейс — маппинг (origin_id, origin_organization_id) → user_id
+        ## Получение идентификатора пользователя по внешнему ключу
+
+        Основной сценарий использования для интеграций — получение
+        идентификатора пользователя HRBox (`user_id`) по внешнему
+        идентификатору должности из системы-источника
+        (`origin_id`, `origin_organization_id`).
+
+        Пример запроса:
 
         ```
         GET /api/v2/admin/employment
@@ -7550,20 +7556,23 @@ paths:
             &origin_organization_id=default
         ```
 
-        В ответе `data[].user_id` — это родной HRBox UUIDv4 пользователя,
-        который дальше можно передавать в любые v2-эндпоинты, ожидающие
-        `user_id`. Поддерживается батч: `?origin_id[]=...&origin_id[]=...`.
+        В поле `data[].user_id` возвращается идентификатор пользователя
+        в формате UUID версии 4, который может быть использован
+        в последующих обращениях к v2 API. Поддерживается передача
+        нескольких значений через массив:
+        `?origin_id[]=...&origin_id[]=...`.
 
-        ### Совместительства
+        ## Множественные трудоустройства
 
-        Один пользователь может иметь несколько трудоустройств с разными
-        `origin_id`. Поле `is_main` отличает основное от дополнительных.
+        У одного пользователя может быть несколько трудоустройств
+        с различными значениями `origin_id`. Признак основного
+        трудоустройства передаётся в поле `is_main`.
 
-        ### Уволенные
+        ## Завершённые трудоустройства
 
-        Записи с `fired_date != null` включены по умолчанию — нужны для
-        синхронизации увольнений. Если нужны только активные —
-        фильтруйте `status_id=1`.
+        Записи с заполненным полем `fired_date` включены в выдачу
+        по умолчанию. Для исключения завершённых трудоустройств
+        используйте фильтр `status_id`.
       operationId: adminEmploymentIndex
       parameters:
         - name: page
@@ -7575,10 +7584,14 @@ paths:
         - name: sort
           in: query
           schema: { type: string }
-          description: 'Префикс `-` для DESC. Атрибуты — `created_at`, `employment_date`, `fired_date`, и др. (по `EmploymentSearch::sort`).'
+          description: |
+            Поле сортировки. Для сортировки по убыванию используется префикс `-`.
+            Допустимые поля: `created_at`, `employment_date`, `fired_date` и другие
+            атрибуты, определённые в `EmploymentSearch::sort()`.
         - name: id
           in: query
           schema: { type: string, format: uuid }
+          description: Идентификатор трудоустройства.
         - name: user_id
           in: query
           schema:
@@ -7587,15 +7600,20 @@ paths:
                 format: uuid
               - type: array
                 items: { type: string, format: uuid }
-          description: 'UUID юзера. Массив через `?user_id[]=...&user_id[]=...` или comma-separated.'
+          description: |
+            Идентификатор пользователя. Допускается передача нескольких значений
+            в виде массива `?user_id[]=...&user_id[]=...` либо в виде строки
+            со значениями, разделёнными запятой.
         - name: chief_id
           in: query
           schema: { type: string, format: uuid }
-          description: UUID employment'а руководителя.
+          description: Идентификатор трудоустройства руководителя.
         - name: department_id
           in: query
           schema: { type: string, format: uuid }
-          description: UUID подразделения (с автоматическим учётом поддерева).
+          description: |
+            Идентификатор подразделения. Фильтр учитывает все вложенные
+            подразделения иерархии.
         - name: origin_id
           in: query
           schema:
@@ -7603,85 +7621,112 @@ paths:
               - type: string
               - type: array
                 items: { type: string }
-          description: Внешний ID (например из 1С). Comma-separated или массив.
+          description: |
+            Внешний идентификатор должности из системы-источника. Допускается
+            передача нескольких значений в виде массива либо строки
+            со значениями, разделёнными запятой.
         - name: origin_organization_id
           in: query
           schema: { type: string }
-          description: Идентификатор организации во внешней системе (для мульти-org тенантов).
+          description: |
+            Идентификатор организации в системе-источнике. Применяется
+            в сочетании с `origin_id` для однозначного сопоставления записи.
         - name: org_num
           in: query
           schema: { type: string }
-          description: Comma-separated табельные номера.
+          description: |
+            Табельный номер. Допускается передача нескольких значений
+            в виде строки, разделённой запятой.
         - name: first_name
           in: query
           schema: { type: string }
-          description: ilike-поиск.
+          description: Поиск по имени, регистронезависимое частичное совпадение.
         - name: last_name
           in: query
           schema: { type: string }
-          description: ilike-поиск.
+          description: Поиск по фамилии, регистронезависимое частичное совпадение.
         - name: name
           in: query
           schema: { type: string }
-          description: ilike по `first_name` + `last_name` через JOIN User.
+          description: |
+            Поиск по полю `name` пользователя (имя и фамилия),
+            регистронезависимое частичное совпадение.
         - name: position
           in: query
           schema: { type: string }
-          description: ilike-поиск по должности.
+          description: Поиск по должности, регистронезависимое частичное совпадение.
         - name: is_main
           in: query
           schema: { type: boolean }
-          description: Только основные трудоустройства.
+          description: Признак основного трудоустройства.
         - name: status_id
           in: query
           schema: { type: integer }
-          description: 'Стандартный enum `Status` (1=Active, 2=Disabled).'
+          description: |
+            Статус трудоустройства. Допустимые значения:
+            `1` — действующее, `2` — отключённое.
         - 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: created_at
           in: query
           schema: { type: string }
-          description: 'Диапазон `from|to` (ISO).'
+          description: |
+            Период создания записи в формате `<начало>|<конец>`,
+            где даты указаны по ISO 8601.
         - name: employment_date
           in: query
           schema: { type: string }
-          description: 'Диапазон даты приёма `from|to`.'
+          description: |
+            Период даты приёма на работу в формате `<начало>|<конец>`.
         - name: fired_date
           in: query
           schema: { type: string }
-          description: 'Диапазон даты увольнения `from|to`.'
+          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: chief_only
           in: query
           schema: { type: boolean }
-          description: Только прямые подчинённые текущего юзера.
+          description: |
+            Ограничить выборку прямыми подчинёнными текущего пользователя.
         - name: chief_only_all
           in: query
           schema: { type: boolean }
-          description: Все подчинённые рекурсивно.
+          description: |
+            Ограничить выборку всеми подчинёнными текущего пользователя
+            с учётом вложенной иерархии.
         - name: multipleEmployment
           in: query
           schema: { type: boolean }
-          description: Только записи юзеров с несколькими трудоустройствами.
+          description: |
+            Ограничить выборку пользователями, у которых более одного
+            трудоустройства.
       responses:
         200:
-          description: Список трудоустройств
+          description: Список трудоустройств.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AdminEmploymentList'
         403:
-          description: Нет права `user-edit`.
+          description: |
+            У текущего пользователя отсутствует право `user-edit`.
 
   /admin/employment/view:
     get:
       tags: [admin-employment]
-      summary: Одно трудоустройство — admin read-only
+      summary: Получить трудоустройство по идентификатору
       operationId: adminEmploymentView
       parameters:
         - name: id
@@ -7690,17 +7735,20 @@ paths:
           schema: { type: string, format: uuid }
       responses:
         200:
-          description: Трудоустройство
+          description: Запись трудоустройства.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AdminEmployment'
         400:
-          description: Невалидный UUID.
+          description: Параметр `id` имеет некорректный формат.
         403:
-          description: Нет права `user-edit`.
+          description: |
+            У текущего пользователя отсутствует право `user-edit`.
         404:
-          description: Запись не найдена (включая cross-tenant).
+          description: |
+            Запись не найдена. Включает случаи обращения к записям,
+            принадлежащим другим тенантам.
 
 components:
   securitySchemes:
@@ -12846,82 +12894,117 @@ components:
     AdminEmployment:
       type: object
       description: |
-        Запись трудоустройства в admin-выдаче. Содержит как сырые поля
-        Employment, так и связанные `user` / `chiefUser` / `department`.
+        Запись трудоустройства в административной выдаче. Содержит поля
+        самого трудоустройства, а также связанные объекты пользователя,
+        руководителя и подразделения.
       properties:
         id:
           type: string
           format: uuid
-          description: UUID трудоустройства (родной HRBox).
+          description: Идентификатор трудоустройства.
         is_main:
           type: boolean
-          description: Основное трудоустройство (одно на юзера). Несколько `false` — совместительства.
+          description: |
+            Признак основного трудоустройства. Для пользователя с несколькими
+            трудоустройствами только одна запись имеет значение `true`.
         user_id:
           type: string
           format: uuid
-          description: UUID владельца (`hr_user.id`) — **то самое значение для маппинга origin → user**.
+          description: |
+            Идентификатор пользователя-владельца трудоустройства. Используется
+            для последующих обращений к v2 API, ожидающих `user_id`.
         chief_id:
           type: string
           format: uuid
           nullable: true
-          description: UUID employment'а руководителя (не User'а).
+          description: |
+            Идентификатор трудоустройства руководителя. Ссылается на запись
+            `Employment`, а не на `User`.
         department_id:
           type: string
           format: uuid
           nullable: true
+          description: Идентификатор подразделения.
         position:
           type: string
           nullable: true
+          description: Должность.
         employment_date:
           type: string
           nullable: true
-          description: Дата приёма (ISO).
+          description: Дата приёма на работу в формате ISO 8601.
         fired_date:
           type: string
           nullable: true
-          description: Дата увольнения (ISO). `null` для действующих.
+          description: |
+            Дата увольнения в формате ISO 8601. Поле имеет значение `null`
+            для действующих трудоустройств.
         status_id:
           type: integer
           nullable: true
-          description: 'Стандартный `Status` (1=Active, 2=Disabled).'
+          description: |
+            Статус трудоустройства. Допустимые значения: `1` — действующее,
+            `2` — отключённое.
         origin_id:
           type: string
           nullable: true
-          description: Внешний идентификатор должности из системы-источника (1С и т.п.).
+          description: |
+            Внешний идентификатор должности из системы-источника.
         origin_organization_id:
           type: string
           nullable: true
-          description: Идентификатор внешней организации. Маппинг — это **пара** `(origin_id, origin_organization_id)`.
+          description: |
+            Идентификатор организации в системе-источнике. Однозначное
+            сопоставление записи определяется парой
+            (`origin_id`, `origin_organization_id`).
         org_num:
           type: string
           nullable: true
           description: Табельный номер.
-        first_name: { type: string, nullable: true }
-        last_name: { type: string, nullable: true }
+        first_name:
+          type: string
+          nullable: true
+          description: Имя пользователя.
+        last_name:
+          type: string
+          nullable: true
+          description: Фамилия пользователя.
         photo:
           type: string
           nullable: true
-          description: Имя файла фото из источника (если приходит из интеграции).
-        created_at: { type: string, nullable: true }
-        updated_at: { type: string, nullable: true }
+          description: |
+            Имя файла фотографии, полученное от системы-источника.
+        created_at:
+          type: string
+          nullable: true
+          description: Дата создания записи.
+        updated_at:
+          type: string
+          nullable: true
+          description: Дата последнего изменения записи.
         experience:
           type: string
           nullable: true
-          description: 'Стаж в человекочитаемом виде (например `15 years 3 months 19 days`).'
+          description: |
+            Стаж работы в текстовом представлении (например,
+            «15 years 3 months 19 days»).
         name:
           type: string
           nullable: true
-          description: Готовая строка ФИО юзера-владельца.
+          description: Имя и фамилия пользователя-владельца трудоустройства.
         nameDetails:
           type: string
           nullable: true
+          description: Расширенное представление имени пользователя.
         iconUrl:
           type: string
           format: uri
           nullable: true
+          description: URL изображения пользователя.
         profilePosition:
           type: string
           nullable: true
+          description: Должность для отображения в профиле пользователя.
         user:
           $ref: '#/components/schemas/AdminEmploymentUserShort'
         chiefUser:
@@ -12935,19 +13018,19 @@ components:
         createdAt:
           type: string
           nullable: true
-          description: 'Локализованная `created_at`.'
+          description: Дата создания записи в локализованном представлении.
         employmentDate:
           type: string
           nullable: true
-          description: 'Локализованная `employment_date`.'
+          description: Дата приёма на работу в локализованном представлении.
         firedDate:
           type: string
           nullable: true
-          description: 'Локализованная `fired_date`.'
+          description: Дата увольнения в локализованном представлении.
         statusName:
           type: string
           nullable: true
-          description: 'Локализованное имя статуса.'
+          description: Локализованное наименование статуса.
 
     AdminEmploymentList:
       type: object