openapi: 3.0.3

info:
  title: HRBox API
  version: 1.0.0
  description: |
    API для чтения подразделений, трудоустройств и пользователей.

    Все методы требуют авторизованную сессию HRBox и соответствующее право доступа.
    Ответ содержит массив `data` и метаданные пагинации `_meta`.

servers:
  - url: /api

tags:
  - name: department
    description: Подразделения организационной структуры
  - name: employment
    description: Трудоустройства пользователей
  - name: user
    description: Пользователи

paths:
  /department:
    get:
      tags: [department]
      summary: Получить список подразделений
      operationId: getDepartments
      description: Возвращает активные подразделения и организации.
      x-permissions:
        - show-structure-page
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Expand'
        - name: id
          in: query
          description: ID подразделений через запятую
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: name
          in: query
          description: Поиск по названию
          schema:
            type: string
        - name: parent_id
          in: query
          description: ID родительского подразделения
          schema:
            type: string
            format: uuid
        - name: chief_id
          in: query
          description: ID руководителя
          schema:
            type: string
            format: uuid
        - name: is_organization
          in: query
          description: Признак организации
          schema:
            type: boolean
        - name: is_null_parent_id
          in: query
          description: Только корневые подразделения
          schema:
            type: boolean
        - name: status_id
          in: query
          description: Статусы подразделений через запятую
          style: form
          explode: false
          schema:
            type: array
            items:
              type: integer
        - name: chief_only
          in: query
          description: Только подразделения текущего руководителя
          schema:
            type: boolean
        - name: for_boss
          in: query
          description: Только управляемые текущим пользователем поддеревья
          schema:
            type: boolean
      responses:
        '200':
          description: Список подразделений
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Department'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /employment:
    get:
      tags: [employment]
      summary: Получить список трудоустройств
      operationId: getEmployments
      x-permissions:
        - user-edit
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Expand'
        - name: id
          in: query
          description: ID трудоустройства
          schema:
            type: string
            format: uuid
        - name: user_id
          in: query
          description: ID пользователя
          schema:
            type: string
            format: uuid
        - name: department_id
          in: query
          description: ID подразделения; учитывается его поддерево
          schema:
            type: string
            format: uuid
        - name: chief_id
          in: query
          description: ID трудоустройства руководителя
          schema:
            type: string
            format: uuid
        - name: position
          in: query
          description: Поиск по должности
          schema:
            type: string
        - name: is_main
          in: query
          description: Только основное трудоустройство
          schema:
            type: boolean
        - name: status_id
          in: query
          description: Статус трудоустройства
          schema:
            type: integer
        - name: org_num
          in: query
          description: Табельные номера через запятую
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: created_at
          in: query
          description: Дата или диапазон дат создания в формате `from|to`
          schema:
            type: string
        - name: first_name
          in: query
          description: Поиск по имени
          schema:
            type: string
        - name: last_name
          in: query
          description: Поиск по фамилии
          schema:
            type: string
        - name: name
          in: query
          description: Поиск по имени и фамилии пользователя
          schema:
            type: string
        - name: employment_date
          in: query
          description: Дата трудоустройства
          schema:
            type: string
            format: date
        - name: fired_date
          in: query
          description: Дата увольнения
          schema:
            type: string
            format: date
        - name: origin_id
          in: query
          description: Внешние ID через запятую
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: origin_organization_id
          in: query
          description: Внешний ID организации
          schema:
            type: string
        - name: reg_status_id
          in: query
          description: Регистрационные статусы пользователей через запятую
          style: form
          explode: false
          schema:
            type: array
            items:
              type: integer
        - name: user_list_key
          in: query
          description: Ключ сохранённого списка пользователей
          schema:
            type: string
            format: uuid
        - name: chief_only
          in: query
          description: Текущий пользователь и его прямые подчинённые
          schema:
            type: boolean
        - name: chief_only_all
          in: query
          description: Текущий пользователь и все его подчинённые
          schema:
            type: boolean
        - name: multipleEmployment
          in: query
          description: Фильтр по наличию нескольких трудоустройств
          schema:
            type: boolean
        - name: searchInAllSubDepartments
          in: query
          description: Искать во всех вложенных подразделениях
          schema:
            type: boolean
      responses:
        '200':
          description: Список трудоустройств
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Employment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /user:
    get:
      tags: [user]
      summary: Получить список пользователей
      operationId: getUsers
      x-permissions:
        anyOf:
          - user-list
          - show-user-page
          - user-invite
          - authenticated user with reports
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Fields'
        - $ref: '#/components/parameters/Expand'
        - name: searchQuery
          in: query
          description: Сквозной полнотекстовый поиск пользователей
          schema:
            type: string
        - name: q
          in: query
          description: Поиск по имени
          schema:
            type: string
        - name: id
          in: query
          description: ID пользователей через запятую
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: not_id
          in: query
          description: Исключить пользователя по ID
          schema:
            type: string
            format: uuid
        - name: email
          in: query
          description: Поиск по электронной почте
          schema:
            type: string
        - name: phone_auth
          in: query
          description: Поиск по телефону авторизации
          schema:
            type: string
        - name: name
          in: query
          description: Поиск по имени, фамилии и отчеству
          schema:
            type: string
        - name: first_name
          in: query
          description: Поиск по имени
          schema:
            type: string
        - name: middle_name
          in: query
          description: Поиск по отчеству
          schema:
            type: string
        - name: last_name
          in: query
          description: Поиск по фамилии
          schema:
            type: string
        - name: department_id
          in: query
          description: ID подразделения; учитывается его поддерево
          schema:
            type: string
            format: uuid
        - name: chief_id
          in: query
          description: ID руководителя
          schema:
            type: string
            format: uuid
        - name: position
          in: query
          description: Поиск по должности
          schema:
            type: string
        - name: is_external
          in: query
          description: Признак внешнего пользователя
          schema:
            type: boolean
        - name: reg_status_id
          in: query
          description: Регистрационные статусы через запятую
          style: form
          explode: false
          schema:
            type: array
            items:
              type: integer
        - name: gender_id
          in: query
          description: Пол пользователя; несколько значений через запятую
          style: form
          explode: false
          schema:
            type: array
            items:
              type: integer
        - name: duty_id
          in: query
          description: ID внутренней услуги
          schema:
            type: string
            format: uuid
        - name: birthday_date
          in: query
          description: Дата или диапазон дат рождения
          schema:
            type: string
        - name: created_at
          in: query
          description: Дата или диапазон дат создания в формате `from|to`
          schema:
            type: string
        - name: updated_at
          in: query
          description: Дата или диапазон дат изменения
          schema:
            type: string
        - name: employment_date
          in: query
          description: Дата или диапазон дат трудоустройства
          schema:
            type: string
        - name: is_boss
          in: query
          description: Признак руководителя
          schema:
            type: boolean
        - name: group_id
          in: query
          description: ID группы пользователей
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          description: ID персональных статусов через запятую
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: survey_id
          in: query
          description: ID опроса
          schema:
            type: string
            format: uuid
        - name: survey_360_matrix_is_approved
          in: query
          description: Статус согласования матрицы 360
          schema:
            type: boolean
        - name: company
          in: query
          description: Поиск по компании
          schema:
            type: string
        - name: spec_id
          in: query
          description: ID профессиональной области
          schema:
            type: string
            format: uuid
        - name: chief_only
          in: query
          description: Текущий пользователь и его прямые подчинённые
          schema:
            type: boolean
        - name: chief_only_all
          in: query
          description: Текущий пользователь и все его подчинённые
          schema:
            type: boolean
        - name: user_list_key
          in: query
          description: Ключ сохранённого списка пользователей
          schema:
            type: string
            format: uuid
        - name: withoutEmployment
          in: query
          description: Только пользователи без трудоустройств
          schema:
            type: boolean
        - name: searchInAllSubDepartments
          in: query
          description: Искать во всех вложенных подразделениях
          schema:
            type: boolean
      responses:
        '200':
          description: Список пользователей
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

components:
  parameters:
    Page:
      name: page
      in: query
      description: Номер страницы, начиная с 1
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPage:
      name: per-page
      in: query
      description: Количество элементов на странице
      schema:
        type: integer
        minimum: 1
        default: 20
    Sort:
      name: sort
      in: query
      description: Поля сортировки через запятую; префикс `-` задаёт сортировку по убыванию
      schema:
        type: string
    Fields:
      name: fields
      in: query
      description: Возвращаемые поля через запятую
      schema:
        type: string
    Expand:
      name: expand
      in: query
      description: Дополнительные связанные данные через запятую
      schema:
        type: string

  responses:
    Unauthorized:
      description: Пользователь не авторизован
    Forbidden:
      description: Недостаточно прав

  schemas:
    PaginatedResponse:
      type: object
      required: [data, _meta]
      properties:
        data:
          type: array
          items: {}
        _meta:
          $ref: '#/components/schemas/PaginationMeta'

    PaginationMeta:
      type: object
      required: [totalCount, pageCount, currentPage, perPage]
      properties:
        totalCount:
          type: integer
          example: 42
        pageCount:
          type: integer
          example: 3
        currentPage:
          type: integer
          example: 1
        perPage:
          type: integer
          example: 20

    Department:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
          nullable: true
        parent_id:
          type: string
          format: uuid
          nullable: true
        chief_id:
          type: string
          format: uuid
          nullable: true
        is_organization:
          type: boolean
        status_id:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Employment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        department_id:
          type: string
          format: uuid
          nullable: true
        chief_id:
          type: string
          format: uuid
          nullable: true
        position:
          type: string
          nullable: true
        is_main:
          type: boolean
        employment_date:
          type: string
          format: date
          nullable: true
        fired_date:
          type: string
          format: date
          nullable: true
        status_id:
          type: integer
        org_num:
          type: string
          nullable: true

    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        first_name:
          type: string
        middle_name:
          type: string
          nullable: true
        last_name:
          type: string
        name:
          type: string
        birthday_date:
          type: string
          format: date
          nullable: true
        reg_status_id:
          type: integer
        gender_id:
          type: integer
          nullable: true
        city_id:
          type: string
          format: uuid
          nullable: true
        company:
          type: string
          nullable: true
        is_external:
          type: boolean
        photo_file_id:
          type: string
          format: uuid
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time