H-3729: GET /system-notifications/active

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

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}:
@@ -2525,6 +2527,7 @@ paths:
               - updBirthday
               - updNewbies
               - updBooks
+              - updContent
         - name: info
           in: query
           description: >
@@ -2537,6 +2540,21 @@ paths:
             enum:
               - profileBrief
               - notificationsBadge
+        - name: visibility_target_id
+          in: query
+          description: >
+            Content widgets visibility target filter. Used for `updContent` widget.
+             * `1` - Web
+             * `2` - Mobile app
+             * `3` - Everywhere
+          example: 2
+          schema:
+            type: integer
+            default: 1
+            enum:
+              - 1
+              - 2
+              - 3
       responses:
         200:
           description: Returns all the dashboard data about requested widgets. In response object only requested info/widgets keys will be presented. If widget is not available for current user, this widget will not exists in response of will be null.
@@ -2596,6 +2614,21 @@ paths:
                       updBooks:
                         #                        description: Company feed - New books in library
                         $ref: '#/components/schemas/dashboardWidget'
+                      updContent:
+                        description: Company feed - Content widgets
+                        allOf:
+                          - $ref: '#/components/schemas/dashboardWidget'
+                          - type: object
+                            properties:
+                              items:
+                                type: array
+                                items:
+                                  allOf:
+                                    - $ref: '#/components/schemas/dashboardWidgetItem'
+                                    - type: object
+                                      properties:
+                                        data:
+                                          $ref: '#/components/schemas/dashboardContentWidgetItemData'
         400:
           description: Invalid input
         401:
@@ -8233,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:
@@ -9590,6 +9680,31 @@ components:
                 periodLengthText:
                   type: integer
                   description: Продолжительность отпуска в днях
+
+    dashboardContentWidgetItemData:
+      type: object
+      properties:
+        content:
+          type: string
+          description: Rendered content widget HTML.
+          example: '<a href="https://example.hrbox.io/article/1">Open article</a>'
+        visibility_target_id:
+          type: integer
+          description: Content widget visibility target.
+          enum:
+            - 1
+            - 2
+            - 3
+          example: 2
+        visibilityTargetName:
+          type: string
+          description: Human readable visibility target name.
+          enum:
+            - Веб
+            - Мобильное приложение
+            - Везде
+          example: Мобильное приложение
+
     feedback:
       type: object
       properties:
@@ -13774,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