H-3729: GET /system-notifications/active

Co-Authored-By: Claude Opus 5.5 (1M context)

swagger.yml

@@ -1,680 +0,0 @@
-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

v2/swagger.yaml

@@ -79,6 +79,8 @@ tags:
     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.
+  - name: system-notifications
+    description: Methods for reading active HRBox system announcements (home page banner for portal administrators). Requires "admin-controls" permission.
 
 paths:
   /mobile/bind/{id}/{token}:
@@ -8264,6 +8266,63 @@ paths:
             Запись не найдена. Включает случаи обращения к записям,
             принадлежащим другим тенантам.
 
+  /system-notifications/active:
+    get:
+      tags: [system-notifications]
+      summary: Получить активные системные объявления
+      description: |
+        Возвращает постраничный список активных системных объявлений HRBox
+        (по умолчанию 20 на страницу, максимум 50). По умолчанию сортировка
+        по дате публикации, сначала новые. Используется для баннера
+        на главной странице портала.
+
+        Тело каждого объявления (`body_html`) рендерится из markdown на языке
+        профиля текущего пользователя с откатом на русский, если перевод
+        отсутствует, и очищается до ограниченного набора тегов: `p`, `br`,
+        `strong`, `em`, `del`, `ul`, `ol`, `li`, `a` (только `http`/`https`,
+        с `target="_blank" rel="noopener noreferrer"`). Если после очистки
+        текста не осталось, объявление всё равно попадает в выдачу
+        с пустым `body_html` — клиенты такие объявления не показывают.
+
+        Скрытие объявлений хранится только на стороне клиента (локально)
+        и не влияет на ответ этого метода.
+      operationId: systemNotificationsActive
+      parameters:
+        - name: per-page
+          in: query
+          schema: { type: integer, minimum: 1, maximum: 50, default: 20 }
+          description: Значение больше 50 урезается до 50.
+        - name: page
+          in: query
+          schema: { type: integer, minimum: 1, default: 1 }
+        - name: sort
+          in: query
+          schema:
+            type: string
+            enum:
+              - published_at
+              - -published_at
+          description: По умолчанию `-published_at`.
+      responses:
+        200:
+          description: Список активных объявлений.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/SystemNotification'
+                  _links:
+                    $ref: '#/components/schemas/_links'
+                  _meta:
+                    $ref: '#/components/schemas/_meta'
+        403:
+          description: |
+            У текущего пользователя отсутствует право `admin-controls`.
+
 components:
   securitySchemes:
     SessionAuth:
@@ -13830,6 +13889,31 @@ components:
         _meta:
           $ref: '#/components/schemas/_meta'
 
+    SystemNotification:
+      type: object
+      description: Системное объявление HRBox в баннере на главной странице портала.
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Идентификатор объявления.
+        body_html:
+          type: string
+          description: |
+            Текст объявления, отрендеренный из markdown в HTML на языке
+            профиля пользователя (откат на русский, если перевод отсутствует)
+            и очищенный до ограниченного набора тегов: `p`, `br`, `strong`,
+            `em`, `del`, `ul`, `ol`, `li`, `a` (только `http`/`https`,
+            с `target="_blank" rel="noopener noreferrer"`). Пустая строка,
+            если после очистки текста не осталось — такие объявления клиенты
+            не показывают.
+          example: "<p>Плановые работы <strong>1 октября</strong> с 02:00 до 04:00 МСК.</p>"
+        published_at:
+          type: string
+          format: date-time
+          description: Дата и время публикации, ISO 8601 со смещением.
+          example: "2026-09-24T16:30:04+03:00"
+
   parameters:
     boardDateTypeParam:
       in: query