API КВЕД на JavaScript: fetch, заголовки лімітів і 429
Оновлено 26.09.2026
Фронтенд-розробник робить поле «Вид діяльності» у формі, а Node.js-розробник обробляє анкети нових клієнтів на сервері. Обом потрібна розшифровка коду КВЕД: назва, секція, розділ, для ФОП статус на єдиному податку. Initask API віддає це запитом `GET https://dani.initask.com/v1/kved/{code}` у форматі JSON. Нижче приклад на JavaScript і те, що варто врахувати в продакшн-коді: де тримати ключ, як читати заголовки лімітів і що робити з кодом 429.
Приклад
```javascript const r = await fetch("https://dani.initask.com/v1/kved/62.01", { headers: { Authorization: `Bearer ${process.env.INITASK_KEY}` }, }); const { ok, data, error } = await r.json(); console.log(r.headers.get("X-RateLimit-Remaining"), data); ```
Приклад розрахований на сервер: ключ читається зі змінної середовища. Не вбудовуйте ключ у код, який виконується в браузері, бо будь-хто зможе його побачити і витратити ваш ліміт. Форма в браузері звертається до вашого сервера, а сервер до Initask API.
Форма відповіді
Тіло відповіді містить три частини. Ознака `ok` каже, чи запит вдався. У `data` лежать самі дані, у `error` опис помилки, якщо щось пішло не так. Така форма однакова для всіх ендпоінтів Initask API, тому обробник можна написати один раз і використовувати для КВЕД, компаній, курсів і решти.
Для 62.01 у даних прийдуть назва «Компʼютерне програмування», рівень `class`, секція J «Інформація та телекомунікації», розділ 62, група 62.0 і поле `fop` зі статусом `allowed`. Для другої групи єдиного податку там сказано, що вона можлива, якщо клієнти це населення або платники єдиного податку, для третьої групи обмежень немає.
Заголовки лімітів
Кожна відповідь містить три заголовки:
| Заголовок | Що показує |
|---|---|
| X-RateLimit-Limit | ліміт вашого плану |
| X-RateLimit-Remaining | скільки запитів лишилось |
| X-RateLimit-Reset | коли ліміт скинеться |
Коли ліміт вичерпано, приходить код 429 і заголовок `Retry-After` з кількістю секунд очікування. Правильна реакція сервера: поставити запит у чергу на вказаний час і повторити його після паузи. Для форми в браузері краще показати людині спокійне повідомлення і дозволити зберегти анкету без розшифровки коду, а розшифрувати пізніше.
Помилки
| Код | Помилка | Коли |
|---|---|---|
| 400 | bad_request | рядок має форму, відмінну від коду КВЕД |
| 404 | not_found | такого коду у класифікаторі немає |
Для поля форми 400 і 404 варто показувати по-різному. 400 означає, що людина ввела щось, зовсім не схоже на код. 404 означає, що формат правильний, але такого коду немає, найчастіше це одрук або код зі старого класифікатора. Кому шлюз приймає сам: 62,01 читається як 62.01.
Статус єдиного податку в інтерфейсі
Якщо ваш сервіс працює з підприємцями, статус з поля `fop` варто показувати людині прямо у формі. Зелена позначка для дозволеного коду, жовта для коду, що потребує перевірки умов, червона для забороненого на єдиному податку. Поруч коротке пояснення для групи, яку людина обрала. Такий підказник рятує підприємця від помилки, яку інакше він помітив би лише після листа з податкової. Текст пояснень приходить українською в самій відповіді, тож перекладати чи переписувати його не треба.
Кеш на своєму боці
Шлюз кешує відповідь на 1440 хвилин, і на своєму сервері ви можете робити те саме або довше. Простий кеш у памʼяті процесу за кодом КВЕД прибирає більшість повторних запитів: коди в анкетах повторюються часто. Для кількох серверів підійде спільне сховище.
| План | Запитів | Ціна, грн на місяць |
|---|---|---|
| Безкоштовний | 100 на добу | 0 |
| Старт | 10000 на місяць | 990 |
| Про | 100000 на місяць | 2990 |
Підказки у полі форми
Поле `children` повертає підкоди з назвою, рівнем і сторінкою. Це дає змогу зробити підказки: людина вводить «62», сервер питає розділ і показує список класів з назвами. Завантажте дерево для потрібних розділів заздалегідь, і підказки працюватимуть без затримки.
Що робити
- Запустіть приклад на сервері з ключем у змінній середовища.
- Напишіть один обробник відповіді з перевіркою `ok` для всіх ендпоінтів Initask API.
- Додайте обробку 429 з очікуванням за заголовком `Retry-After` і кеш за кодом.
- Для анкет юросіб беріть код з картки компанії за ЄДРПОУ, для ФОП показуйте строки з податкового календаря.
- Опис полів у документації КВЕД, тарифи на сторінці Ціни і ліміти.
Питання і відповіді
Як отримати назву КВЕД через fetch?
Запит fetch до https://dani.initask.com/v1/kved/{code} із заголовком Authorization: Bearer і ключем повертає JSON з ok, data і error. Ключ тримайте на сервері.
Що робити з кодом 429 у JavaScript?
Прочитати заголовок Retry-After і повторити запит через вказану кількість секунд. Поточний залишок видно в X-RateLimit-Remaining.
Чи можна викликати API КВЕД прямо з браузера?
Технічно так, але ключ у браузері побачить будь-хто. Краще робити запит з вашого сервера.