Сертифікат KSeF чи токен: як підключити CRM і магазин до API KSeF 2.0
Як CRM, інтернет-магазин або B2B-кабінет входить в API KSeF 2.0: токен чи сертифікат KSeF, строк дії токенів після 2026 року згідно з проєктом від 27.10.2026, як отримати сертифікат, офлайн-сертифікат, а також середовища TEST і DEMO.
Коротко
- CRM, інтернет-магазин або B2B-кабінет, який сам надсилає рахунки-фактури в KSeF (польську систему електронних рахунків-фактур), входить в API KSeF 2.0 за допомогою токена KSeF або сертифіката KSeF для автентифікації. Обидва способи діють паралельно.
- Згідно з чинним розпорядженням токени діють до 31 грудня 2026 року. Міністерство фінансів Польщі оголосило, що цей спосіб залишиться, а проєкт змін до розпорядження від 27 жовтня 2026 року передбачає, що наявні токени діятимуть до 30 листопада 2027 року, а нові щонайбільше 365 днів. Станом на 14 листопада 2026 року це лише проєкт.
- Сертифікат KSeF діє щонайбільше 2 роки. Заявку на нього ви подаєте в Aplikacja Podatnika KSeF 2.0 (безкоштовному застосунку Мінфіну) або через API, увійшовши через довірений профіль Profil Zaufany, кваліфікованим підписом або кваліфікованою печаткою. Токеном сертифікат замовити не можна.
- Для рахунків-фактур в офлайн-режимі потрібен окремий офлайн-сертифікат: без нього система не згенерує другий QR-код.
- Інтеграцію спершу перевіряють у середовищі TEST, потім у DEMO і лише наприкінці в робочому середовищі.
Як CRM або інтернет-магазин входить в API KSeF 2.0?
Програма, яка надсилає рахунки-фактури в KSeF без участі людини, не входить за паролем. Під час кожного підключення вона проходить коротку процедуру: отримує з KSeF одноразовий виклик (challenge), підтверджує його токеном або підписом сертифікатом, а натомість отримує токен доступу, яким надсилає й завантажує рахунки-фактури. Токен доступу діє кільканадцять хвилин, а токен оновлення щонайбільше 7 днів. Після цього система має пройти автентифікацію заново.
| Крок | Запит до API | Що треба знати |
|---|---|---|
| 1. Виклик (challenge) | POST /auth/challenge | Виклик дійсний 10 хвилин. |
| 2а. Сертифікат | POST /auth/xades-signature | Система підписує XML-документ із викликом і NIP (польським податковим номером) підписом XAdES: сертифікатом KSeF, кваліфікованим підписом або кваліфікованою печаткою. |
| 2б. Токен KSeF | POST /auth/ksef-token | Система надсилає токен разом із часовою позначкою з виклику, зашифрований публічним ключем Міністерства фінансів. |
| 3. Статус | GET /auth/{referenceNumber} | Запит повторюють, доки не буде результату. Кваліфікований підпис його видавець може перевіряти довше, сертифікат KSeF перевіряється одразу. |
| 4. Токени доступу | POST /auth/token/redeem | Повертає токен доступу і токен оновлення. Повторний запит із тим самим токеном автентифікації завершується помилкою. |
| 5. Оновлення | POST /auth/token/refresh | Новий токен доступу без повторного входу, доки діє токен оновлення. |
Токен чи сертифікат KSeF: що обрати для інтеграції?
Згідно з FAQ Міністерства фінансів, токен і сертифікат діють паралельно, а зовнішня система може користуватися одним або другим. Вони відрізняються способом отримання, строком дії і тим, що ще дозволяють зробити.
| Ознака | Токен KSeF | Сертифікат KSeF (автентифікація) |
|---|---|---|
| Що це | Рядок символів, згенерований у KSeF із визначеним обсягом прав, наприклад надсилання і читання рахунків-фактур. | Електронне підтвердження особи людини або компанії з парою ключів. Приватний ключ залишається у вас. |
| Як отримати | Ви генеруєте його в Aplikacja Podatnika KSeF 2.0 або через API (POST /tokens) після входу. | Заявка в Aplikacja Podatnika KSeF 2.0 або через API після входу через Profil Zaufany, кваліфікованим підписом або кваліфікованою печаткою. |
| Строк дії | Чинні норми: до 31.12.2026. Проєкт від 27.10.2026: наявні токени до 30.11.2027, нові щонайбільше 365 днів. | Щонайбільше 2 роки, з можливістю поновлення протягом строку дії. |
| Права доступу | Записані в токені. Зміна обсягу прав означає новий токен. | Сертифікат їх не містить: KSeF перевіряє права людини або компанії, на яку його видано. |
| Вимоги до системи | Шифрування токена публічним ключем Мінфіну. | Підпис XAdES документа автентифікації. |
| Обмеження | Увійшовши токеном, ви не створите сертифікат KSeF. | Ним не можна увійти в Aplikacja Podatnika KSeF: він призначений для систем, які підключаються через API. |
Токен простіший на старті, бо системі не потрібно підписувати документи XAdES. Сертифікат дає довший і передбачуваний строк дії, а в інтеграції, яку ви будуєте сьогодні, має ще одну перевагу: він не залежить від того, чим закінчиться зміна норм щодо токенів. Найбезпечніше побудувати інтеграцію так, щоб спосіб входу можна було змінити в налаштуваннях, без переробки програми.
Як отримати сертифікат KSeF крок за кроком?
З лютого 2026 року заявку на сертифікат подають в Aplikacja Podatnika KSeF 2.0 або через API KSeF 2.0. Модуль сертифікатів і прав доступу (Moduł Certyfikatów i Uprawnień, MCU), у якому сертифікати видавали з листопада 2025 року, працював до кінця січня 2026 року. У застосунку це виглядає так:
- Увійдіть в Aplikacja Podatnika KSeF 2.0 через Profil Zaufany (на login.gov.pl), кваліфікованим підписом або кваліфікованою печаткою компанії. Перевірте, що працюєте в контексті потрібного NIP.
- Відкрийте вкладку «Certyfikaty» (сертифікати) і виберіть «Wnioskuj o certyfikat» (подати заявку на сертифікат). Дані для заявки застосунок бере з даних входу.
- Виберіть призначення: автентифікація або офлайн-режим. Один сертифікат має одне призначення, тож для обох потрібні дві заявки.
- Захистіть приватний ключ. Пара ключів створюється під час заявки, а до Міністерства потрапляє лише публічний ключ. Без приватного ключа сертифікат марний, а той, хто ним володіє, може діяти від вашого імені в межах ваших прав.
- Завантажте сертифікат і додайте його в систему разом із приватним ключем, безпечним каналом. Не надсилайте ключ електронною поштою.
- Запишіть дату закінчення строку дії. Наступний сертифікат можна замовити ще до того, як мине строк дії попереднього. Налаштуйте нагадування щонайменше за місяць.
Система може також подати заявку сама, через API: перевіряє ліміти (GET /certificates/limits), завантажує дані для заявки (GET /certificates/enrollments/data), надсилає запит CSR у форматі PKCS#10 (POST /certificates/enrollments), перевіряє статус і завантажує сертифікат (POST /certificates/retrieve). Документація допускає ключі RSA 2048 і EC P-256 і рекомендує EC. Відкликати сертифікат може лише його власник, наприклад після витоку ключа (POST /certificates/{numer}/revoke), а відкликаний сертифікат відновити неможливо.
Чий сертифікат має бути в системі компанії?
Сертифікат підтверджує особу, але не надає прав. Під час кожного підключення KSeF перевіряє, що дозволено людині або компанії, на яку видано сертифікат. Згідно з FAQ Міністерства фінансів, сертифікат може отримати фізична особа, яку ідентифікують за номером NIP або PESEL (польським ідентифікаційним номером), а також компанія, яка входить кваліфікованою печаткою. Сертифікатом компанії можна ділитися з працівниками, а сертифікат JDG (jednoosobowa działalność gospodarcza, польський аналог ФОП) є особистим.
- Сертифікат компанії (кваліфікована печатка): інтеграція не залежить від однієї людини. Це розумний вибір для CRM або інтернет-магазину, який виставляє рахунки-фактури всієї компанії.
- Сертифікат працівника: діє, доки цей працівник має права в KSeF для компанії. Коли він звільниться і втратить права, система перестане надсилати рахунки-фактури.
- Бухгалтерське бюро або зовнішній постачальник: входить власним сертифікатом і діє в межах прав, наданих компанією. Проєкт змін до розпорядження від 27 жовтня 2026 року передбачає також сертифікат, виданий у контексті одного визначеного NIP, тобто такий, що діє лише для конкретного клієнта. Це лише проєкт.
Коли потрібен офлайн-сертифікат KSeF?
Коли ви виставляєте рахунок-фактуру без підключення до KSeF, його треба позначити двома QR-кодами. Перший дає змогу перевірити рахунок-фактуру в KSeF, другий підтверджує особу того, хто його виставив, і потребує сертифіката KSeF для офлайн-режиму. Такий сертифікат не призначений для входу, а сертифікат для входу не підпише QR-код. Строки, до яких рахунок-фактуру треба надіслати в KSeF, згідно з документацією API:
| Режим | Коли | Строк надсилання в KSeF |
|---|---|---|
| offline24 | З будь-якої причини, на рішення платника податків | До наступного робочого дня після дати виставлення |
| offline (недоступність) | Оголошена недоступність KSeF | До наступного робочого дня після закінчення недоступності |
| аварійний (tryb awaryjny) | Оголошена аварія KSeF | До 7 робочих днів після закінчення аварії |
| повна аварія (awaria całkowita) | Аварія, оголошена в засобах масової інформації | Рахунок-фактура без QR-кодів і без обовʼязку надсилати його в KSeF |
Для системи це означає чотири речі: надсилання рахунку-фактури з позначкою офлайн-режиму, дату виставлення, яку беруть виключно з поля P_1, обидва QR-коди на роздруківці та в PDF, а також контроль строку надсилання. Інтернет-магазин або CRM без офлайн-сертифіката під час недоступності KSeF не виставить коректного рахунку-фактури для компанії.
Де тестувати інтеграцію з KSeF: TEST, DEMO чи робоче середовище?
| Середовище | Адреса API | Для чого призначене |
|---|---|---|
| TEST | api-test.ksef.mf.gov.pl | Перші тести інтеграції. Фіктивні номери NIP, самостійно згенеровані сертифікати, дані можуть бачити інші інтегратори. Технічні перерви з 16 до 18 години. |
| DEMO (передробоче) | api-demo.ksef.mf.gov.pl | Остання перевірка в конфігурації, близькій до робочого середовища. Без реальних рахунків-фактур і даних компаній. |
| Робоче середовище | api.ksef.mf.gov.pl | Рахунки-фактури з повними юридичними наслідками. |
У TEST ви перевіряєте вхід, надсилання рахунку-фактури, відхилення, коригування й офлайн-режим. У DEMO повторюєте те саме із сертифікатом, яким користуватиметеся в робочому середовищі. Реальних рахунків-фактур не надсилайте в жодне з цих середовищ.
Що, крім входу, має підтримувати інтеграція?
- Поновлення доступу: оновлення токена доступу і повторний вхід, коли закінчиться строк дії токена оновлення.
- Нагадування про строк дії: попередження перед закінченням строку дії сертифіката або токена, надіслане людині, яка може згенерувати новий.
- Безпечне зберігання: токен і приватний ключ у сховищі секретів або в зашифрованій конфігурації, ніколи в коді програми чи в електронній таблиці.
- Змінний спосіб входу: перехід із токена на сертифікат без перебудови інтеграції.
- Рахунки-фактури: надсилання FA(3), номер KSeF і UPO (Urzędowe Poświadczenie Odbioru, офіційне підтвердження отримання) разом із рахунком-фактурою, обробка відхилень, коригування з номером KSeF первинного рахунку-фактури, завантаження вхідних рахунків-фактур і ліміти запитів API.
Способи підключення магазину і CRM до KSeF із цінами (застосунок Мінфіну, програма для рахунків-фактур, плагін, API-шлюз, пряма інтеграція) ми порівняли в статті KSeF у CRM та інтернет-магазині: 5 способів інтеграції, а терміни на 2027 рік у чеклісті KSeF 2027. Пояснення понять ви знайдете в словнику ІТ-термінів.
Коли вистачить готової програми, а коли потрібна інтеграція?
Якщо ви виставляєте рахунки-фактури в програмі для рахунків-фактур або на платформі магазину з підтримкою KSeF, сертифікат або токен ви додаєте туди за інструкцією постачальника, і програміст вам не потрібен. Інтеграція з API має сенс, коли рахунок-фактура створюється у вашій CRM, B2B-кабінеті або системі замовлень, коли у вас кілька джерел рахунків-фактур або ви хочете, щоб номер KSeF повертався до замовлення і платежу.
UNSEEN робить такі інтеграції від 5 900 зл нетто (UN·Connect), а фінансовий модуль із KSeF від 29 000 зл нетто (UN·Finance). Надсилання рахунків-фактур у KSeF ми реалізували, зокрема, у CRM для компанії з відновлюваної енергетики: рахунок-фактура, виставлений у системі, потрапляє в KSeF разом з UPO, а вхідні рахунки-фактури повертаються в систему. Повний обсяг ми описуємо на сторінці рахунки-фактури з CRM і магазину в KSeF.
Найчастіші запитання про сертифікат і токен KSeF
Історія оновлень
- Перша версія. Способи автентифікації, строк дії токенів і сертифікатів, середовища та офлайн-режими перевірено 14.11.2026 у Dziennik Ustaw, в RCL, на сайтах Міністерства фінансів і в документації API KSeF 2.0.
Джерела
- Розпорядження міністра фінансів і економіки від 12 грудня 2025 року про користування KSeF, Dz.U. 2025 poz. 1815 (§ 6, § 13) (перевірено 14.11.2026)
- RCL: проєкт розпорядження про зміну розпорядження щодо користування KSeF (27.10.2026) (перевірено 14.11.2026)
- Міністерство фінансів: сертифікати KSeF (перевірено 14.11.2026)
- Міністерство фінансів: запитання й відповіді KSeF 2.0 (перевірено 14.11.2026)
- Документація API KSeF 2.0: автентифікація (перевірено 14.11.2026)
- Документація API KSeF 2.0: сертифікати KSeF (перевірено 14.11.2026)
- Документація API KSeF 2.0: токени KSeF (перевірено 14.11.2026)
- Документація API KSeF 2.0: офлайн-режими (перевірено 14.11.2026)
- Документація API KSeF 2.0: середовища (перевірено 14.11.2026)
- Infor.pl: зміни в KSeF з 2027 року, проєкт змін до розпорядження (9.11.2026) (вторинне джерело)
Стаття має інформаційний характер і не є податковою консультацією: у податкових питаннях остаточне слово за вашим бухгалтером або податковим консультантом.
Потрібна індивідуальна порада?
Запишіться на безкоштовну консультацію. Ми проаналізуємо ваш бізнес і запропонуємо конкретні рішення.
Записатися на безкоштовну розмову (30 хв)