KSeF: як підключити систему продажів через токен і API

З 2026 року Національна система електронних фактур (KSeF) перестає бути опцією. Цей посібник крок за кроком показує, як технічно підключити систему продажів до KSeF: обрати метод автентифікації (токен або сертифікат), з'єднатися з API 2.0, виставити фактуру у структурі FA(3) і все протестувати в тестовому середовищі, перш ніж запуститься продакшн.

Від чого залежить термін і що саме потрібно підключити

Щоб підключити систему продажів до KSeF, потрібні три речі одночасно: метод автентифікації (авторизаційний токен або сертифікат KSeF), інтеграція з API KSeF 2.0 та генерування фактур у структурі FA(3) у форматі XML. Це і є повна відповідь на питання «як це підключити» — решта статті розкладає кожен із цих елементів на складові.

Але спершу про термін, бо саме від нього залежить, коли це має бути готове. З 1 лютого 2026 року діє цільова версія системи: єдиною прийнятою структурою фактури є FA(3), а єдиним робочим інтерфейсом — API KSeF 2.0. Старіші FA(2) та API 1.0 виводяться з експлуатації. Що важливо для кожного продавця: обов’язок отримувати фактури в KSeF стосується всіх платників податків уже з лютого 2026 — навіть якщо сам ти маєш виставляти лише з квітня.

Пороги та дати наводимо орієнтовно — перш ніж плануватимеш впровадження, звір їх із чинним законом і на ksef.podatki.gov.pl. Якщо ти лише розбираєшся в темі з боку бізнесу, почни з нашого огляду KSeF 2026 для продавців e-commerce, а тут зосередься на технічному рівні.

Автентифікація: токен, сертифікат KSeF чи печатка

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

Цим «сильним» методом першого входу є Profil Zaufany, кваліфікований електронний підпис (фізична особа, за PESEL/NIP) або кваліфікована електронна печатка (організація, за NIP). Весь цей процес обслуговує Модуль сертифікатів і повноважень (MCU), запущений 1 листопада 2025 року.

Повноваження надаються окремо для різних дій — зазвичай розділяють право на виставлення фактур, на їх перегляд і отримання та на керування повноваженнями (адміністративна роль). Інтеграції системи продажів потрібне повноваження на виставлення й отримання, прив’язане до суб’єкта або особи, від імені якої ти згенеруєш токен чи сертифікат. Визнач заздалегідь, хто в компанії є власником цієї конфігурації — саме він розблокує та заблокує доступ, коли ти зміниш постачальника програмного забезпечення.

Авторизаційний токен KSeF

Це найзручніший метод для інтеграції «система до системи». Токен генеруєш одноразово (після автентифікації сильним методом), а далі він служить для підпису наступних запитів до API — без щоразового звернення до підпису чи сертифіката. Дві речі, про які треба пам’ятати: токени з KSeF 1.0 не працюють у KSeF 2.0 (потрібно згенерувати новий), а самі токени 2.0 втрачають чинність 31 грудня 2026 року. З 1 січня 2027 їх замінюють сертифікати KSeF. Тож став до токена як до тимчасового рішення — і як до секрету: тримай поза репозиторієм коду, ротуй і обмежуй доступ.

Сертифікат KSeF (тип 1 і тип 2)

Сертифікати KSeF доступні з MCU від 1 листопада 2025 року, дійсні максимум 2 роки та поновлювані. Це не кваліфікований сертифікат у розумінні eIDAS, але він визнається всередині KSeF. Існує у двох типах: тип 1 виконує автентифікаційну функцію (як підпис/печатка у взаємодії з API), а тип 2 служить для цифрового підпису QR-кодів на фактурах, виставлених в офлайн-режимі. Це цільове рішення — якщо будуєш інтеграцію на роки, варто одразу спертися на сертифікат тип 1, а не на токен, що втрачає чинність.

Печатка, кваліфікований підпис і Profil Zaufany

Ці методи служать переважно для першого входу та надання повноважень. Кваліфікована електронна печатка автентифікує всю організацію (за NIP), а не конкретну особу — зручно для компанії, де інтеграцію підтримує кілька людей. Profil Zaufany — це найпростіший шлях для одноосібної підприємницької діяльності.

Структура FA(3): що змінюється порівняно з FA(2)

З 1 лютого 2026 єдиною чинною структурою фактури є FA(3). Якщо твоя система сьогодні генерує XML у FA(2), потрібно оновити мапінг. Найважливіші відмінності:

• Бінарні вкладення — до фактури можна долучити, наприклад, акт приймання чи специфікацію (у FA(2) це було неможливо).
• Нова роль «працівник» у вузлі Podmiot3.
• Уточнені поля термінів оплати — більше точності за розстрочених і кількох термінів.
• Розширені ліміти символів у назвах товарів і послуг (поле P_7).
• Підтримка JST і груп ПДВ — нові суб’єктні сценарії.

Ключове правило: згенерований XML має точно 1:1 відповідати схемі XSD, опублікованій Міністерством фінансів. Найменша невідповідність означає відхилення фактури, а відхилена фактура не отримує номера KSeF — тобто в очах системи не існує. Тому не «склеюй» XML вручну: використай бібліотеку або шар мапінгу даних замовлення на структуру та валідуй локально відносно XSD перед надсиланням. Актуальний XSD FA(3), специфікацію OpenAPI (Swagger), посібник інтегратора та готові SDK (Java, .NET) і приклади коду завантажиш із ksef.podatki.gov.pl. Окремий, поширений в e-commerce випадок — фактури до замовлень з marketplace і чеків — описуємо в тексті KSeF і продаж на Allegro.

На практиці найбільше відхилень виникає не через екзотичні поля, а через основи: хибний або відсутній NIP покупця, ставка ПДВ, неузгоджена з позицією, неправильний формат дати або суми, які не збігаються до гроша. Подбай також про коригувальні й авансові фактури — у FA(3) вони мають свої правила, а в e-commerce з’являються при поверненнях і передоплатах. Змапуй ці випадки одразу, замість того щоб додавати їх пізніше «на продакшні».

Тестове середовище KSeF 2.0 — тестуй, перш ніж запуститься продакшн

Міністерство фінансів надає три середовища. Здоровий сценарій такий: спершу тестове (розробка), потім передпродакшн (приймання), наприкінці — продакшн. Не починай із продакшну — там фактури мають реальні правові наслідки.

У тестовому середовищі можна використовувати self-signed сертифікати та згенерувати токен без «справжніх» документів, а тестові дії не впливають ані на повноваження, ані на продакшн-сертифікати. Якщо власної інтеграції ще немає, для ручної перевірки згодиться безкоштовний Застосунок платника податків KSeF 2.0 від MF, який теж має тестову версію (доступна з осені 2025). Адреси наводимо орієнтовно — завжди підтверджуй їх на ksef.podatki.gov.pl, бо деталі середовищ час від часу оновлюються.

Крок за кроком: підключення системи через API

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

1. Упорядкуй повноваження в MCU. Власник входить сильним методом (печатка / підпис / Profil Zaufany) і надає повноваження — наприклад, на виставлення й отримання фактур — потрібним особам і суб’єктам. Без цього ані токен, ані сертифікат не спрацюють.
2. Згенеруй ключ для автоматизації. У MCU створи авторизаційний токен або сертифікат KSeF тип 1. Збережи секрет у безпечному місці (менеджер секретів, змінні середовища), ніколи в коді.
3. Завантаж інтеграційні матеріали. Специфікація OpenAPI, схеми XSD для FA(3), SDK і посібник інтегратора є на ksef.podatki.gov.pl.
4. Налаштуй тестове середовище. Встанови базовий URL на тестову адресу та реалізуй потік challenge → підпис → токен: система отримує виклик, підписує його, а натомість дістає доступ до сесії.
5. Відкрий сесію в потрібному режимі. Інтерактивна сесія — це окремі фактури з миттєвою валідацією (документ до близько 1 МБ). Пакетна (batch) сесія — це пакет із багатьох фактур, що надсилається як ZIP-архів, поділений на частини — добра для великих обсягів, типових для e-commerce.
6. Надішли фактуру FA(3). Змапуй дані замовлення на XML FA(3), провалідуй локально відносно XSD, а потім надішли у відкритій сесії.
7. Отримай номер KSeF і UPO. Після успішної валідації система присвоює номер KSeF (35 символів), що повертається в UPO — офіційному підтвердженні отримання. Опитуй статус (орієнтовно: 150 = в опрацюванні, 200 = прийнято) і зберігай номер KSeF та UPO при замовленні.
8. Опрацюй помилки та повторні спроби. Відхилена фактура не має номера KSeF — виправ XML і надішли повторно. Побудуй чергу повторних спроб та лог відповідей, щоб нічого не зникло при тимчасових помилках.
9. Перейди на demo, потім на продакшн. Повтори тести в передпродакшн-середовищі, а після відповідного терміну (1 лютого або 1 квітня 2026) переключи конфігурацію на продакшн.

Якщо хочеш, щоб фактура створювалася сама після зміни статусу замовлення (наприклад, «оплачено» або «відправлено»), розглядай з’єднання з KSeF як частину ширшої автоматизації замовлень — інакше додаси команді ручної роботи замість того, щоб її зменшити.

Режими роботи: online, offline24 та аварійний

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

• Online (основний) — фактура потрапляє до KSeF одразу, номер KSeF отримуєш миттєво.
• Offline24 — виставляєш фактуру без з’єднання (префікс OFF, два QR-коди, другий підписаний сертифікатом продавця) і надсилаєш її до KSeF щонайпізніше наступного робочого дня.
• Аварійний — запускається офіційним повідомленням MF під час збою системи; фактури досилаєш у вікні до 7 робочих днів від завершення збою (терміни орієнтовні — звір при впровадженні).

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

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

Підключення до KSeF — це не разовий проєкт, а елемент, який треба підтримувати. Заплануй заздалегідь кілька речей. По-перше — ротацію секретів: токен втрачає чинність наприкінці 2026 року, а сертифікат дійсний до двох років, тож потрібен календар поновлень, щоб інтеграція не стала з дня на день. По-друге — моніторинг статусів: кожне надсилання має завершуватися підтвердженим номером KSeF, а все, що застрягло «в опрацюванні» або було відхилено, має потрапляти до видимого списку на обробку. По-третє — логи та архівацію: зберігай надісланий XML, номер KSeF та UPO, бо це твій доказ виставлення на випадок перевірки. По-четверте — середовище для регресії: коли MF оновить схему або API, перевір зміну в тестовому середовищі, перш ніж вона торкнеться продакшну.

Найчастіші помилки при підключенні (чек-лист)

• Використання старого токена з KSeF 1.0 — не спрацює у 2.0, згенеруй новий.
• Ручне «склеювання» XML замість мапінгу — дрібна помилка означає відхилення і відсутність номера KSeF.
• Тести одразу на продакшні — почни з тестового середовища.
• Відсутність наданих повноважень у MCU перед генеруванням токена.
• Ставлення до токена як до постійного рішення — пам’ятай про завершення чинності 31.12.2026 і перехід на сертифікат.
• Незбереження номера KSeF та UPO при замовленні — це твій доказ виставлення.
• Ігнорування обов’язку отримання — стосується всіх уже з лютого 2026.
• Відсутність плану на збій та офлайн-режим.

Для магазину, що продає на кількох каналах, найскладніше — не саме API, а зв’язування його з рештою обігу: замовлення з Allegro чи Shopify, коректні дані покупця, правильна ставка ПДВ і виставлення FA(3) у потрібний момент. Інструменти класу multichannel — зокрема Nimo, що готується, — мають у перспективі брати цей обіг на себе, щоб продавцеві не доводилося підтримувати власну інтеграцію з KSeF; як така обробка фактур KSeF має виглядати, описуємо окремо. Незалежно від вибору інструмента правило те саме: протестуй усе в тестовому середовищі, перш ніж фактури почнуть мати правові наслідки.

Найчастіші запитання

Мені потрібен сертифікат чи достатньо токена?

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

Чим відрізняється FA(3) від FA(2)?

FA(3) — це єдина чинна структура від 1 лютого 2026. Вона додає, зокрема, бінарні вкладення і роль «працівник», уточнює поля термінів оплати та розширює ліміти символів. Фактура має точно відповідати схемі XSD від MF, інакше буде відхилена.

Де тестувати інтеграцію?

Почни в тестовому середовищі KSeF 2.0 (орієнтовно api-test.ksef.mf.gov.pl та застосунок ap-test.ksef.mf.gov.pl), а потім перейди на передпродакшн (demo). Тестові дії не впливають на продакшн-дані. Актуальні адреси підтверди на ksef.podatki.gov.pl.

Що таке номер KSeF і UPO?

Номер KSeF — це унікальний ідентифікатор (35 символів), що присвоюється після успішної валідації — підтверджує, що фактура в обігу. UPO — це офіційне підтвердження отримання, в якому цей номер повертається. Обидва зберігай при замовленні як доказ виставлення.

З якого моменту я маю виставляти фактури в KSeF?

Найбільші (продажі брутто понад 200 млн zł у 2024 р.) — від 1 лютого 2026, решта підприємців — від 1 квітня 2026, а найменші виставники — від 1 січня 2027. Отримання фактур у KSeF обов’язкове для всіх уже з лютого 2026.