Translation. Original: limity/limity-api.md

Ліміти запитів API

22.11.2025

З огляду на масштаб роботи KSeF та його публічний характер, запроваджено механізми обмеження інтенсивності запитів API. Їхня мета — захист стабільності системи, захист від кіберзагроз та забезпечення рівних умов доступу для всіх користувачів. Ліміти визначають максимальну кількість запитів, які можна виконати в певний час, та забезпечують такий спосіб інтеграції, який відповідає припущенням архітектури системи.

Загальні принципи лімітів

1. Спосіб нарахування лімітів

Всі запити до API KSeF підлягають лімітам. Ці обмеження охоплюють кожен виклик захищеного endpoint. Для потреб обліку трафіку запити групуються за парою: контекст та IP-адреса.

• контекст - визначений ContextIdentifier (Nip, InternalId або NipVatUe), переданий при аутентифікації.
• IP-адреса - IP-адреса, з якої встановлюється мережеве з'єднання.

Ліміти запитів нараховуються незалежно для кожної пари: контекст та IP-адреса. Це означає, що трафік в тому ж контексті, але з різних IP-адрес, обліковується окремо.

Приклад
Бухгалтерська фірма A завантажує рахунки від імені компанії B, використовуючи контекст компанії B (NIP) та підключаючись до KSeF з адреси IP1. Одночасно компанія B завантажує рахунки самостійно, в тому ж контексті (своєму NIP), але з іншої IP-адреси — IP2. Незважаючи на спільний контекст, різні IP-адреси призводять до того, що ліміти нараховуються незалежно. У такій ситуації система розглядає кожне з'єднання як окрему пару (контекст + IP-адреса) і нараховує ліміти незалежно: окремо для бухгалтерської фірми A та окремо для компанії B.

Одиниці лімітів
В таблицях лімітів використовуються такі позначення:

• req/s - кількість запитів на секунду,
• req/min - кількість запитів на хвилину,
• req/h - кількість запитів на годину.

Модель нарахування лімітів (ковзне часове вікно - sliding/rolling window)
Ліміти виконуються в моделі ковзного часового вікна. В будь-який момент підраховуються запити, виконані в період:

• для порогу req/h - в останніх 60 хвилинах,
• для порогу req/min - в останніх 60 секундах,
• для порогу req/s - в останній секунді.

Вікна не вирівнюються до повних годин чи хвилин (не "скидаються" на :00). Всі пороги (req/s, req/min, req/h) діють паралельно — блокування активується при першому перевищенні будь-якого з них.

2. При перевищенні ліміту система блокує доступ до API

У випадку перевищення лімітів запитів API повертається код HTTP 429 Too Many Requests, а наступні запити тимчасово блокуються.
Період блокування є динамічним і залежить від частоти та масштабу перевищень. Точний час блокування повертається в заголовку відповіді Retry-After (в секундах). Багатократні перевищення можуть призвести до значного подовження блокування.

Приклад відповіді 429:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30

{
  "status": {
    "code": 429,
    "description": "Too Many Requests",
    "details": [ "Перевищено ліміт 20 запитів на хвилину. Спробуйте знову через 30 секунд." ]
  }
}

3. Реєстрація перевищень

Всі випадки перевищення лімітів запитів реєструються та аналізуються механізмами безпеки. Ці дані служать для моніторингу стабільності API та виявлення потенційних зловживань. Особливу увагу система приділяє шаблонам, що вказують на спроби обходу лімітів, наприклад через паралельне та системне використання кількох IP-адрес в рамках одного контексту. Такі дії можуть бути визнані загрозою безпеці.

У випадку повторних порушень або критичного навантаження система може автоматично застосувати захисні заходи, такі як:

• блокування доступу до API KSeF для даного суб'єкта або діапазону IP-адрес,
• обмеження доступності для найбільш навантажуючих контекстів.

4. Вищі ліміти в нічні години

В години 20:00-06:00 діють вищі ліміти завантаження, ніж вдень. Детальні значення будуть визначені в початковий період роботи KSeF 2.0, після налаштування параметрів до реального навантаження.

5. Попередні припущення лімітів

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

Реальний характер трафіку залежатиме від способу реалізації інтеграції в зовнішніх системах та від створюваних ними шаблонів навантаження. Це означає, що ліміти, встановлені на етапі проектування, можуть відрізнятися від значень, що підтримуються в продуктивному середовищі.

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

Ліміти на середовищах

Середовище TE (тестове) На середовищі TE ліміти налаштовані таким чином, щоб забезпечити вільну роботу інтеграторів та тестування інтеграції без ризику блокувань. Стандартні значення лімітів є у десять разів вищими ніж на продукції, що дозволяє проводити інтенсивні тести. Додатково, завдяки наданим endpoint-ам можна симулювати різні сценарії:

• POST /testdata/rate-limits/production - активує ліміти такі ж як на продукції (PRD),
• POST /testdata/rate-limits - дозволяє встановити власні значення,
• DELETE /testdata/rate-limits - відновлює стандартні ліміти середовища TE.

Середовище DEMO (препродуктивне) На середовищі DEMO діють такі ж ліміти як на продукції для даного контексту. Ці значення реплікуються з PRD і служать для фінальної валідації продуктивності та стабільності інтеграції перед продуктивним впровадженням.

Середовище PRD (продуктивне) На середовищі PRD застосовуються стандартні ліміти, визначені в цій документації. У обґрунтованих випадках — наприклад, великого масштабу обробки рахунків — передбачена можливість подання заяви на підвищення лімітів через спеціальну форму (в підготовці).

Завантаження рахунків - ліміти

Архітектурні припущення

API KSeF в області завантаження рахунків було розроблено як механізм синхронізації документів між центральним репозиторієм та локальною базою даних зовнішніх систем. Ключовим припущенням є те, що бізнес-операції, такі як пошук, фільтрація чи звітність, повинні виконуватися на даних, що зберігаються локально та були раніше синхронізовані з KSeF. Такий підхід підвищує стабільність роботи, мінімізує ризик перевантаження системи та дозволяє більш гнучке використання даних клієнтськими додатками.

API KSeF в сфері завантаження рахунків не призначене для обслуговування прямих операцій кінцевих користувачів в реальному часі. Це означає, що воно не повинно використовуватися для:

• завантаження окремих рахунків на вимогу користувача, наприклад перегляд рахунку,
• завантаження списку метаданих рахунків або ініціювання експорту пакетів у відповідь на поточні дії в додатку, за винятком ситуацій, коли користувач свідомо запускає синхронізацію даних.

Рекомендований спосіб інтеграції в сфері завантаження

Для поступової синхронізації використовується endpoint /invoices/query/metadata. Детальні принципи поступової синхронізації описані в окремому документі.

Залежно від обсягу рахунків можна застосовувати різні підходи до їх завантаження:

1. Сценарії низького обсягу - якщо кількість рахунків обмежена і можлива до обробки в рамках доступних лімітів в очікуваний час, можна завантажувати їх синхронно, викликаючи /invoices/ksef/{ksefNumber} для обраних документів.
2. Сценарії високого обсягу - якщо кількість документів значна і обробка в синхронному режимі стає непрактичною, рекомендується використання механізму експорту (/invoices/exports). Експорт працює асинхронно, ставиться в чергу і завдяки цьому не впливає негативно на продуктивність системи.
3. Бізнес-операції - незалежно від обраної стратегії, всі дії користувачів (пошук, фільтрація, звітність) повинні реалізовуватися на локальній базі даних, синхронізованій раніше з KSeF.

Режими синхронізації та завантаження рахунків

Завантаження рахунку до облікової системи може реалізовуватися в трьох режимах:

1. На вимогу користувача - поступова синхронізація запускається вручну користувачем від останньої підтвердженої контрольної точки.
2. Циклічно - поступова синхронізація виконується автоматично згідно з розкладом системи.
3. Змішаний режим - поступова синхронізація працює циклічно, а додатково користувач може запустити її вручну на вимогу.

Частота опитування

• Не рекомендуються розклади з високою частотою. В продуктивному середовищі циклічний інтервал не повинен бути коротшим ніж 15 хвилин для кожного суб'єкта, що фігурує на рахунку (Суб'єкт 1, Суб'єкт 2, Суб'єкт 3, Уповноважений суб'єкт).
• Профілі низького обсягу. Рекомендується завантаження на вимогу, доповнене циклом, наприклад раз на добу в нічному вікні.
• Дата отримання рахунку. Датою отримання рахунку є дата надання номера KSeF. Цей номер присвоюється автоматично системою в момент обробки рахунку і не залежить від моменту його завантаження до облікової системи.

Приклади нерекомендованої реалізації

Неправильна інтеграція може призвести до блокування в API. До найчастіших помилок належать:

1. Синхронізація виключно через завантаження окремих рахунків (синхронний шлях), без використання експорту пакетів рахунків. Такий підхід допустимий лише в профілях з низьким обсягом; при більшій кількості документів слід користуватися механізмом /invoices/exports.
2. Обслуговування запитів кінцевих користувачів (наприклад, відображення повного змісту рахунку в додатку, завантаження XML-файлу) через прямі виклики API KSeF замість використання локальної бази.

Детальні ліміти

Endpoint		req/s	req/min	req/h
Отримання списку метаданих рахунків	POST /invoices/query/metadata	8	16	20
Експорт пакету рахунків	POST /invoices/exports	8	16	20
Отримання статусу експорту пакету рахунків	/invoices/exports/	10	60	600
Отримання рахунку за номером KSeF	GET /invoices/ksef/	8	16	64

Увага: Якщо в бізнес-сценаріях організації доступні ліміти завантаження рахунків є недостатніми, просимо зв'язатися з відділом підтримки KSeF для індивідуального аналізу та підбору відповідного рішення.

Відправка рахунків - ліміти

Архітектурні припущення

• Відправка рахунків, незалежно від режиму, ставиться в чергу.
• Обробка оптимізована під якнайшвидше підтвердження правильності рахунку та надання номера KSeF.

Пакетна відправка (пакети рахунків):

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

• Один пакет, одне повідомлення в черзі.
  Пакет рахунків розглядається як одне повідомлення в черзі — як посилання на пакет, а не як окремий запис для кожного рахунку. Він обробляється з таким самим пріоритетом, як окремий документ.

• Менші комунікаційні витрати.
  Відправка в пакеті обмежує кількість HTTP-запитів та зменшує мережеві й операційні витрати на стороні клієнта та API.

• Ефективніша обробка багатьох документів.
  Операції з вмістом пакету, такі як розшифрування, валідація та запис, виконуються пакетно, що є найефективнішим способом обробки багатьох документів одночасно.

• Стиснення пакету.
  Пакетна відправка дозволяє передати багато рахунків як один стиснутий пакет.

  Для більших пакетів рекомендується використання формату tar.gz замість стандартного ZIP. tar.gz стискає весь пакет як один потік даних і краще використовує повторюваність структури XML між рахунками. ZIP стискає кожен файл окремо, тому дає гірший результат для великих наборів подібних документів.

• Ефективніше використання лімітів.
  Механізм лімітів працює незалежно від режиму відправки. Пакетна відправка за своєю природою зменшує кількість запитів до API, завдяки чому полегшує ефективне використання доступних лімітів. На практиці передати один пакет, що містить, наприклад, 100 рахунків, зазвичай вигідніше, ніж відправити 100 окремих рахунків в інтерактивній сесії.

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

Приклади сценаріїв застосування пакетного режиму:

• Інтернет-магазин (електронна комерція). Замовлення та платежі обробляються асинхронно, а рахунки виставляються автоматично системою ERP або модулем виставлення рахунків. Окремий рахунок не повинен відправлятися до KSeF негайно після виставлення. Виділений процес може агрегувати виставлені рахунки та циклічно — наприклад, кожні 5 хвилин — відправляти їх в пакетах до KSeF, що значно обмежує кількість HTTP-запитів і оптимізує використання лімітів.
• Підписні послуги / циклічні розрахунки. Рахунки генеруються збірно раз на день або раз на місяць (наприклад, в телекомунікаціях або медіа) і відправляються в одному пакеті в рамках запланованої пакетної сесії.
• Автоматизовані процеси виставлення рахунків на підприємствах. Зустрічаються, наприклад, в секторі дистрибуції, логістики, виробництва або послуг, замовлених в моделі B2B. Рахунки генеруються автоматично на основі системних подій (доставки, виконання замовлень) і відправляються збірно, наприклад після завершення операції.

Рекомендація: для забезпечення максимальної ефективності інтеграції рекомендується агрегувати документи в одній пакетній сесії скрізь, де це можливо з точки зору бізнес-процесів. Це дозволяє обмежити кількість запитів API та оптимізує використання доступних лімітів.

Детальні ліміти

Endpoint		req/s	req/min	req/h
Відкриття пакетної сесії *	POST /sessions/batch	10	20	60
Закриття пакетної сесії	POST /sessions/batch/{referenceNumber}/close	10	20	60

Відправка частини пакету - запити, що передають частини пакету в рамках однієї пакетної сесії, не підпадають під ліміти API. У випадку пакетів, поділених на декілька частин, рекомендується їх паралельна (багатопотокова) передача, що значно скорочує час відправки.

Інтерактивна відправка (поодиноко)

Інтерактивний режим розроблений для сценаріїв, що потребують швидкої реєстрації окремих рахунків та негайного отримання номера KSeF. На відміну від пакетної сесії, кожен рахунок передається незалежно в рамках активної інтерактивної сесії. Його мета — максимальне скорочення часу, потрібного для отримання номера KSeF для окремого документа. Застосування охоплює сценарії з низьким обсягом, в яких передаються окремі рахунки.

Приклади сценаріїв застосування інтерактивного режиму:

• Точка роздрібного продажу (POS). Після завершення транзакції виставляється рахунок, а система реєструє його негайно в KSeF і повертає номер KSeF для друку або презентації клієнту.
• Мобільні додатки та легкі системи продажу, що не мають механізму черг або буферизації, відправляють рахунки одразу після їх виставлення.
• Одиничні або нерегулярні події, наприклад окремий коригуючий рахунок.

Інтерактивний режим, незважаючи на більші мережеві витрати у випадку більших обсягів, є необхідним доповненням пакетного режиму в сценаріях, що потребують поточної реакції або негайної реєстрації документа в KSeF. Його слід застосовувати виключно там, де негайна обробка рахунку є ключовою для бізнес-процесу або коли масштаб операцій не виправдовує використання пакетної сесії.

Детальні ліміти

Endpoint		req/s	req/min	req/h
Відкриття інтерактивної сесії	POST /sessions/online	10	30	120
Відправка рахунку *	POST /sessions/online/{referenceNumber}/invoices	10	30	180
Закриття інтерактивної сесії	POST /sessions/online/{referenceNumber}/close	10	30	120

* Увага: Якщо в бізнес-сценаріях організації регулярно досягаються ліміти відправки в інтерактивній сесії, в першу чергу слід розглянути застосування пакетного режиму, який дозволяє ефективніше використовувати доступні ресурси та ліміти. У ситуаціях, коли використання інтерактивної сесії є необхідним, а досягнуті ліміти залишаються недостатніми, просимо зв'язатися з відділом підтримки KSeF для індивідуального аналізу та допомоги в підборі рішення.

Статус сесій та рахунків

Детальні ліміти

Endpoint		req/s	req/min	req/h
Отримання статусу рахунку із сесії	GET /sessions/{referenceNumber}/invoices/	30	120	1200
Отримання списку сесій	GET /sessions	5	10	60
Отримання рахунків сесії	GET /sessions/{referenceNumber}/invoices	10	20	200
Отримання неправильно оброблених рахунків сесії	GET /sessions/{referenceNumber}/invoices/failed	10	20	200
Інші	GET /sessions/*	10	120	1200

Інші

Стандартні ліміти діють для всіх ресурсів API, які не мають визначених детальних значень в цій документації. Кожен такий endpoint має власний лічильник лімітів, а його запити не впливають на інші ресурси.

Ці ліміти стосуються виключно захищених ресурсів. Вони не охоплюють публічні ресурси API, такі як /auth/challenge, які не потребують аутентифікації та мають власні механізми захисту — ліміт становить 60 запитів на секунду для однієї IP-адреси.

Endpoint		req/s	req/min	req/h
Інші	POST/GET /*	10	30	120

Пов'язані документи:

• Ліміти