API КВЕД на Python: розшифровка кодів скриптом з requests
Оновлено 26.09.2026
Аналітик отримав вивантаження клієнтів чи контрагентів з колонкою КВЕД і хоче згрупувати їх за галузями. Або розробник пише скрипт, що перевіряє коди ФОП перед підключенням до сервісу. В обох випадках потрібна та сама операція: код на вході, назва і ієрархія на виході. Initask API робить це запитом `GET https://dani.initask.com/v1/kved/{code}`, і на Python це кілька рядків з бібліотекою requests.
Базовий запит
```python import os, requests
r = requests.get( "https://dani.initask.com/v1/kved/62.01", headers={"Authorization": f"Bearer {os.environ['INITASK_KEY']}"}, timeout=10, ) body = r.json() print(r.headers["X-RateLimit-Remaining"], body["data"]) ```
Ключ береться зі змінної середовища `INITASK_KEY`, у тексті скрипта його немає. Без ключа доступно 100 запитів на добу з однієї IP-адреси, для першої спроби цього досить. Таймаут у десять секунд не дає скрипту зависнути на поганій мережі.
Що лежить у відповіді
Відповідь складається з ознаки успіху, самих даних і службової частини з джерелом. Для 62.01 у даних прийдуть:
| Поле | Значення у прикладі |
|---|---|
| code | 62.01 |
| name | Компʼютерне програмування |
| level | class |
| section | J, Інформація та телекомунікації |
| division | 62, Компʼютерне програмування, консультування та повʼязана з ними діяльність |
| group | 62.0 |
| fop.status | allowed |
Для групування за галузями беріть код секції з `section`: це одна літера, і за нею зручно будувати зведену таблицю. Для детальнішого аналізу підходить розділ з `division`.
Поле `fop` є лише у класу. Воно містить статус (`allowed`, `only3`, `check`, `forbidden`, `na`), підпис українською і пояснення окремо для груп `g1`, `g2`, `g3` з полем `ok` і текстом. Якщо скрипт перевіряє коди ФОП третьої групи, достатньо дивитися на `g3.ok`.
Нормалізація кодів перед запитом
У вивантаженнях коди записані по-різному: з комою, з пробілами, з малою літерою секції. Шлюз сам читає 62,01 як 62.01 і приймає малу літеру, тому окремо чистити формат не обовʼязково. Корисніше інше: прибрати дублікати. У вивантаженні на тисячі рядків унікальних кодів зазвичай кілька десятків, і скрипт має питати кожен код один раз.
Обробка помилок і лімітів
| Код відповіді | Помилка | Що робити у скрипті |
|---|---|---|
| 400 | bad_request | рядок має форму, відмінну від коду КВЕД: записати в журнал і пропустити |
| 404 | not_found | такого коду у класифікаторі немає: позначити рядок для ручної перевірки |
| 429 | ліміт вичерпано | зачекати стільки секунд, скільки в заголовку Retry-After, і повторити |
Заголовки `X-RateLimit-Limit`, `X-RateLimit-Remaining` і `X-RateLimit-Reset` показують ліміт, залишок і момент скидання. Скрипт, що обробляє велике вивантаження, може перевіряти залишок і сам зупинятися, коли він наближається до нуля.
Зведення за галузями
Після того як кожен рядок вивантаження отримав секцію і розділ, аналіз стає звичайною задачею для таблиці чи бібліотеки обробки даних. Порахуйте кількість клієнтів і виручку за секціями, а для найбільших секцій розкладіть їх за розділами. Такий звіт відповідає на питання, з якими галузями компанія працює насправді, і часто відрізняється від того, що вважає відділ продажів.
Окремо варто подивитися на рядки з 404. Якщо їх багато, у джерелі даних коди вводилися вручну без перевірки, і це привід додати валідацію в систему, звідки прийшло вивантаження.
Перевірка кодів ФОП перед підключенням
Для сервісів, які працюють з підприємцями, скрипт може перевіряти всі коди ФОП перед підключенням. Логіка проста: для кожного коду класу дивимось статус і пояснення для групи підприємця. Якщо хоча б один код має статус, несумісний з обраною групою, підключення зупиняється до розмови з бухгалтером. Пояснення з поля `fop` можна показати людині дослівно, разом з посиланням на норму.
Кешування
Класифікатор змінюється рідко, шлюз тримає відповідь у кеші 1440 хвилин. На своєму боці можна зберігати відповіді назавжди, наприклад у файлі чи локальній базі: наступний запуск скрипта візьме відомі коди звідти і запитає лише нові.
| План | Запитів | Ціна, грн на місяць |
|---|---|---|
| Безкоштовний | 100 на добу | 0 |
| Старт | 10000 на місяць | 990 |
| Про | 100000 на місяць | 2990 |
Що робити
- Запустіть приклад з кодом 62.01 і подивіться повну відповідь.
- Зберіть унікальні коди з вашого вивантаження і пройдіть їх циклом з обробкою 400, 404 і 429.
- Збережіть відповіді локально і додайте до вивантаження колонки секції і назви.
- Коди компаній за ЄДРПОУ беріть з картки компанії, строки звітності для ФОП з податкового календаря.
- Опис полів у документації КВЕД, тарифи на сторінці Ціни і ліміти.
Питання і відповіді
Як отримати назву КВЕД у Python?
Запит requests.get до https://dani.initask.com/v1/kved/{code} з ключем у заголовку Authorization повертає JSON з полями name, section, division, group і для класу fop.
Що робити, якщо API повернув 429?
Ліміт вичерпано: зачекайте стільки секунд, скільки вказано в заголовку Retry-After, і повторіть запит.
Чи треба чистити формат кодів КВЕД перед запитом?
Ні, шлюз сам читає 62,01 як 62.01 і приймає малу літеру секції. Корисніше прибрати дублікати і питати кожен код один раз.