diff --git a/v2/swagger.yaml b/v2/swagger.yaml index c29476c..03713c2 100644 --- a/v2/swagger.yaml +++ b/v2/swagger.yaml @@ -73,6 +73,8 @@ tags: description: Methods for managing personal API tokens (PATs) for server-to-server access. Requires "api-tokens-manage" permission. - 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 administrative read-only access to employee employments, including external identifiers used by integrations. Requires "user-edit" permission. paths: /mobile/bind/{id}/{token}: @@ -7529,6 +7531,225 @@ paths: 404: description: Токен не найден. + /admin/employment: + get: + tags: [admin-employment] + summary: Получить список трудоустройств + description: | + Возвращает постраничный список трудоустройств тенанта с поддержкой + фильтрации, сортировки и пагинации. Состав возвращаемых полей и + набор параметров фильтрации соответствуют существующему эндпоинту + `/api/employment` версии 1. + + ## Получение идентификатора пользователя по внешнему ключу + + Основной сценарий использования для интеграций — получение + идентификатора пользователя HRBox (`user_id`) по внешнему + идентификатору должности из системы-источника + (`origin_id`, `origin_organization_id`). + + Пример запроса: + + ``` + GET /api/v2/admin/employment + ?origin_id=12345 + &origin_organization_id=default + ``` + + В поле `data[].user_id` возвращается идентификатор пользователя + в формате UUID версии 4, который может быть использован + в последующих обращениях к v2 API. Поддерживается передача + нескольких значений через массив: + `?origin_id[]=...&origin_id[]=...`. + + ## Множественные трудоустройства + + У одного пользователя может быть несколько трудоустройств + с различными значениями `origin_id`. Признак основного + трудоустройства передаётся в поле `is_main`. + + ## Завершённые трудоустройства + + Записи с заполненным полем `fired_date` включены в выдачу + по умолчанию. Для исключения завершённых трудоустройств + используйте фильтр `status_id`. + operationId: adminEmploymentIndex + parameters: + - name: page + in: query + schema: { type: integer, minimum: 1, default: 1 } + - name: per-page + in: query + schema: { type: integer, minimum: 1, default: 20 } + - name: sort + in: query + schema: { type: string } + 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: + oneOf: + - type: string + format: uuid + - type: array + items: { type: string, format: uuid } + description: | + Идентификатор пользователя. Допускается передача нескольких значений + в виде массива `?user_id[]=...&user_id[]=...` либо в виде строки + со значениями, разделёнными запятой. + - name: chief_id + in: query + schema: { type: string, format: uuid } + description: Идентификатор трудоустройства руководителя. + - name: department_id + in: query + schema: { type: string, format: uuid } + description: | + Идентификатор подразделения. Фильтр учитывает все вложенные + подразделения иерархии. + - name: origin_id + in: query + schema: + oneOf: + - type: string + - type: array + items: { type: string } + description: | + Внешний идентификатор должности из системы-источника. Допускается + передача нескольких значений в виде массива либо строки + со значениями, разделёнными запятой. + - name: origin_organization_id + in: query + schema: { type: string } + description: | + Идентификатор организации в системе-источнике. Применяется + в сочетании с `origin_id` для однозначного сопоставления записи. + - name: org_num + 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: name + in: query + schema: { type: string } + description: | + Поиск по полю `name` пользователя (имя и фамилия), + регистронезависимое частичное совпадение. + - name: position + in: query + schema: { type: string } + description: Поиск по должности, регистронезависимое частичное совпадение. + - name: is_main + in: query + schema: { type: boolean } + description: Признак основного трудоустройства. + - name: status_id + in: query + schema: { type: integer } + description: | + Статус трудоустройства. Допустимые значения: + `1` — действующее, `2` — отключённое. + - name: reg_status_id + in: query + schema: { type: string } + description: | + Статус регистрации пользователя-владельца трудоустройства. + Допустимые значения: `1` — без аккаунта, `2` — приглашён, + `3` — активен, `4` — заблокирован. Допускается передача + нескольких значений через запятую. + - name: created_at + in: query + schema: { type: string } + description: | + Период создания записи в формате `<начало>|<конец>`, + где даты указаны по ISO 8601. + - name: employment_date + in: query + schema: { type: string } + description: | + Период даты приёма на работу в формате `<начало>|<конец>`. + - name: fired_date + in: query + schema: { type: string } + description: | + Период даты увольнения в формате `<начало>|<конец>`. + - name: user_list_key + in: query + schema: { type: string, format: uuid } + description: | + Ключ закэшированной выборки пользователей, полученный + от `/user-list-cache/set-user-list`. + - name: chief_only + in: query + schema: { type: boolean } + description: | + Ограничить выборку прямыми подчинёнными текущего пользователя. + - name: chief_only_all + in: query + schema: { type: boolean } + description: | + Ограничить выборку всеми подчинёнными текущего пользователя + с учётом вложенной иерархии. + - name: multipleEmployment + in: query + schema: { type: boolean } + description: | + Ограничить выборку пользователями, у которых более одного + трудоустройства. + responses: + 200: + description: Список трудоустройств. + content: + application/json: + schema: + $ref: '#/components/schemas/AdminEmploymentList' + 403: + description: | + У текущего пользователя отсутствует право `user-edit`. + + /admin/employment/view: + get: + tags: [admin-employment] + summary: Получить трудоустройство по идентификатору + operationId: adminEmploymentView + parameters: + - name: id + in: query + required: true + schema: { type: string, format: uuid } + responses: + 200: + description: Запись трудоустройства. + content: + application/json: + schema: + $ref: '#/components/schemas/AdminEmployment' + 400: + description: Параметр `id` имеет некорректный формат. + 403: + description: | + У текущего пользователя отсутствует право `user-edit`. + 404: + description: | + Запись не найдена. Включает случаи обращения к записям, + принадлежащим другим тенантам. + components: securitySchemes: SessionAuth: @@ -12647,6 +12868,182 @@ components: _meta: $ref: '#/components/schemas/_meta' + AdminEmploymentUserShort: + type: object + properties: + id: { type: string, format: uuid } + name: { type: string, nullable: true } + faceUrl: { type: string, format: uri, nullable: true } + + AdminEmploymentChiefUserShort: + type: object + properties: + id: { type: string, format: uuid } + name: { type: string, nullable: true } + + AdminEmploymentDepartmentShort: + type: object + properties: + id: { type: string, format: uuid } + name: { type: string, nullable: true } + departmentPath: + type: string + nullable: true + description: 'Полный путь от корня структуры через `/`.' + + AdminEmployment: + type: object + description: | + Запись трудоустройства в административной выдаче. Содержит поля + самого трудоустройства, а также связанные объекты пользователя, + руководителя и подразделения. + properties: + id: + type: string + format: uuid + description: Идентификатор трудоустройства. + is_main: + type: boolean + description: | + Признак основного трудоустройства. Для пользователя с несколькими + трудоустройствами только одна запись имеет значение `true`. + user_id: + type: string + format: uuid + description: | + Идентификатор пользователя-владельца трудоустройства. Используется + для последующих обращений к v2 API, ожидающих `user_id`. + chief_id: + type: string + format: uuid + nullable: true + 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 8601. + fired_date: + type: string + nullable: true + description: | + Дата увольнения в формате ISO 8601. Поле имеет значение `null` + для действующих трудоустройств. + status_id: + type: integer + nullable: true + description: | + Статус трудоустройства. Допустимые значения: `1` — действующее, + `2` — отключённое. + origin_id: + type: string + nullable: true + description: | + Внешний идентификатор должности из системы-источника. + origin_organization_id: + type: string + nullable: true + description: | + Идентификатор организации в системе-источнике. Однозначное + сопоставление записи определяется парой + (`origin_id`, `origin_organization_id`). + org_num: + type: string + nullable: true + description: Табельный номер. + 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 + description: Дата создания записи. + updated_at: + type: string + nullable: true + description: Дата последнего изменения записи. + experience: + type: string + nullable: true + description: | + Стаж работы в текстовом представлении (например, + «15 years 3 months 19 days»). + name: + type: string + nullable: true + 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: + allOf: + - $ref: '#/components/schemas/AdminEmploymentChiefUserShort' + nullable: true + department: + allOf: + - $ref: '#/components/schemas/AdminEmploymentDepartmentShort' + nullable: true + createdAt: + type: string + nullable: true + description: Дата создания записи в локализованном представлении. + employmentDate: + type: string + nullable: true + description: Дата приёма на работу в локализованном представлении. + firedDate: + type: string + nullable: true + description: Дата увольнения в локализованном представлении. + statusName: + type: string + nullable: true + description: Локализованное наименование статуса. + + AdminEmploymentList: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/AdminEmployment' + _links: + $ref: '#/components/schemas/_links' + _meta: + $ref: '#/components/schemas/_meta' + parameters: boardDateTypeParam: in: query