diff --git a/v2/swagger.yaml b/v2/swagger.yaml index f7cca68..1c5ed95 100644 --- a/v2/swagger.yaml +++ b/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: "
Плановые работы 1 октября с 02:00 до 04:00 МСК.
" + published_at: + type: string + format: date-time + description: Дата и время публикации, ISO 8601 со смещением. + example: "2026-09-24T16:30:04+03:00" + parameters: boardDateTypeParam: in: query