API курсу НБУ для JavaScript і Node.js
Оновлено 26.09.2026
Курс НБУ в JavaScript отримується звичайним `fetch` до `https://dani.initask.com/v1/rates`. Відповідь має однакову структуру для всіх ендпоінтів Initask API: `ok`, `data`, `error`, тож розбір пишеться один раз. Нижче приклад, робота із заголовками лімітів, обробка 429 і порада, як не звертатися до API на кожне завантаження сторінки.
Приклад
```javascript const r = await fetch("https://dani.initask.com/v1/rates?date=2026-09-25&cur=USD,EUR", { headers: { Authorization: `Bearer ${process.env.INITASK_KEY}` }, }); const { ok, data, error } = await r.json(); console.log(r.headers.get("X-RateLimit-Remaining"), data); ```
Приклад розрахований на серверний код: ключ береться зі змінної середовища. У браузері ключ світити не можна, тому запит до API робить ваш сервер, а сторінка звертається вже до нього. Без ключа доступно 100 запитів на добу з однієї IP-адреси, і для сервера з кешем цього часто досить.
Структура відповіді
Прапорець `ok` показує, чи запит успішний. У разі успіху в `data` лежать дата курсу, базова валюта і масив курсів. Кожен курс має буквений код, назву, значення в гривнях за одну одиницю і цифровий код. У разі помилки `data` порожнє, а причина в `error`.
Для прикладу на 2026-09-25 у масиві прийдуть євро за 51.122 і долар США за 44.9729 гривні з цифровими кодами 978 і 840. Масив зручно одразу перетворити на обʼєкт за буквеним кодом, щоб курс діставався за ключем без пошуку.
Параметри запиту
| Параметр | Обовʼязковий | Опис |
|---|---|---|
| date | ні | дата YYYY-MM-DD, від 1996-01-06 до завтра; без параметра сьогодні за Києвом |
| cur | ні | коди валют ISO 4217 через кому, до 20 кодів; без параметра всі валюти |
Заголовки лімітів і 429
Кожна відповідь несе три заголовки: `X-RateLimit-Limit`, `X-RateLimit-Remaining` і `X-RateLimit-Reset`. Сервер може читати залишок і завчасно попереджати в журналі, що ліміт закінчується.
Після вичерпання ліміту приходить код 429 і заголовок `Retry-After`. Правильна реакція: прочитати значення, почекати вказаний час і повторити запит. Нескінченні повтори без паузи лише продовжують блокування і засмічують журнали.
Інші коди відповідей:
| Код | Коли |
|---|---|
| 400 | дата у форматі, відмінному від YYYY-MM-DD, або поза межами |
| 404 | на дату немає курсів або серед них немає запитаних валют |
Кешування на вашому боці
Курс на конкретну дату після публікації не змінюється. Тому найкраща архітектура проста: сервер запитує курс один раз, зберігає його в памʼяті чи базі і віддає сторінкам зі свого сховища. Шлюз теж кешує: курс на минулу дату добу, на сьогодні і завтра 10 хвилин. Проте кожне звернення до шлюзу рахується в ліміт, тож власний кеш економить і запити, і час відповіді.
Для сайту, що показує курс на сьогодні, достатньо оновлювати значення раз на кілька хвилин. Для курсу на завтра врахуйте, що НБУ встановлює його близько 15:30 за Києвом: до цього часу запит із завтрашньою датою дасть 404.
Типові задачі фронтенду і Node.js
Перерахунок цін. Сервер тримає курс на сьогодні, а шаблон показує ціни в гривні.
Облікова інтеграція. Скрипт на Node.js щодня запитує курс і записує його в базу разом з датою.
Інвойси. Перед формуванням рахунку сервіс бере курс саме на дату операції.
Нагадування про зміну курсу. Сервіс порівнює курс на сьогодні з учорашнім і повідомляє менеджера, коли зміна перевищує поріг, заданий компанією. Так рішення про перегляд цін ухвалюється вчасно, без щоденного ручного моніторингу.
Надійність інтеграції
Зовнішній сервіс може тимчасово не відповісти, як і будь-який інший. Тому інтеграція має чесно переживати збій: лишати попереднє значення курсу, писати попередження в журнал і пробувати ще раз через кілька хвилин. Користувач сайту при цьому бачить ціни за останнім відомим курсом і нічого не помічає. Помилку краще показувати адміністратору, а не відвідувачу.
Ліміти і тарифи
| План | Запитів | Ціна, грн на місяць |
|---|---|---|
| Безкоштовний | 100 на добу | 0 |
| Старт | 10000 на місяць | 990 |
| Про | 100000 на місяць | 2990 |
Ключ можна передати заголовком `Authorization: Bearer КЛЮЧ` або параметром `key`. Заголовок безпечніший, бо адреси запитів часто потрапляють у журнали.
Що робити
- Скопіюйте приклад у серверний код і запустіть його з ключем у змінній середовища.
- Перетворіть масив курсів на обʼєкт за буквеним кодом.
- Додайте обробку 429 з паузою за `Retry-After`.
- Збережіть курс у своєму кеші і віддавайте сторінкам звідти.
- Опис усіх полів у документації курсу НБУ, план під навантаження на сторінці Ціни і ліміти.
Питання і відповіді
Як отримати курс НБУ через fetch?
Зробіть fetch до https://dani.initask.com/v1/rates з параметрами date і cur і заголовком Authorization: Bearer КЛЮЧ. Відповідь містить ok, data і error.
Як обробити помилку 429?
Прочитайте заголовок Retry-After, почекайте вказаний час і повторіть запит. Залишок ліміту показує заголовок X-RateLimit-Remaining.
Чи можна викликати API курсу прямо з браузера?
Ключ у браузері світити не можна, тому запит робить ваш сервер, зберігає курс у кеші і віддає його сторінкам.