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 отдельных счетов в интерактивной сессии.

• Применение.
  Пакетный режим рекомендуется везде, где в одном операционном окне передаётся более одного документа. В частности, он хорошо подходит при циклических расчётах с клиентами, в электронной коммерции и в автоматизированных процессах выставления счетов.

Примерные сценарии применения пакетного режима:

• Интернет-магазин (e-commerce). Заказы и платежи обрабатываются асинхронно, а счета выставляются автоматически системой 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

Связанные документы:

• Лимиты