KSeF: jak podłączyć system sprzedaży przez token i API

Od 2026 roku Krajowy System e-Faktur przestaje być opcją. Ten poradnik pokazuje krok po kroku, jak technicznie podłączyć system sprzedaży do KSeF: wybrać metodę uwierzytelnienia (token albo certyfikat), połączyć się z API 2.0, wystawić fakturę w strukturze FA(3) i wszystko przetestować w środowisku testowym, zanim ruszy produkcja.

Od czego zależy termin i co właściwie trzeba podłączyć

Żeby podłączyć system sprzedaży do KSeF, potrzebujesz trzech rzeczy naraz: metody uwierzytelnienia (token autoryzacyjny albo certyfikat KSeF), integracji z API KSeF 2.0 oraz generowania faktur w strukturze FA(3) w formacie XML. To jest cała odpowiedź na pytanie „jak to podłączyć” — reszta artykułu rozkłada każdy z tych elementów na czynniki pierwsze.

Najpierw jednak termin, bo od niego zależy, kiedy musisz mieć to gotowe. Od 1 lutego 2026 roku obowiązuje docelowa wersja systemu: jedyną akceptowaną strukturą faktury jest FA(3), a jedynym działającym interfejsem — API KSeF 2.0. Starsze FA(2) i API 1.0 są wygaszane. Co ważne dla każdego sprzedawcy: obowiązek odbierania faktur w KSeF dotyczy wszystkich podatników już od lutego 2026 — nawet jeśli sam musisz wystawiać dopiero od kwietnia.

Progi i daty podajemy orientacyjnie — zanim zaplanujesz wdrożenie, zweryfikuj je w aktualnej ustawie i na ksef.podatki.gov.pl. Jeśli dopiero orientujesz się w temacie od strony biznesowej, zacznij od naszego przeglądu KSeF 2026 dla sprzedawców e-commerce, a tutaj skup się na warstwie technicznej.

Uwierzytelnienie: token, certyfikat KSeF czy pieczęć

Zanim system cokolwiek wyśle, musi udowodnić KSeF, że działa w imieniu Twojej firmy. Działają tu trzy powiązane pojęcia: uwierzytelnienie (kim jesteś), autoryzacja (jakie masz uprawnienia) i klucz do automatyzacji (czym podpisujesz kolejne żądania API). Kolejność jest sztywna: właściciel firmy najpierw loguje się „mocną” metodą, nadaje uprawnienia, a dopiero potem generuje token lub certyfikat do integracji.

Tą „mocną” metodą pierwszego logowania jest Profil Zaufany, kwalifikowany podpis elektroniczny (osoba fizyczna, po PESEL/NIP) albo kwalifikowana pieczęć elektroniczna (organizacja, po NIP). Cały ten proces obsługuje Moduł Certyfikatów i Uprawnień (MCU), uruchomiony 1 listopada 2025 roku.

Uprawnienia nadaje się osobno dla różnych czynności — zwykle rozdziela się prawo do wystawiania faktur, do ich przeglądania i odbioru oraz do zarządzania uprawnieniami (rola administracyjna). Integracja systemu sprzedaży potrzebuje uprawnienia do wystawiania i odbioru, przypisanego do podmiotu lub osoby, w której imieniu wygenerujesz token albo certyfikat. Ustal z góry, kto w firmie jest właścicielem tej konfiguracji — to on odblokuje i zablokuje dostęp, gdy zmienisz dostawcę oprogramowania.

Token autoryzacyjny KSeF

To najwygodniejsza metoda do integracji „system do systemu”. Generujesz token jednorazowo (po uwierzytelnieniu mocną metodą), a potem służy on do podpisywania kolejnych żądań do API — bez każdorazowego sięgania po podpis czy certyfikat. Dwie rzeczy, o których trzeba pamiętać: tokeny z KSeF 1.0 nie działają w KSeF 2.0 (trzeba wygenerować nowy), a same tokeny 2.0 tracą ważność 31 grudnia 2026 roku. Od 1 stycznia 2027 zastępują je certyfikaty KSeF. Token traktuj więc jak rozwiązanie przejściowe — i jak sekret: trzymaj poza repozytorium kodu, rotuj i ograniczaj dostęp.

Certyfikat KSeF (typ 1 i typ 2)

Certyfikaty KSeF są dostępne z MCU od 1 listopada 2025 roku, ważne maksymalnie 2 lata i odnawialne. To nie jest certyfikat kwalifikowany w rozumieniu eIDAS, ale jest honorowany wewnątrz KSeF. Występuje w dwóch typach: typ 1 pełni funkcję uwierzytelniającą (jak podpis/pieczęć w kontakcie z API), a typ 2 służy do podpisywania cyfrowego kodów QR na fakturach wystawianych w trybie offline. To rozwiązanie docelowe — jeśli budujesz integrację na lata, warto od razu oprzeć ją o certyfikat typ 1, a nie o wygasający token.

Pieczęć, podpis kwalifikowany i Profil Zaufany

Te metody służą głównie do pierwszego logowania i nadawania uprawnień. Kwalifikowana pieczęć elektroniczna uwierzytelnia całą organizację (po NIP), a nie konkretną osobę — wygodne dla firmy, w której integrację utrzymuje kilka osób. Profil Zaufany to najprostsza droga dla jednoosobowej działalności.

Struktura FA(3): co się zmienia względem FA(2)

Od 1 lutego 2026 jedyną obowiązującą strukturą faktury jest FA(3). Jeśli Twój system generuje dziś XML w FA(2), musisz zaktualizować mapowanie. Najważniejsze różnice:

• Załączniki binarne — do faktury można dołączyć np. protokół odbioru czy specyfikację (w FA(2) było to niemożliwe).
• Nowa rola „pracownik” w węźle Podmiot3.
• Uściślone pola terminów płatności — więcej precyzji przy rozłożonych i wielu terminach.
• Rozszerzone limity znaków w nazwach towarów i usług (pole P_7).
• Obsługa JST i grup VAT — nowe scenariusze podmiotowe.

Kluczowa zasada: wygenerowany XML musi dokładnie 1:1 odpowiadać schematowi XSD opublikowanemu przez Ministerstwo Finansów. Najmniejsza niezgodność oznacza odrzucenie faktury, a odrzucona faktura nie dostaje numeru KSeF — czyli w świetle systemu nie istnieje. Dlatego nie „sklejaj” XML ręcznie: użyj biblioteki lub warstwy mapowania danych zamówienia na strukturę i waliduj lokalnie względem XSD przed wysyłką. Aktualny XSD FA(3), specyfikację OpenAPI (Swagger), podręcznik integratora oraz gotowe SDK (Java, .NET) i przykładowe kody pobierzesz z ksef.podatki.gov.pl. Osobny, częsty w e-commerce przypadek — faktury do zamówień z marketplace i paragonów — opisujemy w tekście KSeF a sprzedaż na Allegro.

W praktyce najwięcej odrzuceń bierze się nie z egzotycznych pól, lecz z podstaw: błędny lub brakujący NIP nabywcy, stawka VAT niespójna z pozycją, zły format daty albo kwoty, które nie sumują się co do grosza. Zadbaj też o faktury korygujące i zaliczkowe — w FA(3) mają swoje reguły, a w e-commerce pojawiają się przy zwrotach i przedpłatach. Zmapuj te przypadki od razu, zamiast dokładać je później „na produkcji”.

Środowisko testowe KSeF 2.0 — testuj, zanim ruszy produkcja

Ministerstwo Finansów udostępnia trzy środowiska. Zdrowy scenariusz to: najpierw testowe (deweloperka), potem przedprodukcyjne (akceptacja), na końcu produkcja. Nie zaczynaj od produkcji — tam faktury mają realny skutek prawny.

W środowisku testowym możesz używać certyfikatów self-signed i wygenerować token bez „prawdziwych” dokumentów, a działania testowe nie wpływają na uprawnienia ani certyfikaty produkcyjne. Jeśli nie masz jeszcze własnej integracji, do ręcznej weryfikacji nada się bezpłatna Aplikacja Podatnika KSeF 2.0 od MF, która również ma wersję testową (udostępniona jesienią 2025). Adresy podajemy orientacyjnie — zawsze potwierdź je na ksef.podatki.gov.pl, bo szczegóły środowisk bywają aktualizowane.

Krok po kroku: podłączenie systemu przez API

Poniższa sekwencja zakłada, że masz już system sprzedaży, który zna dane zamówień i nabywców. Zadaniem integracji jest przetłumaczyć te dane na język KSeF i odebrać potwierdzenie. Przejdź kroki po kolei — pominięcie uprawnień albo walidacji lokalnej to najczęstsza przyczyna „utknięcia” na pierwszej wysyłce.

1. Uporządkuj uprawnienia w MCU. Właściciel loguje się mocną metodą (pieczęć / podpis / Profil Zaufany) i nadaje uprawnienia — np. do wystawiania i odbioru faktur — właściwym osobom i podmiotom. Bez tego token ani certyfikat nie zadziałają.
2. Wygeneruj klucz do automatyzacji. W MCU utwórz token autoryzacyjny albo certyfikat KSeF typ 1. Zapisz sekret w bezpiecznym miejscu (menedżer sekretów, zmienne środowiskowe), nigdy w kodzie.
3. Pobierz materiały integracyjne. Specyfikacja OpenAPI, schematy XSD dla FA(3), SDK i podręcznik integratora są na ksef.podatki.gov.pl.
4. Zestaw środowisko testowe. Ustaw bazowy URL na adres testowy i zaimplementuj przepływ challenge → podpis → token: system pobiera wyzwanie, podpisuje je, a w zamian dostaje dostęp do sesji.
5. Otwórz sesję we właściwym trybie. Sesja interaktywna to pojedyncze faktury z natychmiastową walidacją (dokument do ok. 1 MB). Sesja wsadowa (batch) to paczka wielu faktur wysyłana jako archiwum ZIP dzielone na części — dobra do dużych wolumenów typowych dla e-commerce.
6. Wyślij fakturę FA(3). Zmapuj dane zamówienia na XML FA(3), zwaliduj lokalnie względem XSD, a następnie wyślij w otwartej sesji.
7. Odbierz numer KSeF i UPO. Po pozytywnej walidacji system nadaje numer KSeF (35 znaków), zwracany w UPO — urzędowym poświadczeniu odbioru. Odpytuj o status (orientacyjnie: 150 = w toku, 200 = przyjęto) i zapisuj numer KSeF oraz UPO przy zamówieniu.
8. Obsłuż błędy i ponowienia. Faktura odrzucona nie ma numeru KSeF — popraw XML i wyślij ponownie. Zbuduj kolejkę ponowień oraz log odpowiedzi, żeby nic nie przepadło przy chwilowych błędach.
9. Przejdź na demo, potem na produkcję. Powtórz testy na środowisku przedprodukcyjnym, a po odpowiednim terminie (1 lutego lub 1 kwietnia 2026) przełącz konfigurację na produkcyjną.

Jeśli chcesz, żeby faktura powstawała sama po zmianie statusu zamówienia (np. „opłacone” albo „wysłane”), połączenie z KSeF traktuj jako część szerszej automatyzacji zamówień — inaczej dołożysz zespołowi ręcznej pracy zamiast ją odjąć.

Tryby pracy: online, offline24 i awaryjny

KSeF przewiduje kilka trybów i dla sklepu z dużym ruchem to nie jest ciekawostka, tylko element planu ciągłości:

• Online (podstawowy) — faktura trafia do KSeF od razu, numer KSeF dostajesz natychmiast.
• Offline24 — wystawiasz fakturę bez połączenia (prefiks OFF, dwa kody QR, drugi podpisany certyfikatem sprzedawcy) i przesyłasz ją do KSeF najpóźniej następnego dnia roboczego.
• Awaryjny — uruchamiany oficjalnym komunikatem MF podczas awarii systemu; faktury dosyłasz w oknie do 7 dni roboczych od zakończenia awarii (terminy orientacyjne — zweryfikuj przy wdrożeniu).

Wniosek praktyczny: zaplanuj obsługę trybu offline w kodzie, żeby awaria po stronie KSeF nie zatrzymała fakturowania i wysyłek w sklepie.

Utrzymanie integracji: co zaplanować na dłużej

Podłączenie do KSeF to nie jednorazowy projekt, tylko element, który trzeba utrzymywać. Zaplanuj z góry kilka rzeczy. Po pierwsze — rotację sekretów: token wygasa z końcem 2026 roku, a certyfikat ma ważność do dwóch lat, więc potrzebujesz kalendarza odnowień, żeby integracja nie stanęła z dnia na dzień. Po drugie — monitoring statusów: każda wysyłka powinna kończyć się potwierdzonym numerem KSeF, a wszystko, co utknęło „w toku” albo zostało odrzucone, musi trafić na widoczną listę do obsługi. Po trzecie — logi i archiwizację: przechowuj wysłany XML, numer KSeF oraz UPO, bo to Twój dowód wystawienia w razie kontroli. Po czwarte — środowisko do regresji: gdy MF zaktualizuje schemat lub API, sprawdź zmianę na środowisku testowym, zanim dotknie produkcji.

Najczęstsze błędy przy podłączaniu (checklista)

• Użycie starego tokena z KSeF 1.0 — nie zadziała w 2.0, wygeneruj nowy.
• Ręczne sklejanie XML zamiast mapowania — drobny błąd oznacza odrzucenie i brak numeru KSeF.
• Testy od razu na produkcji — zacznij od środowiska testowego.
• Brak nadanych uprawnień w MCU przed wygenerowaniem tokena.
• Traktowanie tokena jako rozwiązania na stałe — pamiętaj o wygaśnięciu 31.12.2026 i przejściu na certyfikat.
• Niezapisywanie numeru KSeF i UPO przy zamówieniu — to Twój dowód wystawienia.
• Ignorowanie obowiązku odbioru — dotyczy wszystkich już od lutego 2026.
• Brak planu na awarię i tryb offline.

Dla sklepu sprzedającego na kilku kanałach najtrudniejsze nie jest samo API, tylko spięcie go z resztą obiegu: zamówienie z Allegro czy Shopify, poprawne dane nabywcy, właściwa stawka VAT i wystawienie FA(3) w odpowiednim momencie. Narzędzia klasy multichannel — w tym przygotowywany Nimo — mają docelowo brać ten obieg na siebie, żeby sprzedawca nie musiał utrzymywać własnej integracji z KSeF; jak taka obsługa faktur KSeF ma wyglądać, opisujemy osobno. Niezależnie od wyboru narzędzia zasada jest ta sama: przetestuj wszystko na środowisku testowym, zanim faktury zaczną mieć skutek prawny.

Najczęstsze pytania

Czy potrzebuję certyfikatu, czy wystarczy token?

Do końca 2026 roku token autoryzacyjny wystarczy do automatyzacji przez API. Od 1 stycznia 2027 tokeny wygasają i zastępują je certyfikaty KSeF, więc integrację budowaną na lata warto od razu oprzeć o certyfikat typ 1.

Czym różni się FA(3) od FA(2)?

FA(3) to jedyna obowiązująca struktura od 1 lutego 2026. Dodaje m.in. załączniki binarne i rolę „pracownik”, uściśla pola terminów płatności oraz rozszerza limity znaków. Faktura musi dokładnie pasować do schematu XSD MF, inaczej zostanie odrzucona.

Gdzie testować integrację?

Zacznij w środowisku testowym KSeF 2.0 (orientacyjnie api-test.ksef.mf.gov.pl oraz aplikacja ap-test.ksef.mf.gov.pl), a potem przejdź na przedprodukcyjne (demo). Działania testowe nie wpływają na dane produkcyjne. Aktualne adresy potwierdź na ksef.podatki.gov.pl.

Co to jest numer KSeF i UPO?

Numer KSeF to unikalny identyfikator (35 znaków) nadawany po pozytywnej walidacji — potwierdza, że faktura jest w obiegu. UPO to urzędowe poświadczenie odbioru, w którym ten numer jest zwracany. Oba zapisuj przy zamówieniu jako dowód wystawienia.

Od kiedy muszę wystawiać faktury w KSeF?

Najwięksi (sprzedaż brutto powyżej 200 mln zł w 2024 r.) od 1 lutego 2026, pozostali przedsiębiorcy od 1 kwietnia 2026, a najmniejsi wystawcy od 1 stycznia 2027. Odbieranie faktur w KSeF obowiązuje wszystkich już od lutego 2026.