API Реферальної програми — FonProxy Реферальна програма, Коди та Статистика

Останнє оновлення: 15 жовтня 2026 р.

Для автентифікації та заголовків дивіться API Загальне.

Огляд

Отримати інформацію про реферала Auth required

GET /referral

Повертає реферальний код користувача, відсотки і статистику. Автоматично створює реферальний код при першому доступі.

Відповідь

{
  "id": "xK9mR2pL1w",
  "code": "a3f8c2d1",
  "incomePercentage": 5,
  "salePercentage": 0,
  "clicks": 142,
  "registrations": 23,
  "totalIncome": 12.50,
  "pendingIncome": 3.75
}

Назва	Тип	Опис
`id`	`string`	Ідентифікатор реферала
`code`	`string`	Редагований реферальний код (використовується в реферальному посиланні)
`incomePercentage`	`number`	Відсоток, який отримує реферер від кожного поповнення від реферала
`salePercentage`	`number`	Відсоток знижки для рефералів (у майбутньому)
`clicks`	`number`	Загальна кількість відвідувачів, що прийшли через цей код
`registrations`	`number`	Загальна кількість користувачів, що зареєструвалися через цей код
`totalIncome`	`number`	Загальний завершений дохід від рефералів (USD)
`pendingIncome`	`number`	Очікуваний дохід від рефералів, що ще не зарахований (USD)

Список запрошених людей Auth required

GET /referral/people

Повертає найновіших людей, які зареєструвалися за допомогою посилання користувача, із прихованими серединами адрес.

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

Назва	Тип	Опис	Обов'язково
`limit`	`number`	Скільки людей повернути, новітні спочатку (за замовчуванням 5, макс. 20)	Ні

Відповідь

{
  "total": 23,
  "people": [
    {
      "signedUpAt": "2026-04-08T11:20:00.000Z",
      "account": "j•••@gmail.com",
      "topups": 2,
      "spentUsd": 40,
      "earnedUsd": 2,
      "status": "paid"
    }
  ]
}

Назва	Тип	Опис
`total`	`number`	Всі, хто зареєструвався за цим реферальним кодом, не лише на повернутій сторінці
`signedUpAt`	`string`	Час реєстрації (ISO 8601)
`account`	`string`	Маскована email: перший символ, `•••`, потім домен
`topups`	`number`	Поповнення цього користувача, що дали реферальний дохід
`spentUsd`	`number`	Сума цих поповнень (USD)
`earnedUsd`	`number`	Реферальний дохід, зароблений від них (USD)
`status`	`string`	`paid` (весь дохід зарахований), `pending` (деякий дохід не зарахований), `none` (не було поповнень поки що)

Код

Оновити реферальний код Auth required

PATCH /referral/code

Оновити реферальний код. Має бути 3–30 символів, букви, цифри + підкреслення + дефіс.

Тіло запиту

Назва	Тип	Опис	Обов'язково
`code`	`string`	Новий реферальний код	Так

Відповідь

{ "code": "john_doe", "message": "referral.code_updated" }

Помилки:

{ "message": "referral.code_invalid" }
{ "message": "referral.code_taken" }

Аналітика

Графік рефералів Auth required

GET /referral/graph

Повертає дані графіка про кліки, реєстрації та дохід у часовій послідовності.

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

Назва	Тип	Опис	Обов'язково
`from`	`string`	Початок дати в форматі ISO. За замовчуванням 30 днів тому	Ні
`to`	`string`	Кінець дати в форматі ISO. За замовчуванням теперішній час	Ні
`granularity`	`string`	`hour`, `day`, `week`, `month`. Автоматичне визначення за замовчуванням	Ні

Відповідь

{
  "graph": "referral",
  "granularity": "day",
  "from": "2026-02-23T00:00:00.000Z",
  "to": "2026-03-25T00:00:00.000Z",
  "series": [
    {
      "key": "clicks",
      "label": "Clicks",
      "color": "#3B82F6",
      "points": [
        { "t": "2026-03-24T00:00:00.000Z", "v": 15 },
        ...
      ]
    },
    {
      "key": "registrations",
      "label": "Registrations",
      "color": "#22C55E",
      "points": [
        { "t": "2026-03-24T00:00:00.000Z", "v": 3 },
        ...
      ]
    },
    {
      "key": "income",
      "label": "Income (USD)",
      "color": "#151515",
      "points": [
        { "t": "2026-03-24T00:00:00.000Z", "v": 2.50 },
        ...
      ]
    }
  ],
  "meta": { "currency": "USD" }
}

Як працюють реферали

Користувач отримує унікальний реферальний код з GET /referral
Фронтенд будує посилання: https://fonproxy.com/?ref=<code>
Відвідувач приходить → реєструється в базі даних.
Відвідувач реєструється → invitedById встановлюється для нового користувача + реферер отримує сповіщення
Реферальний користувач поповнює рахунок → створюється очікуюча транзакція реферального доходу для реферера
Через 2 дні (миттєво в режимі розробки) очікуюча транзакція зараховується на баланс реферера + реферер отримує сповіщення
Користувач може відстежувати все в GET /referral, GET /referral/graph і GET /referral/people