Перейти до вмісту
Повернутися до статей
Технології9 хв читанняОновлено:

Сертифікат 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 KSeF 2.0 крок за кроком (документація Мінфіну, станом на 14.11.2026)
КрокЗапит до APIЩо треба знати
1. Виклик (challenge)POST /auth/challengeВиклик дійсний 10 хвилин.
2а. СертифікатPOST /auth/xades-signatureСистема підписує XML-документ із викликом і NIP (польським податковим номером) підписом XAdES: сертифікатом KSeF, кваліфікованим підписом або кваліфікованою печаткою.
2б. Токен KSeFPOST /auth/ksef-tokenСистема надсилає токен разом із часовою позначкою з виклику, зашифрований публічним ключем Міністерства фінансів.
3. СтатусGET /auth/{referenceNumber}Запит повторюють, доки не буде результату. Кваліфікований підпис його видавець може перевіряти довше, сертифікат KSeF перевіряється одразу.
4. Токени доступуPOST /auth/token/redeemПовертає токен доступу і токен оновлення. Повторний запит із тим самим токеном автентифікації завершується помилкою.
5. ОновленняPOST /auth/token/refreshНовий токен доступу без повторного входу, доки діє токен оновлення.
Джерело: документація API KSeF 2.0 Міністерства фінансів на GitHub (автентифікація).

Токен чи сертифікат KSeF: що обрати для інтеграції?

Згідно з FAQ Міністерства фінансів, токен і сертифікат діють паралельно, а зовнішня система може користуватися одним або другим. Вони відрізняються способом отримання, строком дії і тим, що ще дозволяють зробити.

Токен KSeF і сертифікат KSeF в інтеграції (станом на 14.11.2026)
ОзнакаТокен 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.
Підстава: § 6 і § 13 розпорядження від 12.12.2025 (Dz.U. 2025 poz. 1815), сторінка Мінфіну про сертифікати KSeF, FAQ KSeF 2.0 і документація API.

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

Як отримати сертифікат KSeF крок за кроком?

З лютого 2026 року заявку на сертифікат подають в Aplikacja Podatnika KSeF 2.0 або через API KSeF 2.0. Модуль сертифікатів і прав доступу (Moduł Certyfikatów i Uprawnień, MCU), у якому сертифікати видавали з листопада 2025 року, працював до кінця січня 2026 року. У застосунку це виглядає так:

  1. Увійдіть в Aplikacja Podatnika KSeF 2.0 через Profil Zaufany (на login.gov.pl), кваліфікованим підписом або кваліфікованою печаткою компанії. Перевірте, що працюєте в контексті потрібного NIP.
  2. Відкрийте вкладку «Certyfikaty» (сертифікати) і виберіть «Wnioskuj o certyfikat» (подати заявку на сертифікат). Дані для заявки застосунок бере з даних входу.
  3. Виберіть призначення: автентифікація або офлайн-режим. Один сертифікат має одне призначення, тож для обох потрібні дві заявки.
  4. Захистіть приватний ключ. Пара ключів створюється під час заявки, а до Міністерства потрапляє лише публічний ключ. Без приватного ключа сертифікат марний, а той, хто ним володіє, може діяти від вашого імені в межах ваших прав.
  5. Завантажте сертифікат і додайте його в систему разом із приватним ключем, безпечним каналом. Не надсилайте ключ електронною поштою.
  6. Запишіть дату закінчення строку дії. Наступний сертифікат можна замовити ще до того, як мине строк дії попереднього. Налаштуйте нагадування щонайменше за місяць.

Система може також подати заявку сама, через 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 2.0 і строки надсилання рахунку-фактури
РежимКолиСтрок надсилання в KSeF
offline24З будь-якої причини, на рішення платника податківДо наступного робочого дня після дати виставлення
offline (недоступність)Оголошена недоступність KSeFДо наступного робочого дня після закінчення недоступності
аварійний (tryb awaryjny)Оголошена аварія KSeFДо 7 робочих днів після закінчення аварії
повна аварія (awaria całkowita)Аварія, оголошена в засобах масової інформаціїРахунок-фактура без QR-кодів і без обовʼязку надсилати його в KSeF
Джерело: офлайн-режими у документації API KSeF 2.0.

Для системи це означає чотири речі: надсилання рахунку-фактури з позначкою офлайн-режиму, дату виставлення, яку беруть виключно з поля P_1, обидва QR-коди на роздруківці та в PDF, а також контроль строку надсилання. Інтернет-магазин або CRM без офлайн-сертифіката під час недоступності KSeF не виставить коректного рахунку-фактури для компанії.

Де тестувати інтеграцію з KSeF: TEST, DEMO чи робоче середовище?

Середовища API KSeF 2.0 (документація Мінфіну від 16.03.2026)
СередовищеАдреса APIДля чого призначене
TESTapi-test.ksef.mf.gov.plПерші тести інтеграції. Фіктивні номери NIP, самостійно згенеровані сертифікати, дані можуть бачити інші інтегратори. Технічні перерви з 16 до 18 години.
DEMO (передробоче)api-demo.ksef.mf.gov.plОстання перевірка в конфігурації, близькій до робочого середовища. Без реальних рахунків-фактур і даних компаній.
Робоче середовищеapi.ksef.mf.gov.plРахунки-фактури з повними юридичними наслідками.
Специфікація OpenAPI доступна за адресою середовища з додаванням /docs/v2. Міністерство також надає офіційні клієнтські бібліотеки на C# і Java.

У 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

Чи перестане працювати токен KSeF 31 грудня 2026 року?

Згідно з чинним розпорядженням, входити токеном можна до 31 грудня 2026 року. Міністерство фінансів оголосило, що цей спосіб залишиться, а проєкт змін до розпорядження від 27 жовтня 2026 року передбачає, що наявні токени діятимуть до 30 листопада 2027 року, а нові щонайбільше 365 днів. Доки зміну не опубліковано, обовʼязковою є дата 31 грудня 2026 року.

Де згенерувати сертифікат KSeF?

В Aplikacja Podatnika KSeF 2.0, у вкладці «Certyfikaty» (сертифікати), або через API KSeF 2.0. Раніше, з листопада 2025 року до кінця січня 2026 року, сертифікати видавав Moduł Certyfikatów i Uprawnień (MCU), модуль сертифікатів і прав доступу.

Скільки діє сертифікат KSeF?

Щонайбільше 2 роки від створення або від початкової дати, зазначеної в заявці. Його можна поновити до закінчення строку дії.

Чи можна сертифікатом KSeF увійти в Aplikacja Podatnika?

Ні. Сертифікат для автентифікації призначений для систем, які підключаються до KSeF через API, наприклад програм для рахунків-фактур, інтернет-магазинів і CRM. В Aplikacja Podatnika ви входите через Profil Zaufany, кваліфікованим підписом або кваліфікованою печаткою.

Чи потрібен окремий сертифікат для рахунків-фактур в офлайн-режимі?

Так. Другий QR-код на рахунку-фактурі, виставленому в офлайн-режимі, потребує сертифіката KSeF для офлайн-режиму. Сертифікат для входу його не замінить, а один сертифікат не може мати обох призначень.

Чи можна токеном KSeF замовити сертифікат?

Ні. Увійшовши токеном, ви не створите сертифікат KSeF. Для заявки потрібен вхід через Profil Zaufany, кваліфікованим підписом або кваліфікованою печаткою.

Історія оновлень

  • Перша версія. Способи автентифікації, строк дії токенів і сертифікатів, середовища та офлайн-режими перевірено 14.11.2026 у Dziennik Ustaw, в RCL, на сайтах Міністерства фінансів і в документації API KSeF 2.0.

Джерела

  1. Розпорядження міністра фінансів і економіки від 12 грудня 2025 року про користування KSeF, Dz.U. 2025 poz. 1815 (§ 6, § 13) (перевірено 14.11.2026)
  2. RCL: проєкт розпорядження про зміну розпорядження щодо користування KSeF (27.10.2026) (перевірено 14.11.2026)
  3. Міністерство фінансів: сертифікати KSeF (перевірено 14.11.2026)
  4. Міністерство фінансів: запитання й відповіді KSeF 2.0 (перевірено 14.11.2026)
  5. Документація API KSeF 2.0: автентифікація (перевірено 14.11.2026)
  6. Документація API KSeF 2.0: сертифікати KSeF (перевірено 14.11.2026)
  7. Документація API KSeF 2.0: токени KSeF (перевірено 14.11.2026)
  8. Документація API KSeF 2.0: офлайн-режими (перевірено 14.11.2026)
  9. Документація API KSeF 2.0: середовища (перевірено 14.11.2026)
  10. Infor.pl: зміни в KSeF з 2027 року, проєкт змін до розпорядження (9.11.2026) (вторинне джерело)

Стаття має інформаційний характер і не є податковою консультацією: у податкових питаннях остаточне слово за вашим бухгалтером або податковим консультантом.

Потрібна індивідуальна порада?

Запишіться на безкоштовну консультацію. Ми проаналізуємо ваш бізнес і запропонуємо конкретні рішення.

Записатися на безкоштовну розмову (30 хв)

Аналітичні й маркетингові cookie лише за вашою згодою. Деталі в політиці конфіденційності.