Сертифікат KSeF чи токен: чому ми побудували Biurko на сертифікатах

Коли ми у 2025 році проєктували шар автентифікації в Biurko, було два шляхи. Простий: вставити токен, зберегти його в базі, отримати робочу інтеграцію з KSeF за тиждень. Складний: побудувати повну підтримку сертифікатів KSeF, включно з підписом XAdES-BES, зберіганням приватного ключа і контролем термінів дії.

Ми обрали складний. Це коштувало нам кількох тижнів і одного показового провалу на демо-середовищі, про який розкажу нижче.

Короткий контекст. KSeF (Krajowy System e-Faktur, польська національна система е-фактур) обовʼязковий для всіх підприємців у Польщі. Це не податкова консультація: я засновник SaaS, а не податковий радник. Це запис технічного рішення.

Токен і сертифікат не є двома версіями одного інструмента

Найпоширеніше непорозуміння: «токен і сертифікат це просто два способи входу, обери зручніший». Не зовсім так.

Міністерство фінансів формулює це однозначно: токен містить у собі повноваження платника, задекларовані в момент його генерування. Сертифікат KSeF є виключно засобом автентифікації, подібно до кваліфікованого електронного підпису, і жодних повноважень не переносить (Certyfikaty KSeF, ksef.podatki.gov.pl).

Останній рядок і є суттю. Токен працює як пароль: хто ним володіє, той і є вами. Сертифікат працює як підпис: KSeF надсилає challenge, ви підписуєте його приватним ключем, а сам ключ нікуди не передається.

Чотири причини, чому ми не зробили підтримку токенів

1. Приватний ключ не залишає системи. Токен доводиться передавати в KSeF при кожному відкритті сесії. Сертифікат ні: challenge підписується локально. Якщо ви будуєте SaaS, який зберігає облікові дані сотень компаній, це не косметична деталь.

2. Сертифікат типу Offline все одно потрібен. Щоб додати до фактури другий QR-код (KOD II) в офлайн-режимі, потрібен окремий сертифікат KSeF типу Offline. Сертифікати обох типів генеруються окремо і розрізняються позначкою «uwierzytelnianie» (автентифікація) або «offline» в атрибуті CN (ksef.podatki.gov.pl). Якщо сертифікати нам однаково потрібні заради офлайн-режиму, паралельна токенова гілка це подвійна робота.

3. Токеном не подати заявку на сертифікат. Автентифікація токеном не дозволяє подати заявку на сертифікат KSeF. Побудуйте весь процес на токені, і вам однаково доведеться повернутися до Profil Zaufany (польський довірений профіль, аналог Дія.Підпис), кваліфікованого підпису або кваліфікованої печатки. Це глухий кут за задумом.

4. Бухгалтерські бюро. Токен має вшитий обсяг повноважень для конкретної фірми. Бюро з 80 клієнтами це 80 токенів для генерування, зберігання і ротації. Сертифікат ідентифікує особу, а KSeF після входу вирішує, від імені яких компаній ця особа може діяти. Для бюро, що обслуговує багато фірм, це принципово інша модель даних.

Помилка, яку варто описати

Перша версія нашого тестового сідера генерувала self-signed сертифікат і намагалася автентифікуватися ним на демо-середовищі KSeF. Система відхилила зʼєднання. Сертифікат має бути виданий самим KSeF після автентифікації через Profil Zaufany, кваліфікований електронний підпис або кваліфіковану електронну печатку. Обхідного шляху немає, власного центру сертифікації теж.

Ми втратили на цьому два дні. Саме тому типовим першим підключенням компанії в Biurko є Profil Zaufany (можна також вказати власний сертифікат KSeF), а сертифікат замовляємо в Міністерстві вже після нього. Послідовність має значення.

Ще один момент: автентифікація сертифікатом вимагає реалізації підпису XAdES-BES, тож застосунок, що зʼєднується з API KSeF 2.0, має вміти його створювати. Тобто сертифікат корисний рівно настільки, наскільки його підтримує ваша програма.

Червень 2026: Міністерство пропонує залишити токени

9 червня 2026 року в Міністерстві фінансів відбулися перші консультації після часткового впровадження KSeF. Відомство запропонувало, щоб токени залишалися доступними і після 31 грудня 2026 року, з терміном дії від 1 до 365 днів і новим повноваженням на автоматичне поновлення (підсумок консультацій, ksef.podatki.gov.pl).

Важливо: це пропозиція з консультацій, а не чинні норми. За чинними правилами токени KSeF перестають діяти 31 грудня 2026 року, а акта, що їх зберігає, ще немає — безпечніше перейти на сертифікат KSeF. Перед операційним рішенням перевірте актуальні повідомлення на ksef.podatki.gov.pl.

Чи підриває це наше рішення? Ні, з нудної причини: жоден із чотирьох аргументів вище не звучав як «бо токени перестають діяти». Закінчення токенів було побічним ефектом нашої логіки, а не її підставою. Сертифікат типу Offline досі єдиний шлях до другого QR-коду (KOD II). Токеном досі не подати заявку на сертифікат. Модель безпеки досі інша.

Якби токени зникли, ми мали б рацію випадково. Якщо вони залишаться, ми маємо рацію з правильної причини.

Компроміси, про які постачальники не люблять говорити

Чесно: сертифікат не є безкоштовним обідом.

• Приватний ключ треба десь зберігати. Ми шифруємо його на рівні застосунку. Це відповідальність, якої токен на себе не бере.

• Сертифікат спливає. Максимум 2 роки. Хтось має за цим стежити, тому ми зробили завчасні попередження і видимий статус зʼєднання в панелі.

• Сертифікат фізичної особи діє в кількох контекстах. Якщо бухгалтерка має повноваження в пʼятьох фірмах, її сертифікат автентифікує її в усіх пʼятьох, а не в одній. Це зручно і водночас вимагає порядку в повноваженнях на стороні KSeF. Вужчий обсяг токена тут є його реальною перевагою.

• XAdES-BES це робота. Токен вставляється за 30 секунд. Сертифікат вимагав від нас обробки форматів PEM і P12, перевірки відповідності ключа сертифікату і звірки NIP (польський податковий номер), записаного в сертифікаті. Клієнт цього не бачить, і це правильно.

Одним реченням: токен швидший на старті, сертифікат кращий у довгій перспективі і потрібен, якщо ви хочете додати до офлайн-фактури другий QR-код (KOD II).

Чеклист для вашої фірми

1. Зʼясуйте, чим ви сьогодні входите в KSeF. Якщо токеном, встановіть, хто його згенерував і які повноваження туди вшито.

2. Перевірте, чи ваша бухгалтерська програма взагалі підтримує сертифікат KSeF типу Uwierzytelniający. Якщо ні, після завершення дії токенів ви не зможете підтримувати її зʼєднання з KSeF.

3. Замовте сертифікат типу Offline, якщо хочете мати реальний план Б на випадок аварії KSeF або відсутності інтернету — з другим QR-кодом (KOD II) на офлайн-фактурі.

4. Визначте, хто у фірмі має повноваження в KSeF. Сертифікат їх не надає, він ними користується.

5. Запишіть у календар дату закінчення сертифіката. Максимум 2 роки, і поновлення саме не станеться.

6. Стежте за повідомленнями Міністерства щодо токенів. Статус на сьогодні: пропозиція, а не норма.

Підсумок

Вибір між сертифікатом і токеном це не вибір між новим і старим. Це вибір між обліковим даним, яке несе повноваження, і обліковим даним, яке підтверджує особу і додає другий QR-код до офлайн-фактур. Для продукту, який має працювати навіть тоді, коли не працює сам KSeF, краще підходить друге.

У Biurko підтримка сертифікатів вбудована з першого дня: заявка, зберігання, моніторинг закінчення терміну, а для бухгалтерів — безкоштовне місце в кожній фірмі клієнта й перемикання між фірмами одним кліком. Вам не потрібно знати, що таке XAdES-BES. Створіть безкоштовний акаунт на biurko.io і підключіть першу фірму до KSeF.

FAQ

Чим сертифікат KSeF відрізняється від токена? Токен містить повноваження, надані в момент його генерування. Сертифікат KSeF підтверджує лише особу або субʼєкта, а повноваження система бере з KSeF після входу. Сертифікат також має термін дії (до 2 років) і потрібний для другого QR-коду (KOD II) в офлайн-режимі.

Чи перестануть токени KSeF працювати 31 грудня 2026 року? За чинними правилами токени KSeF перестають діяти 31 грудня 2026 року. На консультаціях 9 червня 2026 року Міністерство фінансів запропонувало їх зберегти, але рішення у формі акта ще немає — безпечніше перейти на сертифікат KSeF. Звіряйтеся з повідомленнями на ksef.podatki.gov.pl.

Чи можна подати заявку на сертифікат KSeF, увійшовши токеном? Ні. Автентифікація токеном не дозволяє подати заявку на сертифікат. Потрібен Profil Zaufany, кваліфікований електронний підпис або кваліфікована електронна печатка.

Скільки існує типів сертифіката KSeF? Два. Тип Uwierzytelniający служить для автентифікації в системі, тип Offline — для другого QR-коду (KOD II) на фактурах в офлайн-режимі. Вони видаються окремо, один сертифікат не покриває обидва застосування.

Чи потрібен сертифікат українському ФОП, зареєстрованому в Польщі як JDG? Якщо ви ведете JDG (jednoosobowa działalność gospodarcza, аналог ФОП), сертифікат KSeF може бути виданий вам за номером NIP або PESEL. Він потрібен для автоматичного входу з бухгалтерської програми а також потрібен, якщо хочете мати другий QR-код (KOD II) в офлайн-режимі.