Translation. Original: limity/limity-api.md

Лимиты запросов API

22.11.2025

В связи с масштабом работы KSeF и его публичным характером введены механизмы ограничения интенсивности запросов API. Их цель - защита стабильности системы, защита от киберугроз и обеспечение равных условий доступа для всех пользователей. Лимиты определяют максимальное количество запросов, которые можно выполнить за определенное время, и принуждают к такому способу интеграции, который соответствует принципам архитектуры системы.

Общие принципы лимитов

1. Способ начисления лимитов

Все запросы к API KSeF подлежат лимитам. Эти ограничения охватывают каждый вызов защищенной конечной точки. Для целей учета трафика запросы группируются по паре: контекст и 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 лимиты настроены так, чтобы обеспечить свободную работу интеграторов и тестирование интеграции без риска блокировок. Стандартные значения лимитов в десять раз выше, чем в продакшене, что позволяет проводить интенсивные тесты. Дополнительно, благодаря предоставленным конечным точкам можно моделировать различные сценарии:

• 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 в области скачивания счетов не предназначено для обслуживания прямых операций конечных пользователей в реальном времени. Это означает, что оно не должно использоваться для:

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

Рекомендуемый способ интеграции в области скачивания

Для инкрементальной синхронизации используется конечная точка /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 вместо использования локальной базы.

Подробные лимиты

Конечная точка		req/s	req/min	req/h
Получение списка метаданных счетов	POST /invoices/query/metadata	8	16	20
Экспорт пакета счетов	POST /invoices/exports	4	8	20
Получение статуса экспорта пакета счетов	/invoices/exports/	10	60	600
Получение счета по номеру KSeF	GET /invoices/ksef/	8	16	64

Примечание: Если в бизнес-сценариях организации доступных лимитов скачивания счетов недостаточно, просим обратиться в службу поддержки KSeF для индивидуального анализа и подбора соответствующего решения.

Отправка счетов - лимиты

Архитектурные принципы

• Отправка счетов независимо от типа отправки ставится в очередь.
• Обработка оптимизирована для максимально быстрого подтверждения правильности счета и возврата номера KSeF.

Пакетная отправка (пакеты счетов):

• Пакет счетов рассматривается как одно сообщение в очереди (ссылка на пакет вместо отдельных записей для каждого счета) и обрабатывается с тем же приоритетом, что и отдельный документ.
• Отправка в пакете ограничивает сетевые и операционные издержки, поскольку:
  • выполняется меньшее количество HTTP-запросов,
  • операции с содержимым (расшифровка, валидация, запись) выполняются в пакетном режиме, что представляет наиболее эффективный способ обработки множества документов одновременно.
• Сжатие пакета. Благодаря XML-формату и высокой повторяемости элементов между счетами (постоянная структура, похожие названия полей, повторяющиеся блоки) достигается обычно очень благоприятный коэффициент сжатия, что значительно уменьшает объем данных и сокращает время передачи. На практике быстрее отправить один пакет, содержащий например 100 счетов, чем 100 отдельных счетов в интерактивной сессии.
• Лимиты. Механизм лимитов работает независимо от режима отправки. Пакетная отправка по своей природе уменьшает количество запросов и облегчает эффективное использование доступных лимитов.
• Применение. Пакетный режим рекомендуется везде, где в одном операционном окне передается более одного документа. В частности, хорошо подходит при циклических расчетах клиентов, в электронной коммерции и в автоматизированных процессах выставления счетов.

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

• Интернет-магазин (e-commerce). Заказы и платежи обрабатываются асинхронно, а счета выставляются автоматически системой ERP или модулем выставления счетов. Отдельный счет не должен отправляться в KSeF сразу после выставления. Выделенный процесс может агрегировать выставленные счета и циклически - например, каждые 5 минут - отправлять их в пакетах в KSeF, что значительно ограничивает количество HTTP-запросов и оптимизирует использование лимитов.
• Подписные услуги / циклические расчеты. Счета генерируются сводно раз в день или раз в месяц (например, в телекоммуникациях или медиа) и отправляются в одном пакете в рамках запланированной пакетной сессии.
• Автоматизированные процессы выставления счетов на предприятиях. Встречаются например в секторе дистрибуции, логистики, производства или услуг, заказываемых в модели B2B. Счета генерируются автоматически на основе системных событий (поставки, выполнение заказов) и отправляются сводно, например, после завершения операций.

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

Подробные лимиты

Конечная точка		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. Его следует применять исключительно там, где немедленная обработка счета критична для бизнес-процесса или когда масштаб операций не оправдывает использование пакетной сессии.

Подробные лимиты

Конечная точка		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 для индивидуального анализа и помощи в подборе решения.

Статус сессий и счетов

Подробные лимиты

Конечная точка		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, которые не имеют определенных подробных значений в данной документации. Каждая такая конечная точка имеет собственный счетчик лимитов, а ее запросы не влияют на другие ресурсы.

Эти лимиты касаются исключительно защищенных ресурсов. Они не охватывают публичные ресурсы API, такие как /auth/challenge, которые не требуют аутентификации и имеют собственные механизмы защиты - лимит составляет 60 запросов в секунду для одного IP-адреса.

Конечная точка		req/s	req/min	req/h
Остальные	POST/GET /*	10	30	120

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

• Лимиты