Notifications API

Endpoints for listing, reading, and managing notification channels and preferences on FonProxy.

Updated 2026-04-17 14:57:00

Для автентифікації, формату помилок і загальних заголовків дивіться Загальна інформація про API.

Усі ідентифікатори сповіщень є ID.

Сповіщення

Переглянути список сповіщень Auth required

GET /notifications

Параметри запиту

Назва	Тип	Опис	Обов'язково
`page`	`number`	Номер сторінки (за замовчуванням: `1`)	Ні
`limit`	`number`	Кількість елементів на сторінку, макс. 50 (за замовчуванням: `20`)	Ні
`category`	`string`	Фільтр: `general`, `auth`, `order`, `payment`, `support`	Ні

Відповідь

{
  "notifications": [
    {
      "id": "K4Xb9rPmYz",
      "type": "order_activated",
      "category": "order",
      "subject": "notification.order_activated_subject",
      "payload": {
        "subject": "notification.order_activated_subject",
        "blocks": [
          { "type": "heading", "text": "notification.order_activated_heading" },
          { "type": "text", "text": "notification.order_activated_text" },
          { "type": "divider" },
          { "type": "key_value", "label": "notification.order_activated_type", "value": "Residential Giga" },
          { "type": "key_value", "label": "notification.order_activated_quantity", "value": "10 GB" },
          { "type": "key_value", "label": "notification.order_activated_total", "value": "$5.00" },
          { "type": "divider" },
          { "type": "heading", "text": "notification.order_activated_getting_started" },
          { "type": "text", "text": "notification.order_activated_step_1" },
          { "type": "text", "text": "notification.order_activated_step_2" },
          { "type": "text", "text": "notification.order_activated_step_3" },
          { "type": "copyable", "value": "https://fonproxy.com/orders/K4Xb9rPmYz", "label": "notification.order_activated_order_link" },
          { "type": "button", "text": "notification.order_activated_view_order", "url": "https://fonproxy.com/orders/K4Xb9rPmYz" },
          { "type": "divider" },
          { "type": "muted", "text": "notification.order_activated_footer" }
        ]
      },
      "read": false,
      "createdAt": "2026-03-22T10:00:00.000Z"
    },
    ...
  ],
  "total": 1,
  "page": 1,
  "pages": 1
}

Отримати кількість непрочитаних Auth required

GET /notifications/unread-count

Відповідь

{
  "unread": 3
}

Отримати окреме сповіщення Auth required

GET /notifications/:id

Відповідь

{
  "id": "K4Xb9rPmYz",
  "type": "welcome",
  "category": "general",
  "subject": "notification.welcome_subject",
  "payload": {
    "subject": "notification.welcome_subject",
    "blocks": [
      { "type": "heading", "text": "notification.welcome_heading" },
      { "type": "text", "text": "notification.welcome_text" },
      { "type": "key_value", "label": "notification.welcome_email_label", "value": "user@example.com" },
      { "type": "divider" },
      { "type": "muted", "text": "notification.welcome_footer" }
    ]
  },
  "read": true,
  "createdAt": "2026-03-22T09:00:00.000Z"
}

Позначити сповіщення як прочитане Auth required

PATCH /notifications/:id/read

Відповідь

{
  "id": "K4Xb9rPmYz",
  "type": "welcome",
  "category": "general",
  "subject": "notification.welcome_subject",
  "payload": { "..." : "..." },
  "read": true,
  "createdAt": "2026-03-22T09:00:00.000Z"
}

Позначити всі сповіщення як прочитані Auth required

PATCH /notifications/read-all

Відповідь

{
  "success": true
}

Типи блоків сповіщень

Масив payload.blocks містить структуровані блоки контенту, які фронтенд рендерить. Кожен блок має type і специфічні поля для типу:

Тип	Поля	Опис
`heading`	`text`	Заголовок розділу
`text`	`text`	Текст параграфа (може містити HTML для електронної пошти)
`muted`	`text`	Маленький сірий/другорядний текст
`code`	`code`, `label?`	Великий текст у моноширинному форматі (наприклад, коди автентифікації)
`copyable`	`value`, `label?`	Значення, яке можна скопіювати (наприклад, проксі-сервер, URL)
`button`	`text`, `url`	Кнопка заклик до дії / посилання
`divider`	—	Горизонтальний розділювач
`key_value`	`label`, `value`	Пара "назва: значення"

Текстові поля, що містять ключі notification.*, повинні розв'язуватися через систему перекладу на фронтенді.

Категорії сповіщень

Категорія	Опис
`general`	Привітання, системні оголошення
`auth`	Коди автентифікації (тільки електронна пошта, не зберігаються в БД)
`order`	Замовлення активовано, закінчується термін дії тощо
`payment`	Поповнення завершено, не вдалося тощо
`admin`	Адміністративні оголошення
`referral`	Реєстрація і доходи від рефералів
`support`	Відповіді та закриття заявок підтримки

Обмеження каналів

Не всі сповіщення надсилаються на всі канали:

Сповіщення	email	database	telegram	Примітки
Код автентифікації	✅	❌	❌	Безпека: коди ніколи не зберігаються
Привітання	✅	✅	✅	Усі канали
Замовлення активовано	✅	✅	✅	Усі канали
Адміністративна трансляція	✅	✅	✅	Канали, налаштовані адміністратором; коли канали явно встановлені адміністратором, налаштування користувача ігноруються
Реферальна реєстрація	✅	✅	✅	Усі канали
Реферальний дохід	✅	✅	✅	Усі канали
Відповідь підтримки	✅	✅	✅	Усі канали; анонімні користувачі тільки на електронну пошту
Закриття підтримки	✅	✅	✅	Усі канали; анонімні користувачі тільки на електронну пошту

Параметри каналу

Користувачі можуть увімкнути або вимкнути канали сповіщень. Вимкнені канали мовчки пропускаються під час відправки.

Переглянути канали Auth required

GET /notifications/channels

Відповідь

{
  "channels": [
    {
      "name": "email",
      "label": "Email",
      "available": true,
      "userControllable": true,
      "enabled": true
    },
    {
      "name": "database",
      "label": "Вбудовані сповіщення",
      "available": true,
      "userControllable": true,
      "enabled": true
    },
    {
      "name": "telegram",
      "label": "Тelegram",
      "available": true,
      "userControllable": true,
      "enabled": true
    }
  ]
}

available — чи налаштований канал на сервері (наприклад, налаштування SMTP для електронної пошти).
enabled — чи увімкнуто канал для цього користувача.
userControllable — чи може користувач керувати ним (деякі системні канали можуть бути доступні лише для читання в майбутньому).

Оновити налаштування каналу Auth required

PATCH /notifications/channels/:channel

Параметри

Назва	Тип	Опис	Обов'язково
`:channel`	`string`	Назва каналу (`email`, `database`, тощо)	Так

Тіло запиту

{ "enabled": false }

Відповідь

Повний оновлений список каналів (такий самий як GET /notifications/channels).

Відписка (публічна)

Кожен надісланий електронний лист містить посилання для відписки в один клік на підписці. Натискання на нього відразу вимикає канал електронної пошти для цього користувача і показує брендовану сторінку підтвердження.

Відписатися через токен

GET /notifications/unsubscribe

Параметри запиту

Назва	Тип	Опис	Обов'язково
`token`	`string`	AES-256-GCM зашифрований токен, що містить `{ userId, channel }`	Так

Повертає HTML-сторінку (200 на успіх, 400 при недійсному токені).

Токен генерується на стороні сервера і включається в кожен вихідний електронний лист. Пошук у бази даних не потрібен — саме шифрування діє як автентифікація.

Повторне увімкнення електронних сповіщень здійснюється з автентифікованого кінцевого ходу /notifications/channels.

API Reference

Copy page as Markdown for AI / LLM