Документация Notifier

Интеграция сервиса с Notifier API

Эта страница для разработчиков сервисов, которые отправляют Telegram-уведомления через Notifier.

1. Быстрый старт

Администратор создает сервис в панели Notifier.
Администратор выпускает API-ключ для этого сервиса.
Ваш backend отправляет HTTP-запросы в Notifier с заголовком X-API-Key.

Базовый URL обычно выглядит так: https://your-domain.com/api.

2. Авторизация

Все интеграционные методы защищены API key и требуют заголовок X-API-Key.

X-API-Key: ntf_xxxxxxxxxxxxxxxxxxxxxxxxx

3. Методы отправки уведомлений

POST /notify/user

Отправка одному пользователю по keycloakId.

curl -X POST "https://your-domain.com/api/notify/user" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ntf_xxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "keycloakId": "user-123",
    "sender": "Billing Service",
    "message": "Ваш платеж успешно проведен",
    "actions": [
      { "name": "Открыть кабинет", "url": "https://example.com/account" }
    ]
  }'

POST /notify/users

Массовая отправка выбранным пользователям (до 1000 keycloakId за один запрос).

curl -X POST "https://your-domain.com/api/notify/users" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ntf_xxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "keycloakIds": ["user-123", "user-456"],
    "sender": "LMS",
    "message": "Новый курс уже доступен"
  }'

POST /notify/all

Broadcast по всем активным пользователям. Доступен только сервисам с включенным canBroadcast.

curl -X POST "https://your-domain.com/api/notify/all" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ntf_xxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "sender": "Portal",
    "message": "Плановые технические работы в 23:00"
  }'

4. Формат ответа

Все методы /notify/* возвращают агрегированный результат доставки:

{
  "success": true,
  "sent": 42,
  "all": 50,
  "failed": 8
}

success: хотя бы одно сообщение отправлено.
sent: количество успешно доставленных сообщений.
failed: количество недоставленных сообщений.

5. Лимиты и ограничения

POST /notify/user: до 60 запросов в минуту.
POST /notify/users: до 10 запросов в минуту.
POST /notify/all: до 2 запросов в час.
actions в сообщении: максимум 5 кнопок.
message: до 4000 символов.

6. Частые ошибки

401 Unauthorized: отсутствует или неверный X-API-Key.
403 Forbidden: у сервиса нет права на broadcast (canBroadcast = false).
400 Bad Request: невалидное тело запроса (например, пустой `message`).