API KSeF – jak połączyć swój system ERP z Ministerstwem Finansów?

Różnica między tokenem uwierzytelniającym a accessToken – o co chodzi?

Prawidłowa autoryzacja w środowisku Krajowego Systemu e-Faktur wymaga zrozumienia dwuetapowego procesu uwierzytelniania, ponieważ powszechny mit „jeden token wystarczy” jest błędny w architekturze KSeF 2.0. Jak wskazuje dokumentacja techniczna Ministerstwa Finansów: „authenticationToken to tymczasowy token operacyjny otrzymany po wysłaniu żądania uwierzytelniania”. Nie służy on do podpisywania faktur, lecz stanowi wyłącznie przepustkę do uzyskania właściwego poświadczenia w standardzie JWT (JSON Web Token).

Standard autoryzacji opiera się na specyfikacji RFC 7519, która definiuje strukturę tokenów JWT wykorzystywanych jako accessToken. Tokeny wygenerowane w ramach API KSeF 1.0 nie zachowują kompatybilności z nowym interfejsem API KSeF 2.0, co wymusza na programistach i dostawcach systemów ERP implementację nowych procedur wymiany kluczy. Klucz dostępu jest nierozerwalnie powiązany z numerem NIP podatnika oraz przypisanym zakresem uprawnień, które można w dowolnym momencie unieważnić w konsoli zarządzającej.

Proces uzyskiwania dostępu do zasobów API przebiega w ściśle określonej sekwencji czasowej:

1. Wysłanie żądania uwierzytelniającego metodą POST na endpoint /auth/request w celu zainicjowania sesji asynchronicznej.
2. Wykonywanie operacji pollingu z wykorzystaniem krótkotrwałego authenticationToken (ważnego przez 5 minut) do momentu przetworzenia żądania.
3. Odebranie docelowego accessToken, który pełni rolę klucza autoryzacyjnego dla wszystkich operacji merytorycznych i posiada termin ważności wynoszący 24 h.

W związku z powyższym, systemy finansowo-księgowe muszą być zaprojektowane w sposób umożliwiający odświeżanie sesji bez interwencji operatora. Zalecaną praktyką jest przechowywanie aktywnego accessToken wyłącznie w pamięci operacyjnej aplikacji (RAM), unikając jego zapisu w logach systemowych ze względów bezpieczeństwa. Przed każdym planowanym restartem usługi lub zamknięciem modułu komunikacyjnego, należy programowo unieważnić aktywny token sesyjny.

Środowisko testowe KSeF 2.0 – jak uruchomić pierwsze połączenie?

Ministerstwo Finansów udostępniło środowisko testowe API KSeF 2.0 w dniu 30 września 2024 r., umożliwiając dostawcom oprogramowania weryfikację kompatybilności systemów przed wprowadzeniem obowiązku ustawowego. Pierwszym krokiem procesowym jest rejestracja podmiotu integrującego w Module Uprawnień (MCU). Rejestracja odbywa się poprzez oficjalny formularz dostępny pod adresem ksef.podatki.gov.pl/formularz, gdzie należy wskazać NIP podatnika, unikalną nazwę integrowanej aplikacji oraz zdefiniować adresy IP przeznaczone do whitelisty komunikacyjnej.

W ramach MCU podmiot może zarządzać maksymalnie 100 certyfikatami, co pozwala na szerokie testowanie uprawnień dla różnych jednostek organizacyjnych lub oddziałów firmy. Integracja ze środowiskiem testowym jest niezbędna, aby zweryfikować mechanizmy szyfrowania danych, zarządzania dostępem oraz poprawność generowania struktury FA(3). Adres punktu styku dla środowiska testowego to api-test.ksef.mf.gov.pl, który obsługuje protokół HTTPS i standard REST API.

Weryfikację poprawności połączenia można przeprowadzić przy użyciu narzędzia curl z linii poleceń systemu operacyjnego:

curl -X GET 

Poprawna odpowiedź serwera o kodzie 200 OK zawiera aktualny czas systemowy oraz status dostępności poszczególnych modułów KSeF. Deweloperzy powinni wykorzystać narzędzia typu Postman z oficjalnymi kolekcjami udostępnionymi przez Ministerstwo Finansów, co znacząco przyspiesza proces mapowania komunikatów. Przed wysłaniem pierwszej faktury ustrukturyzowanej do środowiska produkcyjnego, krytyczne jest sprawdzenie działania schematu FA(3) w środowisku testowym, aby uniknąć błędów walidacji po 1 lutego 2026 r.

Mapowanie struktury FA(3) – co musi trafić z ERP do XML?

Przejście na standard e-faktury wymaga precyzyjnego mapowania danych z baz danych systemów takich jak MS SQL, SAP czy Comarch do ustandaryzowanego formatu XML zgodnego ze strukturą FA(3). Faktura ustrukturyzowana w wersji 3.0 nakłada obowiązek wypełnienia 45 pól krytycznych, których brak uniemożliwi przyjęcie dokumentu przez system centralny. Maksymalny rozmiar pojedynczego pliku XML został ograniczony do 10 MB, a wszelkie załączniki muszą być szyfrowane przy użyciu algorytmu AES-256.

Pole ERP	XML FA(3)	Typ danych
NIP Sprzedawcy	Podmiot1/DaneIdentyfikacyjne/NIP	String (10 cyfr)
Numer faktury	Fa/P_2	String (max 50 znaków)
Data wystawienia	Fa/P_1	Date (YYYY-MM-DD)
Wartość netto	Fa/P_13_1	Decimal (18,2)
Kwota VAT	Fa/P_14_1	Decimal (18,2)

Szczególną uwagę należy zwrócić na kody Grup Towarowo-Usługowych (GTU) oraz oznaczenia procedur. Przykładowo, dla usług informatycznych wymagane jest stosowanie znacznika <GtuCode>GTU_07</GtuCode>. W przypadku transakcji zwolnionych lub niepodlegających opodatkowaniu, system wymaga podania precyzyjnych stawek takich jak „ZW” (zwolnione), „OO” (odwrotne obciążenie) lub „NP” (niepodlega opodatkowaniu), co musi być odzwierciedlone w logice biznesowej systemu ERP.

W celu optymalizacji wydajności, zaleca się przygotowanie widoków SQL z instrukcją JOIN łączącą nagłówki faktur z pozycjami towarowymi i rejestrami VAT. Walidacja dokumentu względem schematu XSD powinna odbywać się po stronie klienta (lokalnie w ERP) przed wysyłką do API. Taka procedura pozwala zaoszczędzić około 1 sekundy na cyklu komunikacyjnym (round-trip) i redukuje obciążenie interfejsu rządowego niepotrzebnymi błędami składniowymi.

Cennik integracji – ile kosztuje gotowy konektor?

Koszty wdrożenia KSeF są bezpośrednio uzależnione od skali prowadzonej działalności oraz wybranego modelu eksploatacji oprogramowania. Małe przedsiębiorstwa mogą korzystać z rozwiązań typu freemium lub tanich pakietów subskrypcyjnych. Symfonia oferuje pakiet Freemium w cenie 0 zł dla wolumenu do 60 faktur miesięcznie. W przypadku Comarch ERP Optima, koszt obsługi do 600 dokumentów wynosi 25 zł miesięcznie, natomiast rozwiązanie Insert GT dla 500 sztuk dokumentacji wyceniane jest na 49 zł.

Dla podmiotów generujących duże wolumeny faktur przygotowano dedykowane plany taryfowe:

• Symfonia Pakiet Basic: 190 zł miesięcznie.
• Symfonia Pakiet Standard: 690 zł miesięcznie (limit do 2 000 faktur).
• Comarch Optima Chmura (800 faktur): 100 zł miesięcznie.
• Comarch Optima Stacjonarny (30 000 faktur): 200 zł miesięcznie.

Comarch XL stacjonarny – 150 000 faktur

Koszt obsługi wariantu stacjonarnego Comarch XL przy wolumenie do 150 000 faktur wynosi 750 zł miesięcznie. W przypadku przekroczenia tego limitu, roczna opłata ryczałtowa wynosi 13 700 zł. Dla systemów w chmurze (XL Cloud) przy 4 500 fakturach cena wynosi 450 zł miesięcznie.

Należy zauważyć, że integracja z API KSeF 2.0 wymaga aktualizacji oprogramowania, a stare tokeny techniczne zostaną definitywnie wycofane po pełnym uruchomieniu systemu obligatoryjnego. Przy wyborze dostawcy warto negocjować roczną subskrypcję, co pozwala uzyskać rabat sięgający 25 %. Kluczowym aspektem umowy powinna być gwarancja aktualizacji schematów XML w cenie abonamentu, co zabezpiecza podatnika przed zmianami legislacyjnymi.

Check-lista wdrożeniowa – 7 kroków przed 1 lutego 2026

Skuteczne wdrożenie systemu KSeF wymaga harmonogramu działań podzielonego na fazę przygotowawczą i produkcyjną. Zgodnie z wytycznymi, kluczowe jest zapewnienie pełnej integralności danych przesyłanych do systemu centralnego. W pierwszej kolejności należy przeprowadzić inwentaryzację posiadanych licencji ERP oraz zweryfikować dostępność aktualizacji wspierających strukturę FA(3). Proces przygotowania obejmuje następujące etapy:

1. Zaktualizuj system ERP do wersji obsługującej natywnie format FA(3) (np. wersje EZD PUW 3.130 lub 3.132).
2. Załóż konto w Module Uprawnień (MCU) i pobierz certyfikat kwalifikowany lub pieczęć elektroniczną.
3. Skonfiguruj środowisko testowe API KSeF 2.0 i prześlij minimum 10 faktur kontrolnych o różnych stawkach VAT.
4. Przełącz punkt styku aplikacji na adres produkcyjny api.ksef.mf.gov.pl zgodnie z harmonogramem.
5. Uruchom system logowania błędów rejestrujący parametr X-Trace-Id dla każdej transakcji.
6. Ustaw alerty monitorujące odpowiedzi HTTP z kodami 4xx oraz 5xx, aby reagować na przerwy techniczne.
7. Przygotuj wewnętrzną procedurę rollback umożliwiającą wystawianie faktur w formacie PDF (tryb awaryjny).

W przypadku wystąpienia awarii systemu KSeF, podatnik ma obowiązek zgłoszenia stosowania procedury alternatywnej do naczelnika właściwego urzędu skarbowego w ciągu 48 h. Monitoring czasu odpowiedzi API powinien być ustawiony na poziomie poniżej 2 s, aby nie blokować procesów sprzedażowych w firmie. Zaleca się również wykonanie pełnego zrzutu bazy danych przed ostatecznym przełączeniem systemu na tryb produkcyjny, co stanowi zabezpieczenie integralności zasobów informatycznych przedsiębiorstwa.

Czy faktury ustrukturyzowane są jedyną formą dokumentowania transakcji?

Obecnie faktury ustrukturyzowane funkcjonują jako jedna z dopuszczonych form dokumentowania transakcji, obok faktur papierowych i elektronicznych (PDF). Sytuacja ulegnie zmianie po wprowadzeniu obowiązku ustawowego w 2026 roku, kiedy KSeF stanie się jedyną dopuszczalną metodą wystawiania faktur w obrocie B2B.

Kiedy nastąpi przerwa techniczna systemu KSeF 1.0?

Planowana przerwa techniczna systemu KSeF 1.0 nastąpi w dniach od 26 do 31 stycznia 2026 r. Jest to okres krytyczny, w którym nastąpi migracja uprawnień właścicielskich oraz deklaracji ZAW-FA ze starego środowiska do API KSeF 2.0.