Коли ми у 2025 році проєктували шар автентифікації в Biurko, було два шляхи. Простий: вставити токен, зберегти його в базі, отримати робочу інтеграцію з KSeF за тиждень. Складний: побудувати повну підтримку сертифікатів KSeF, включно з підписом XAdES-BES, зберіганням приватного ключа і контролем термінів дії.
Ми обрали складний. Це коштувало нам кількох тижнів і одного показового провалу на демо-середовищі, про який розкажу нижче.
Короткий контекст. KSeF (Krajowy System e-Faktur, польська національна система е-фактур) обовʼязковий для всіх підприємців у Польщі. Це не податкова консультація: я засновник SaaS, а не податковий радник. Це запис технічного рішення.
Токен і сертифікат не є двома версіями одного інструмента
Найпоширеніше непорозуміння: «токен і сертифікат це просто два способи входу, обери зручніший». Не зовсім так.
Міністерство фінансів формулює це однозначно: токен містить у собі повноваження платника, задекларовані в момент його генерування. Сертифікат KSeF є виключно засобом автентифікації, подібно до кваліфікованого електронного підпису, і жодних повноважень не переносить (Certyfikaty KSeF, ksef.podatki.gov.pl).
Токен Сертифікат KSeF Що це буквено-цифровий рядок пара ключів і сертифікат, виданий Міністерством Повноваження вшиті всередині визначає KSeF після входу Термін дії безстроковий (до 31.12.2026 за початковим планом) до 2 років Офлайн-режим не підтримує обовʼязковий сертифікат типу 2 Заявка на сертифікат неможлива можлива Модель безпеки bearer-секрет приватний ключ і підпис XAdES-BES
Останній рядок і є суттю. Токен працює як пароль: хто ним володіє, той і є вами. Сертифікат працює як підпис: KSeF надсилає challenge, ви підписуєте його приватним ключем, а сам ключ нікуди не передається.
Чотири причини, чому ми не зробили підтримку токенів
1. Приватний ключ не залишає системи. Токен доводиться передавати в KSeF при кожному відкритті сесії. Сертифікат ні: challenge підписується локально. Якщо ви будуєте SaaS, який зберігає облікові дані сотень компаній, це не косметична деталь.
2. Сертифікат типу 2 однаково обовʼязковий. Щоб позначити фактуру QR-кодом в офлайн-режимі, потрібен окремий сертифікат KSeF типу 2. Сертифікати обох типів генеруються окремо і розрізняються позначкою «uwierzytelnianie» (автентифікація) або «offline» в атрибуті CN (ksef.podatki.gov.pl). Якщо сертифікати нам однаково потрібні заради offline24, паралельна токенова гілка це подвійна робота.
3. Токеном не подати заявку на сертифікат. Автентифікація токеном не дозволяє подати заявку на сертифікат KSeF. Побудуйте весь процес на токені, і вам однаково доведеться повернутися до Profil Zaufany (польський довірений профіль, аналог Дія.Підпис), кваліфікованого підпису або кваліфікованої печатки. Це глухий кут за задумом.
4. Бухгалтерські бюро. Токен має вшитий обсяг повноважень для конкретної фірми. Бюро з 80 клієнтами це 80 токенів для генерування, зберігання і ротації. Сертифікат ідентифікує особу, а KSeF після входу вирішує, від імені яких компаній ця особа може діяти. Для мультифірмової панелі це принципово інша модель даних.
Помилка, яку варто описати
Перша версія нашого тестового сідера генерувала self-signed сертифікат і намагалася автентифікуватися ним на демо-середовищі KSeF. Система відхилила зʼєднання. Сертифікат має бути виданий самим KSeF після автентифікації через Profil Zaufany, кваліфікований електронний підпис або кваліфіковану електронну печатку. Обхідного шляху немає, власного центру сертифікації теж.
Ми втратили на цьому два дні. Саме тому першим підключенням компанії в Biurko є Profil Zaufany, а заявку на сертифікат подаємо вже після нього. Послідовність має значення.
Ще один момент: сертифікатом KSeF не увійти до безкоштовних інструментів Міністерства. Сертифікат типу 1 працює в комерційних застосунках, інтегрованих з API KSeF 2.0, бо його використання вимагає реалізації підпису XAdES-BES. Тобто сертифікат корисний рівно настільки, наскільки його підтримує ваша програма.
Червень 2026: Міністерство хоче залишити токени
9 червня 2026 року в Міністерстві фінансів відбулися перші консультації після часткового впровадження KSeF. Відомство запропонувало, щоб токени залишалися доступними і після 31 грудня 2026 року, з терміном дії від 1 до 365 днів і новим повноваженням на автоматичне поновлення (підсумок консультацій, ksef.podatki.gov.pl).
Важливо: це пропозиція з консультацій, а не чинні норми. До публікації зміненого розпорядження діє початковий графік, за яким токени завершуються 31 грудня 2026 року. Перед операційним рішенням перевірте актуальні повідомлення на ksef.podatki.gov.pl.
Чи підриває це наше рішення? Ні, з нудної причини: жоден із чотирьох аргументів вище не звучав як «бо токени зникають». Закінчення токенів було побічним ефектом нашої логіки, а не її підставою. Сертифікат типу 2 досі єдиний шлях до offline24. Токеном досі не подати заявку на сертифікат. Модель безпеки досі інша.
Якби токени зникли, ми мали б рацію випадково. Оскільки вони залишаються, ми маємо рацію з правильної причини.
Компроміси, про які постачальники не люблять говорити
Чесно: сертифікат не є безкоштовним обідом.
Приватний ключ треба десь зберігати. Ми шифруємо його на рівні застосунку і логуємо кожну операцію автентифікації. Це відповідальність, якої токен на себе не бере.
Сертифікат спливає. Максимум 2 роки. Хтось має за цим стежити, тому ми зробили завчасні попередження і видимий статус зʼєднання в панелі.
Сертифікат фізичної особи діє в кількох контекстах. Якщо бухгалтерка має повноваження в пʼятьох фірмах, її сертифікат автентифікує її в усіх пʼятьох, а не в одній. Це зручно і водночас вимагає порядку в повноваженнях на стороні KSeF. Вужчий обсяг токена тут є його реальною перевагою.
XAdES-BES це робота. Токен вставляється за 30 секунд. Сертифікат вимагав від нас обробки форматів PEM і P12, перевірки відповідності ключа сертифікату і звірки NIP (польський податковий номер), записаного в сертифікаті. Клієнт цього не бачить, і це правильно.
Одним реченням: токен швидший на старті, сертифікат кращий у довгій перспективі і безальтернативний, якщо ви хочете виставляти фактури офлайн.
Чеклист для вашої фірми
Зʼясуйте, чим ви сьогодні входите в KSeF. Якщо токеном, встановіть, хто його згенерував і які повноваження туди вшито.
Перевірте, чи ваша бухгалтерська програма взагалі підтримує сертифікат KSeF типу 1. Якщо ні, режим offline24 для вас закритий.
Згенеруйте сертифікат типу 2, якщо хочете мати реальний план Б на випадок аварії KSeF або відсутності інтернету.
Визначте, хто у фірмі має повноваження в KSeF. Сертифікат їх не надає, він ними користується.
Запишіть у календар дату закінчення сертифіката. Максимум 2 роки, і поновлення саме не станеться.
Стежте за повідомленнями Міністерства щодо токенів. Статус на сьогодні: пропозиція, а не норма.
Підсумок
Вибір між сертифікатом і токеном це не вибір між новим і старим. Це вибір між обліковим даним, яке несе повноваження, і обліковим даним, яке підтверджує особу і відкриває офлайн-фактурування. Для продукту, який має працювати навіть тоді, коли не працює сам KSeF, підходить лише друге.
У Biurko підтримка сертифікатів вбудована з першого дня: заявка, зберігання, моніторинг закінчення терміну, мультифірмова панель для бухгалтерських бюро. Вам не потрібно знати, що таке XAdES-BES. Створіть безкоштовний акаунт на biurko.io і підключіть першу фірму до KSeF.
FAQ
Чим сертифікат KSeF відрізняється від токена? Токен містить повноваження, надані в момент його генерування. Сертифікат KSeF підтверджує лише особу або субʼєкта, а повноваження система бере з KSeF після входу. Сертифікат також має термін дії (до 2 років) і є обовʼязковим для офлайн-режиму.
Чи перестануть токени KSeF працювати 31 грудня 2026 року? Такий був початковий графік. Після консультацій 9 червня 2026 року Міністерство фінансів запропонувало залишити токени як постійний метод входу з терміном дії від 1 до 365 днів. Це поки що пропозиція, а не норма, тому звіряйтеся з повідомленнями на ksef.podatki.gov.pl.
Чи можна подати заявку на сертифікат KSeF, увійшовши токеном? Ні. Автентифікація токеном не дозволяє подати заявку на сертифікат. Потрібен Profil Zaufany, кваліфікований електронний підпис або кваліфікована електронна печатка.
Скільки існує типів сертифіката KSeF? Два. Тип 1 служить для автентифікації в системі, тип 2 для позначення фактур QR-кодом в офлайн-режимі. Вони видаються окремо, один сертифікат не покриває обидва застосування.
Чи потрібен сертифікат українському ФОП, зареєстрованому в Польщі як JDG? Якщо ви ведете JDG (jednoosobowa działalność gospodarcza, аналог ФОП), сертифікат KSeF може бути виданий вам за номером NIP або PESEL. Він потрібен для автоматичного входу з бухгалтерської програми і обовʼязковий, якщо плануєте користуватися офлайн-режимом.