FonProxy API сповіщень — Попередження, Канали та Налаштування

Останнє оновлення: 17 квітня 2026 р.

Щодо аутентифікації, формату помилок та заголовків, дивіться Загальну інформацію для 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`	Пара "Мітка: значення"

subject та поля text, label і title блоків повертаються вже перекладеними на мову заголовка fp-locale (англійська у випадку відсутності або невідомості). Значення (value, code, url, значення рядків) є даними і ніколи не перекладаються.

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

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

Обмеження каналу

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

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

Уподобання каналу

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

Список каналів Auth required

GET /notifications/channels

Відповідь

{
  "channels": [
    {
      "name": "email",
      "label": "Електронна пошта",
      "available": true,
      "userControllable": true,
      "enabled": true
    },
    {
      "name": "database",
      "label": "Сповіщення в додатку",
      "available": true,
      "userControllable": true,
      "enabled": true
    },
    {
      "name": "telegram",
      "label": "Telegram",
      "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.