Translation. Original: przeglad-kluczowych-zmian-ksef-api-2-0.md
KSeF API 2.0 – Обзор ключевых изменений
09.06.2025
Введение
Данный документ предназначен для технических команд и программистов, имеющих опыт работы с версией 1.0 API KSeF. Он содержит обзор наиболее важных изменений, внесенных в версию 2.0, с обсуждением новых возможностей и практических улучшений в интеграции.
Цель документа:
- Указать основные различия относительно версии 1.0
- Представить преимущества миграции на версию 2.0
- Облегчить подготовку интеграции к требованиям системы, внедряемым 1 февраля 2026 г.
Документация и инструменты, поддерживающие интеграцию с KSeF API 2.0
Чтобы облегчить переход на новую версию API и обеспечить правильную реализацию, предоставлен набор официальных материалов и инструментов, поддерживающих интеграторов:
Техническая документация (OpenAPI)
Версия 2.0 API KSeF была описана в стандарте OpenAPI, что позволяет как легко просматривать документацию программистами, так и автоматически генерировать интеграционный код.
Документация (интерактивная онлайн-версия):
Браузерный интерфейс в виде веб-страницы, представляющий описания методов API, модели данных, параметры и примеры использования. Предназначен для программистов и аналитиков интеграции: [link].Спецификация (файл JSON OpenAPI):
Исходный файл спецификации OpenAPI в формате JSON, предназначенный для использования в инструментах автоматизации интеграции (например, генераторы кода, валидаторы контрактов API): [link].
Официальная интеграционная библиотека KSeF 2.0 Client (open source)
Публичная библиотека, предоставляемая на условиях open source, разрабатываемая параллельно с новыми версиями API и поддерживаемая в полном соответствии со спецификацией. Является рекомендуемым интеграционным инструментом, позволяющим отслеживать изменения в текущем режиме и снижать риск несовместимости с актуальными выпусками системы.
Опубликованные пакеты
Библиотека KSeF 2.0 Client будет доступна в официальных репозиториях пакетов для наиболее популярных языков программирования. Для платформы .NET она будет опубликована как пакет NuGet, а для среды Java – как артефакт Maven Central. Публикация в этих репозиториях позволит легко включить библиотеку в проекты и автоматически отслеживать обновления, совместимые с последующими версиями API.
Пошаговое руководство
- Руководство по интеграции / tutorial:
Практические инструкции шаг за шагом с фрагментами кода, иллюстрирующими способ использования ключевых endpoints системы.
[link]
Ключевые изменения в API 2.0
Новая модель аутентификации на основе JWT
В версии 1.0 аутентификация была тесно связана с открытием интерактивной сессии, что вносило множество ограничений и усложняло интеграцию.
В версии 2.0:
Аутентификация была выделена как отдельный процесс, независимый от инициализации сессии.
Введены стандартные токены JWT, которые используются для авторизации всех защищенных операций.
Преимущества:
- соответствие рыночным практикам,
- возможность многократного использования токена для создания множества сессий,
- поддержка обновления и аннулирования токенов.
Подробности процесса аутентификации: [link]
Унифицированный процесс инициализации для пакетной и интерактивной сессии
В API 2.0 процесс открытия сессии был унифицирован и сделан независимым от режима работы. После получения аутентифицирующего токена можно открыть как интерактивную сессию: POST /sessions/online, так и пакетную: POST /sessions/batch.
В обоих случаях передается простой JSON, содержащий:
код формы (formCode),
зашифрованный ключ AES для шифрования данных счетов-фактур (encryptionKey).
В случае пакетной отправки также передается список частичных файлов с метаданными, входящими в состав пакета.
Подробности и примеры использования:
Обязательное шифрование всех счетов-фактур
В версии 1.0 шифрование счетов-фактур было обязательным только в пакетном режиме. В интерактивном режиме возможность шифрования существовала, но была опциональной.
В версии 2.0 шифрование всех счетов-фактур – как в пакетном, так и в интерактивном режиме – является обязательным.
Каждый счет-фактура или пакет счетов-фактур должен быть зашифрован локально клиентом с помощью ключа AES, который:
генерируется индивидуально для каждой сессии,
передается в систему при открытии сессии (encryptionKey).
Асимметричное шифрование
В версии 2.0 введено RSA-OAEP с SHA-256 и MGF1-SHA256. Шифрование токенов KSeF реализуется отдельным ключом, отличным от шифрования симметричного ключа, используемого для счетов-фактур.
Актуальные сертификаты открытых ключей возвращаются публичным endpoint: GET /security/public-key-certificates
Согласованность и новая конвенция именования в API 2.0
Одним из ключевых изменений в KSeF API 2.0 является унификация и упрощение конвенции именования ресурсов, параметров и моделей json. В версии 1.0 API содержал ряд несогласованностей и избыточной сложности, возникших в результате эволюции системы.
В версии 2.0:
Endpoints получили читаемое, REST-овое именование (например, sessions/online, auth/token, permissions/entities/grants).
Названия операций были упрощены и отражают фактическое действие (например, grant, revoke, refresh).
Упорядочена структура заголовков, параметров и форматов данных, чтобы она была согласованной и соответствовала лучшим практикам проектирования REST API.
Структуры данных являются плоскими и ясными – типы идентификаторов и разрешений имеют явно определенные типы enum (Nip, Pesel, Fingerprint), без необходимости анализа подтипов.
Изменения в версии 2.0 включают также обновление названий и структур данных. Хотя полная карта этих изменений не представлена в данном документе, она доступна в документации OpenAPI v2 и в примерах кода в официальном репозитории GitHub.
Следует подчеркнуть, что изменения не носят кардинального характера – не влияют на общую логику работы системы KSeF, а только упорядочивают и упрощают именование и структуры, делая API более прозрачным и интуитивным в использовании.
Миграция на версию 2.0 должна рассматриваться как изменение интеграционного контракта и требует адаптации реализации со стороны внешних систем. Рекомендуется использование официальной интеграционной библиотеки KSeF 2.0 Client, разрабатываемой и поддерживаемой командой, ответственной за API. Эта библиотека реализует все доступные endpoints и модели данных, что значительно облегчает процесс миграции и обеспечивает стабильную поддержку также в будущих версиях системы.
Новый модуль для управления внутренними сертификатами
В рамках версии KSeF API 2.0 введены механизмы, позволяющие выдавать и управлять внутренними сертификатами KSeF [ссылка на документацию]. Сертификаты будут позволять аутентификацию в KSeF и необходимы для выставления счета-фактуры в офлайн режиме [ссылка на документацию].
Субъекты, которые успешно пройдут процесс аутентификации, смогут:
подать заявку на выдачу внутреннего сертификата KSeF, содержащего выбранные атрибуты из сертификата подписи, используемого при аутентификации,
загрузить выданный сертификат в цифровом виде,
проверить статус поданной заявки на выдачу сертификата,
загрузить список метаданных выданных сертификатов,
проверить действующий лимит количества сертификатов.
Улучшение процесса пакетной отправки
В версии KSeF API 2.0 введено существенное усовершенствование в области обработки пакетных сессий. Предыдущее решение, доступное в API 1.0, было неэффективным – в случае, когда хотя бы один счет-фактура в пакете содержал ошибку, отклонялась вся отправка. Такой подход эффективно ограничивал использование пакетного режима интеграторами и вызывал значительные операционные затруднения.
В новом решении при отправке пакета документов:
каждый счет-фактура обрабатывается независимо,
возможные ошибки влияют только на конкретные счета-фактуры, а не на всю отправку,
количество ошибочных счетов-фактур возвращается для статуса сессии,
доступен специализированный endpoint, позволяющий загрузить детальный статус неправильно обработанных счетов-фактур вместе с информацией о возможной ошибке.
Это изменение значительно повышает надежность и эффективность пакетного режима и основывается на той же модели отправки пакетов без риска потери всего пакета из-за отдельных ошибок.
Верификация дубликатов счетов-фактур
Изменен способ обнаружения дубликатов – теперь проверяются бизнес-данные счета-фактуры (Podmiot1:NIP, RodzajFaktury, P_2), а не хеш файла. Подробности – Верификация дубликатов.
Изменение в модуле Разрешений
Изменения в модуле разрешений связаны с изменением некоторых аспектов логики их функционирования в KSeF 2.0.
В ответ на поступающие замечания, в версии 2.0 системы введен механизм предоставления разрешений косвенным способом, который заменяет действующий до сих пор принцип наследования разрешений на просмотр и выставление счетов-фактур. Новый интерфейс позволяет разделить просмотр счетов-фактур клиента (партнера) и возможность выставления счетов-фактур от его имени от просмотра счетов-фактур и выставления собственных счетов-фактур субъекта (например, бухгалтерского бюро).
Механизм заключается в предоставлении субъекту клиентом разрешения на просмотр или выставление счетов-фактур с включенной специальной опцией, разрешающей дальнейшую передачу этого разрешения уполномоченным субъектом. После получения такого разрешения субъект может предоставить его, например, своим сотрудникам. После выполнения этих действий данные сотрудники будут иметь возможность обслуживать указанного клиента в объеме, определенном предоставленными разрешениями.
Также возможно предоставление субъектом так называемых общих разрешений, которые позволяют уполномоченному таким образом сотруднику обслуживать всех клиентов субъекта – конечно, в таком объеме, в каком эти клиенты уполномочили данный субъект и с учетом объема разрешений сотрудника (на просмотр и/или выставление счетов-фактур).
Благодаря такому механизму предоставление и функционирование разрешений на просмотр и выставление счетов-фактур в рамках самого субъекта не связаны с разрешениями на обслуживание счетов-фактур клиентов. Это дает субъектам лучшие возможности профилирования разрешений сотрудников, чем ранее функционировавший в KSeF механизм наследования разрешений. Он заключался в предоставлении разрешений сотрудникам на просмотр и выставление счетов-фактур в рамках субъекта, а если субъект обладал соответствующими разрешениями от клиентов, то эти разрешения автоматически переходили к сотрудникам (наследовались). В результате – сотрудник мог обслуживать клиентов только тогда, когда одновременно имел право на просмотр и/или выставление счетов-фактур субъекта. А это во многих случаях было избыточным разрешением, что могло вызывать проблемы в организациях.
Кроме того, в системе введен новый тип разрешения и новые возможности входа в систему, что позволяет обслуживать самовыставление счетов-фактур субъектами ЕС. Возможен теперь вход в систему в контексте, определенном польским субъектом (идентифицируемым по NIP) и субъектом из страны ЕС, идентифицируемым номером VAT страны ЕС. В таком определенном контексте возможно выставление аутентифицированными представителями указанного субъекта ЕС счетов-фактур в режиме самовыставления от имени указанного польского субъекта.
В рамках определения API все разрешения были упорядочены в логические группы, соответствующие отдельным функциональным областям системы.
Лимиты вызовов API (rate limiting)
В версии KSeF API 2.0 введен точный и предсказуемый механизм ограничения количества вызовов (rate limits), который заменяет существующие решения, известные из версии 1.0. Каждый endpoint в системе охвачен лимитом количества запросов в заданных временных интервалах: в секунду, минуту, час.
Диапазоны и значения лимитов:
- публично предоставляются: лимиты API,
- дифференцированы в зависимости от среды (тестовая среда имеет менее ограничительные лимиты, чем продуктивная),
- адаптированы к характеру операций:
- для защищенных endpoints – лимиты применяются на контекст и IP-адрес,
- для открытых endpoints – лимиты применяются на IP-адрес.
Новая модель лимитов была разработана так, чтобы не ограничивать типичное тестирование приложений, интегрирующихся с системой. Это решение обеспечивает большую прозрачность, предсказуемость и лучшую устойчивость системы как в тестовых, так и в продуктивных средах.
Вспомогательный API для генерации тестовых данных (тестовая среда)
В тестовой среде KSeF API 2.0 будет предоставлен специализированный вспомогательный API для генерации тестовых данных, позволяющий быстро создавать фирмы, организационные структуры и контексты, необходимые для проведения интеграционных тестов.
Благодаря этому решению станет возможным, в частности:
симуляция создания нового хозяйствующего субъекта,
симуляция предоставления разрешений ZAW-FA,
создание единиц в рамках структуры JST,
создание налоговых групп VAT (GVAT) с связанными субъектами,
определение исполнительных органов и судебных приставов.
Стандартно процесс регистрации фирм и предоставления разрешений для реальных субъектов в продуктивной среде требует формальных действий (например, посещения налогового органа). В тестовой среде такие данные не существуют. Поэтому вспомогательный API является необходимым инструментом, позволяющим интеграторам самостоятельно создавать тестовых субъектов, на которых они могут свободно реализовывать и верифицировать полные сценарии работы своих приложений.