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:
Практичні інструкції крок за кроком разом з фрагментами коду, що ілюструють спосіб використання ключових endpoint'ів системи.
[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:
Endpoint'и отримали читабельні, 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. Ця бібліотека реалізує всі доступні endpoint'и та моделі даних, що значно полегшує процес міграції та забезпечує стабільну підтримку також у майбутніх версіях системи.
Новий модуль для управління внутрішніми сертифікатами
В рамках версії KSeF API 2.0 впроваджено механізми, що дозволяють видавати та управляти внутрішніми сертифікатами KSeF [link до документації]. Сертифікати дозволятимуть автентифікацію в KSeF та є необхідними для виставлення рахунку в offline режимі [link до документації].
Суб'єкти, які успішно пройдуть процес автентифікації, зможуть:
подати заявку на видачу внутрішнього сертифіката KSeF, що містить вибрані атрибути з сертифіката підпису, використаного під час автентифікації,
завантажити виданий сертифікат у цифровому вигляді,
перевірити статус поданої заявки на видачу сертифіката,
завантажити список метаданих виданих сертифікатів,
перевірити належний ліміт кількості сертифікатів.
Удосконалення процесу пакетного відправлення
У версії KSeF API 2.0 впроваджено істотне удосконалення в області обробки пакетних сесій. Попереднє рішення, доступне в API 1.0, було неефективним – у випадку, коли хоча б один рахунок у пакеті містив помилку, відхилялося все відправлення. Такий підхід ефективно обмежував використання пакетного режиму інтеграторами та спричиняв значні операційні труднощі.
У новому рішенні при відправленні пакета документів:
кожен рахунок обробляється незалежно,
можливі помилки впливають виключно на конкретні рахунки, а не на весь пакет,
кількість помилкових рахунків повертається для статусу сесії,
доступний спеціальний endpoint, що дозволяє завантажити детальний статус неправильно оброблених рахунків разом з інформацією про можливу помилку.
Ця зміна значно підвищує надійність та ефективність пакетного режиму та базується на тій же моделі відправлення пакетів без ризику втрати всього пакета через окремі помилки.
Верифікація дублікатів рахунків
Змінено спосіб виявлення дублікатів – наразі перевіряються бізнес-дані рахунку (Podmiot1:NIP, RodzajFaktury, P_2), а не хеш файлу. Деталі – Weryfikacja duplikatów.
Зміна в модулі Дозволів
Зміни в модулі дозволів пов'язані зі зміною деяких аспектів логіки їх функціонування в KSeF 2.0.
У відповідь на заявлені зауваження, у версії 2.0 системи впроваджено механізм надання дозволів опосередкованим способом, який замінює попередній принцип успадкування дозволів на перегляд та виставлення рахунків. Новий інтерфейс дозволяє розділити перегляд рахунків клієнта (партнера) та можливість виставляння рахунків від його імені від перегляду рахунків та виставлення рахунків власного суб'єкта (наприклад, бухгалтерського бюро).
Механізм полягає в наданні суб'єкту клієнтом дозволу на перегляд або виставлення рахунків з увімкненою спеціальною опцією, що дозволяє подальше передавання цього дозволу уповноваженим суб'єктом. Після отримання такого дозволу суб'єкт може надати його, наприклад, своїм працівникам. Після виконання цих дій ці працівники матимуть можливість обслуговувати вказаного клієнта в обсязі, визначеному наданими дозволами.
Можливо також надання суб'єктом так званих генеральних дозволів, які дозволяють уповноваженому таким чином працівнику обслуговувати всіх клієнтів суб'єкта – звичайно, в такому обсязі, в якому ці клієнти уповноважили цей суб'єкт і з урахуванням обсягу дозволів працівника (на перегляд та/або виставлення рахунків).
Завдяки такому механізму надання та функціонування дозволів на перегляд та виставлення рахунків в рамках самого суб'єкта не пов'язані з дозволами на обслуговування рахунків клієнтів. Це дає суб'єктам кращі можливості профілювання дозволів працівників, ніж раніше функціональний в KSeF механізм успадкування дозволів. Він полягав у наданні дозволів працівникам на перегляд та виставлення рахунків в рамках суб'єкта, а якщо суб'єкт мав відповідні дозволи від клієнтів, то ці дозволи автоматично переходили на працівників (успадковувалися). В результаті – працівник міг обслуговувати клієнтів виключно тоді, коли водночас мав право на перегляд та/або виставлення рахунків суб'єкта. А це в багатьох випадках було надмірним дозволом, що могло спричиняти проблеми в організаціях.
Крім того, в системі впроваджено новий тип дозволу та нові можливості входу в систему, що дозволяє обслуговування самофактурування європейськими суб'єктами. Можливий наразі вхід в контексті, визначеному польським суб'єктом (ідентифікованим через NIP) та суб'єктом з країни ЄС, ідентифікованим номером VAT європейської країни. В такому визначеному контексті можливе виставлення автентифікованими представниками зазначеного європейського суб'єкта рахунків в режимі самофактурування від імені зазначеного польського суб'єкта.
В рамках визначення API всі дозволи були впорядковані в логічні групи, що відповідають окремим функціональним областям системи.
Ліміти викликів API (rate limiting)
У версії KSeF API 2.0 впроваджено точний та передбачуваний механізм обмежень кількості викликів (rate limits), який замінює попередні рішення, відомі з версії 1.0. Кожен endpoint в системі охоплений лімітом кількості запитів в заданих часових інтервалах: на секунду, хвилину, годину.
Діапазони та значення лімітів є:
- публічно доступними: limity API,
- диференційованими залежно від середовища (тестове середовище має менш обмежувальні ліміти, ніж продуктивне),
- пристосованими до характеру операцій:
- для захищених endpoint'ів – ліміти застосовуються per контекст та IP-адресу,
- для відкритих endpoint'ів – ліміти застосовуються per IP-адресу.
Нова модель лімітів була спроектована так, щоб не обмежувати типове тестування додатків, що інтегруються з системою. Це рішення забезпечує більшу прозорість, передбачуваність та кращу стійкість системи як в тестових, так і в продуктивних середовищах.
Допоміжне API для генерування тестових даних (тестове середовище)
В тестовому середовищі KSeF API 2.0 буде надане спеціальне допоміжне API для генерування тестових даних, що дозволяє швидко створювати компанії, організаційні структури та контексти, необхідні для проведення інтеграційних тестів.
Завдяки цьому рішенню буде можливо, зокрема:
симулювання заснування нового господарського суб'єкта,
симуляція надання дозволів через ZAW-FA,
створення підрозділів в рамках структури JST,
створення податкових груп VAT (GVAT) разом з пов'язаними суб'єктами,
визначення органів виконання та судових виконавців.
Стандартно процес реєстрації компаній та надання дозволів для реальних суб'єктів в продуктивному середовищі вимагає формальних дій (наприклад, візити до податкової інспекції). В тестовому середовищі такі дані не існують. Тому допоміжне API є необхідним інструментом, що дозволяє інтеграторам самостійно створювати тестові суб'єкти, на яких вони можуть вільно реалізовувати та перевіряти повні сценарії роботи своїх додатків.