API General

Базовий URL: https://api.fonproxy.io

Аутентифікація

Всі захищені кінцеві точки вимагають API-ключ:

Згенеруйте API-ключ у своєму акаунті: API Keys.

Локаль

API використовує заголовок fp-locale, щоб визначити мову користувача.

fp-locale: uk

Поведінка

• Кожен запит: бекенд читає fp-locale і використовує його для контенту, що рендериться сервером (електронні листи, сповіщення в Telegram).
• Користувачі, що ввійшли в систему: якщо значення в заголовку відрізняється від збереженої локалі, бекенд автоматично оновлює локаль користувача в базі даних (fire-and-forget, додаткового запиту не потрібно).
• Підтримувані локалі: en (Англійська, за замовчуванням), uk (Українська).
• Отримайте поточний список локалей під час виконання програми: GET /locales
• Запасний варіант: якщо заголовок відсутній або локаль невідома, використовується en.

Що Перекладається

Поле locale завжди повертається в профілі користувача (GET /user/me), щоб фронтенд міг відповідно ініціалізувати свою i18n.

Загальні Заголовки

Формат Відповіді

Всі відповіді в форматі JSON. Успішні відповіді повертають відповідні дані безпосередньо:

{
  "user": { "id": "k5Xz9qR2Wp", "name": "John", ... }
}

Відповіді про помилки:

{
  "message": "order.not_found",
  "path": "/orders/80-12345",
  "timestamp": "2026-04-01T12:00:00.000Z"
}

Поле message є ключем для перекладу — фронтенд перетворює його на зрозумілу для людини фразу.

Пагінація

Пагіновані кінцеві точки приймають:

Відповідь включає:

{
  "items": [ ... ],
  "total": 142,
  "page": 1,
  "pages": 8
}

Валюта

• Всі ціни та баланси зберігаються у USD внутрішньо.
• Значення для відображення конвертуються з використанням актуальних обмінних курсів.
• Обрану користувачем валюту для відображення можна встановити через PATCH /user/settings { "currency": "UAH" }.
• Кінцеві точки, що повертають грошові значення, включають поля *Usd та *Display.

Обмеження Швидкості

Обмеження за IP-адресою. За замовчуванням: 60 запитів / хвилину для більшості кінцевих точок, 5 / хвилину для кінцевих точок аутентифікації.

Коли перевищено швидкість, API повертає 429 Too Many Requests:

{ "message": "error.rate_limit" }

Локалі

GET /locales

Повертає всі поточні підтримувані коди локалей з їхніми назвами для відображення.

Відповідь:

{
  "locales": [
    { "code": "en", "name": "English", "nativeName": "English" },
    { "code": "uk", "name": "Ukrainian", "nativeName": "Українська" }
  ]
}

Валюта

GET /currencies

Повертає всі підтримувані коди валют. Загальнодоступний, автентифікація не потрібна.

Відповідь:

{
  "currencies": ["USD", "EUR", "GBP", "PLN", "CZK", "HUF", "RON", "SEK", "NOK", "DKK", "CHF", "HRK", "BGN", "UAH", "TRY"]
}

GET /currencies/rates

Повертає останні обмінні курси, згруповані за кодами валют. Кожне значення "1 база = N ціль" — з base=USD, "EUR": 0.92 означає, що 1 USD можна обміняти на 0.92 EUR. Загальнодоступний, автентифікація не потрібна.

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

Відповідь:

{
  "base": "USD",
  "rates": {
    "USD": 1,
    "EUR": 0.92,
    "UAH": 41.2,
    ...
  }
}

Помилки:

Довідка по API