Przejdź do treści
Wróć do artykułów
Technologia9 min czytaniaAktualizacja:

Certyfikat KSeF czy token: jak podłączyć CRM i sklep do API KSeF 2.0

Jak CRM, sklep albo panel B2B loguje się do API KSeF 2.0: token czy certyfikat KSeF, ważność tokenów po 2026 r. według projektu z 27.10.2026, jak uzyskać certyfikat, certyfikat offline oraz środowiska TEST i DEMO.

W skrócie

  • CRM, sklep albo panel B2B, który sam wysyła faktury do KSeF, loguje się przez API KSeF 2.0 tokenem KSeF albo certyfikatem KSeF do uwierzytelniania. Obie metody działają równolegle.
  • Według obowiązującego rozporządzenia tokeny działają do 31 grudnia 2026 r. Ministerstwo Finansów zapowiedziało, że metoda zostaje, a projekt zmiany rozporządzenia z 27 października 2026 r. przewiduje ważność obecnych tokenów do 30 listopada 2027 r. i nowych najwyżej 365 dni. Na 14 listopada 2026 r. to projekt.
  • Certyfikat KSeF jest ważny najwyżej 2 lata. Wnioskujesz o niego w Aplikacji Podatnika KSeF 2.0 albo przez API, po zalogowaniu Profilem Zaufanym, podpisem lub pieczęcią kwalifikowaną. Tokenem certyfikatu nie zamówisz.
  • Do faktur w trybie offline potrzebny jest osobny certyfikat offline: bez niego system nie wygeneruje drugiego kodu QR.
  • Integrację sprawdzasz najpierw na środowisku TEST, potem na DEMO, a dopiero na końcu na produkcji.

Jak CRM albo sklep loguje się do API KSeF 2.0?

Program, który wysyła faktury do KSeF bez udziału człowieka, nie loguje się hasłem. Przy każdym połączeniu przechodzi krótką procedurę: pobiera z KSeF jednorazowe wyzwanie, potwierdza je tokenem albo podpisem certyfikatem, a w zamian dostaje token dostępowy, którym wysyła i pobiera faktury. Token dostępowy jest ważny kilkanaście minut, a token odświeżający najwyżej 7 dni. Po tym czasie system musi uwierzytelnić się od nowa.

Uwierzytelnianie w API KSeF 2.0 krok po kroku (dokumentacja MF, stan na 14.11.2026)
KrokWywołanie APICo trzeba wiedzieć
1. WyzwaniePOST /auth/challengeWyzwanie jest ważne 10 minut.
2a. CertyfikatPOST /auth/xades-signatureSystem podpisuje dokument XML z wyzwaniem i NIP podpisem XAdES: certyfikatem KSeF, podpisem albo pieczęcią kwalifikowaną.
2b. Token KSeFPOST /auth/ksef-tokenSystem wysyła token połączony ze znacznikiem czasu z wyzwania, zaszyfrowany kluczem publicznym Ministerstwa Finansów.
3. StatusGET /auth/{referenceNumber}Sprawdzanie do skutku. Podpis kwalifikowany może być weryfikowany u wystawcy dłużej, certyfikat KSeF od razu.
4. Tokeny dostępuPOST /auth/token/redeemZwraca token dostępowy i token odświeżający. Drugie wywołanie z tym samym tokenem uwierzytelniającym kończy się błędem.
5. OdświeżeniePOST /auth/token/refreshNowy token dostępowy bez ponownego logowania, dopóki ważny jest token odświeżający.
Źródło: dokumentacja API KSeF 2.0 Ministerstwa Finansów na GitHubie (uwierzytelnianie).

Token czy certyfikat KSeF: co wybrać do integracji?

Według FAQ Ministerstwa Finansów token i certyfikat działają równolegle, a zewnętrzny system może używać jednego albo drugiego. Różnią się sposobem uzyskania, ważnością i tym, co jeszcze pozwalają zrobić.

Token KSeF i certyfikat KSeF w integracji (stan na 14.11.2026)
CechaToken KSeFCertyfikat KSeF (uwierzytelnianie)
Czym jestCiąg znaków wygenerowany w KSeF z ustalonym zakresem uprawnień, np. wysyłka i odczyt faktur.Elektroniczne potwierdzenie tożsamości osoby albo firmy z parą kluczy. Klucz prywatny zostaje u Ciebie.
Jak go uzyskaćGenerujesz w Aplikacji Podatnika KSeF 2.0 albo przez API (POST /tokens) po zalogowaniu.Wniosek w Aplikacji Podatnika KSeF 2.0 albo przez API, po zalogowaniu Profilem Zaufanym, podpisem lub pieczęcią kwalifikowaną.
WażnośćObowiązujące przepisy: do 31.12.2026. Projekt z 27.10.2026: obecne do 30.11.2027, nowe najwyżej 365 dni.Najwyżej 2 lata, z możliwością odnowienia w czasie ważności.
UprawnieniaZapisane w tokenie. Zmiana zakresu oznacza nowy token.Certyfikat ich nie zawiera: KSeF sprawdza uprawnienia osoby albo firmy, na którą go wystawiono.
Wymagania po stronie systemuSzyfrowanie tokenu kluczem publicznym MF.Podpis XAdES dokumentu uwierzytelniającego.
OgraniczeniaPo zalogowaniu tokenem nie wytworzysz certyfikatu KSeF.Nie zalogujesz się nim do Aplikacji Podatnika KSeF: służy systemom łączącym się przez API.
Podstawa: § 6 i § 13 rozporządzenia z 12.12.2025 (Dz.U. 2025 poz. 1815), strona MF o certyfikatach KSeF, FAQ KSeF 2.0 i dokumentacja API.

Token jest prostszy na start, bo system nie musi podpisywać dokumentów XAdES. Certyfikat daje dłuższą i przewidywalną ważność, a w integracji, którą budujesz dziś, ma jeszcze jedną zaletę: nie zależy od tego, jak skończy się zmiana przepisów o tokenach. Najbezpieczniej zbudować integrację tak, żeby sposób logowania dało się zmienić w ustawieniach, bez przeróbki programu.

Jak uzyskać certyfikat KSeF krok po kroku?

Od lutego 2026 r. o certyfikat wnioskujesz w Aplikacji Podatnika KSeF 2.0 albo przez API KSeF 2.0. Moduł Certyfikatów i Uprawnień (MCU), w którym certyfikaty wydawano od listopada 2025 r., działał do końca stycznia 2026 r. W aplikacji wygląda to tak:

  1. Zaloguj się do Aplikacji Podatnika KSeF 2.0 Profilem Zaufanym (przez login.gov.pl), podpisem kwalifikowanym albo pieczęcią kwalifikowaną firmy. Sprawdź, że pracujesz w kontekście właściwego NIP.
  2. Otwórz zakładkę „Certyfikaty” i wybierz „Wnioskuj o certyfikat”. Dane do wniosku aplikacja pobiera z logowania.
  3. Wybierz zastosowanie: uwierzytelnianie albo tryb offline. Jeden certyfikat ma jedno zastosowanie, więc do obu potrzebujesz dwóch wniosków.
  4. Zabezpiecz klucz prywatny. Para kluczy powstaje przy wniosku, a do Ministerstwa trafia tylko klucz publiczny. Bez klucza prywatnego certyfikat jest bezużyteczny, a kto go ma, może działać w Twoim imieniu w granicach Twoich uprawnień.
  5. Pobierz certyfikat i wgraj go do systemu razem z kluczem prywatnym, bezpiecznym kanałem. Nie wysyłaj klucza mailem.
  6. Zapisz datę ważności. Kolejny certyfikat możesz zamówić przed wygaśnięciem poprzedniego. Ustaw przypomnienie co najmniej miesiąc wcześniej.

System może też złożyć wniosek sam, przez API: sprawdza limity (GET /certificates/limits), pobiera dane do wniosku (GET /certificates/enrollments/data), wysyła żądanie CSR w formacie PKCS#10 (POST /certificates/enrollments), sprawdza status i pobiera certyfikat (POST /certificates/retrieve). Dokumentacja dopuszcza klucze RSA 2048 i EC P-256 i zaleca EC. Certyfikat może unieważnić tylko jego właściciel, np. po wycieku klucza (POST /certificates/{numer}/revoke), a unieważnionego nie da się przywrócić.

Czyj certyfikat powinien mieć system firmy?

Certyfikat potwierdza tożsamość, ale nie daje uprawnień. KSeF przy każdym połączeniu sprawdza, co wolno osobie albo firmie, na którą certyfikat wystawiono. Według FAQ Ministerstwa Finansów certyfikat może uzyskać osoba fizyczna identyfikowana numerem NIP albo PESEL oraz firma, która loguje się pieczęcią kwalifikowaną. Certyfikatem firmy można dzielić się z pracownikami, a certyfikat jednoosobowej działalności jest osobisty.

  • Certyfikat firmy (pieczęć kwalifikowana): integracja nie zależy od jednej osoby. To rozsądny wybór dla CRM albo sklepu, który wystawia faktury całej firmy.
  • Certyfikat pracownika: działa, dopóki ten pracownik ma uprawnienia w KSeF dla firmy. Gdy odejdzie i straci uprawnienia, system przestanie wysyłać faktury.
  • Biuro rachunkowe albo zewnętrzny dostawca: loguje się własnym certyfikatem i działa w granicach uprawnień nadanych przez firmę. Projekt zmiany rozporządzenia z 27 października 2026 r. przewiduje też certyfikat wystawiony w kontekście jednego, wskazanego NIP, czyli działający tylko dla konkretnego klienta. To projekt.

Kiedy potrzebny jest certyfikat KSeF offline?

Gdy fakturę wystawiasz bez połączenia z KSeF, musisz ją oznaczyć dwoma kodami QR. Pierwszy pozwala sprawdzić fakturę w KSeF, drugi potwierdza tożsamość wystawcy i wymaga certyfikatu KSeF do trybu offline. Taki certyfikat nie służy do logowania, a certyfikat do logowania nie podpisze kodu QR. Terminy dosłania faktury według dokumentacji API:

Tryby offline w KSeF 2.0 i terminy dosłania faktury
TrybKiedyTermin wysłania do KSeF
offline24Z dowolnego powodu, decyzja podatnikaDo następnego dnia roboczego po dacie wystawienia
offline (niedostępność)Ogłoszona niedostępność KSeFDo następnego dnia roboczego po zakończeniu niedostępności
awaryjnyOgłoszona awaria KSeFDo 7 dni roboczych od zakończenia awarii
awaria całkowitaAwaria ogłoszona w środkach masowego przekazuFaktura bez kodów QR i bez obowiązku dosyłania do KSeF
Źródło: tryby offline w dokumentacji API KSeF 2.0.

Dla systemu oznacza to cztery rzeczy: wysyłkę faktury z oznaczeniem trybu offline, datę wystawienia braną wyłącznie z pola P_1, oba kody QR na wydruku i w PDF oraz pilnowanie terminu dosłania. Sklep albo CRM bez certyfikatu offline w czasie niedostępności KSeF nie wystawi poprawnej faktury dla firmy.

Gdzie testować integrację z KSeF: TEST, DEMO czy produkcja?

Środowiska API KSeF 2.0 (dokumentacja MF z 16.03.2026)
ŚrodowiskoAdres APIDo czego służy
TESTapi-test.ksef.mf.gov.plPierwsze testy integracji. Fikcyjne numery NIP, certyfikaty samodzielnie wygenerowane, dane mogą być widoczne dla innych integratorów. Przerwy serwisowe w godzinach 16-18.
DEMO (przedprodukcyjne)api-demo.ksef.mf.gov.plOstatnie sprawdzenie w konfiguracji zbliżonej do produkcji. Bez prawdziwych faktur i danych firm.
Produkcjaapi.ksef.mf.gov.plFaktury z pełnym skutkiem prawnym.
Specyfikacja OpenAPI jest pod adresem środowiska z dopiskiem /docs/v2. Ministerstwo udostępnia też oficjalne biblioteki klienckie w C# i Javie.

Na TEST sprawdzasz logowanie, wysyłkę faktury, odrzucenie, korektę i tryb offline. Na DEMO powtarzasz to samo na certyfikacie, którego użyjesz na produkcji. Prawdziwych faktur nie wysyłaj na żadne z tych środowisk.

Co musi obsłużyć integracja oprócz logowania?

  • Odnawianie dostępu: odświeżanie tokenu dostępowego i ponowne logowanie, gdy wygaśnie token odświeżający.
  • Przypomnienia o ważności: ostrzeżenie przed końcem ważności certyfikatu albo tokenu, wysłane do osoby, która może wygenerować nowy.
  • Bezpieczne przechowywanie: token i klucz prywatny w sejfie na sekrety albo w zaszyfrowanej konfiguracji, nigdy w kodzie programu ani w arkuszu.
  • Wymienny sposób logowania: przejście z tokenu na certyfikat bez przebudowy integracji.
  • Faktury: wysyłka FA(3), numer KSeF i UPO przy fakturze, obsługa odrzuceń, korekty z numerem KSeF faktury pierwotnej, pobieranie faktur kosztowych i limity zapytań API.

Sposoby podłączenia sklepu i CRM do KSeF z cenami (aplikacja MF, program do faktur, wtyczka, bramka API, integracja bezpośrednia) zestawiliśmy w artykule KSeF w CRM i sklepie: 5 sposobów integracji, a terminy na 2027 r. w checkliście KSeF 2027. Pojęcia znajdziesz w słowniku pojęć IT.

Kiedy wystarczy gotowy program, a kiedy potrzebna jest integracja?

Jeśli faktury wystawiasz w programie do faktur albo platformie sklepu, które mają obsługę KSeF, certyfikat lub token wgrywasz tam według instrukcji dostawcy i nie potrzebujesz programisty. Integracja z API ma sens, gdy faktura powstaje w Twoim CRM, panelu B2B albo systemie zamówień, gdy masz kilka źródeł faktur albo chcesz, żeby numer KSeF wracał do zamówienia i płatności.

UNSEEN robi takie integracje od 5 900 zł netto (UN·Connect), a moduł finansowy z KSeF od 29 000 zł netto (UN·Finance). Wysyłkę faktur do KSeF zbudowaliśmy m.in. w CRM dla firmy OZE: faktura wystawiona w systemie trafia do KSeF razem z UPO, a faktury kosztowe wracają do systemu. Pełny zakres opisujemy na stronie faktury z CRM i sklepu do KSeF.

Najczęstsze pytania o certyfikat i token KSeF

Czy token KSeF przestanie działać 31 grudnia 2026 r.?

Według obowiązującego rozporządzenia tokenem można logować się do 31 grudnia 2026 r. Ministerstwo Finansów zapowiedziało, że metoda zostanie, a projekt zmiany rozporządzenia z 27 października 2026 r. przewiduje ważność obecnych tokenów do 30 listopada 2027 r. i nowych najwyżej 365 dni. Dopóki zmiana nie zostanie ogłoszona, wiąże 31 grudnia 2026 r.

Gdzie wygenerować certyfikat KSeF?

W Aplikacji Podatnika KSeF 2.0, w zakładce „Certyfikaty”, albo przez API KSeF 2.0. Wcześniej, od listopada 2025 r. do końca stycznia 2026 r., certyfikaty wydawał Moduł Certyfikatów i Uprawnień (MCU).

Jak długo jest ważny certyfikat KSeF?

Najwyżej 2 lata od wytworzenia albo od daty początkowej wskazanej we wniosku. Można go odnowić przed upływem ważności.

Czy certyfikatem KSeF zaloguję się do Aplikacji Podatnika?

Nie. Certyfikat do uwierzytelniania służy systemom, które łączą się z KSeF przez API, np. programom do faktur, sklepom i CRM. Do Aplikacji Podatnika logujesz się Profilem Zaufanym, podpisem albo pieczęcią kwalifikowaną.

Czy do faktur offline potrzebny jest osobny certyfikat?

Tak. Drugi kod QR na fakturze offline wymaga certyfikatu KSeF do trybu offline. Certyfikat do logowania go nie zastąpi, a jeden certyfikat nie może mieć obu zastosowań.

Czy tokenem KSeF można zamówić certyfikat?

Nie. Po zalogowaniu tokenem nie wytworzysz certyfikatu KSeF. Do wniosku potrzebne jest logowanie Profilem Zaufanym, podpisem albo pieczęcią kwalifikowaną.

Historia aktualizacji

  • Pierwsza wersja. Sposoby uwierzytelniania, ważność tokenów i certyfikatów, środowiska i tryby offline sprawdzone 14.11.2026 w Dzienniku Ustaw, w RCL, na stronach Ministerstwa Finansów i w dokumentacji API KSeF 2.0.

Źródła

  1. Rozporządzenie MFiG z 12 grudnia 2025 r. w sprawie korzystania z KSeF, Dz.U. 2025 poz. 1815 (§ 6, § 13) (sprawdzone 14.11.2026)
  2. RCL: projekt rozporządzenia zmieniającego rozporządzenie w sprawie korzystania z KSeF (27.10.2026) (sprawdzone 14.11.2026)
  3. Ministerstwo Finansów: certyfikaty KSeF (sprawdzone 14.11.2026)
  4. Ministerstwo Finansów: pytania i odpowiedzi KSeF 2.0 (sprawdzone 14.11.2026)
  5. Dokumentacja API KSeF 2.0: uwierzytelnianie (sprawdzone 14.11.2026)
  6. Dokumentacja API KSeF 2.0: certyfikaty KSeF (sprawdzone 14.11.2026)
  7. Dokumentacja API KSeF 2.0: tokeny KSeF (sprawdzone 14.11.2026)
  8. Dokumentacja API KSeF 2.0: tryby offline (sprawdzone 14.11.2026)
  9. Dokumentacja API KSeF 2.0: środowiska (sprawdzone 14.11.2026)
  10. Infor.pl: zmiany w KSeF od 2027 r., projekt nowelizacji rozporządzenia (9.11.2026) (źródło wtórne)

Artykuł ma charakter informacyjny i nie jest poradą podatkową: w sprawach podatkowych decyduje Twój księgowy lub doradca podatkowy.

Potrzebujesz indywidualnej porady?

Umów się na darmową konsultację. Przeanalizujemy Twój biznes i zaproponujemy konkretne rozwiązania.

Umów bezpłatną rozmowę (30 min)

Cookies analityczne i marketingowe tylko za Twoją zgodą. Szczegóły w polityce prywatności.