KSeF integracja — Jak polaczyc system z Krajowym Systemem e-Faktur

Integracja z KSeF — od czego zaczac?

Integracja z Krajowym Systemem e-Faktur to proces polaczenia Twojego oprogramowania — systemu ERP, programu ksiegowego, platformy e-commerce lub wlasnej aplikacji biznesowej — z centralna platforma Ministerstwa Finansow do obslugi faktur ustrukturyzowanych. Celem integracji jest automatyzacja wystawiania, wysylania i odbierania faktur w formacie XML zgodnym ze schema FA(2), bez koniecznosci recznego logowania sie do portalu KSeF.

Przed rozpoczeciem prac integracyjnych warto zrozumiec, ze Ministerstwo Finansow udostepnia dwa glowne kanaly komunikacji z KSeF. Pierwszy to portal webowy dostepny pod adresem ksef.mf.gov.pl, przeznaczony do recznego wystawiania i przegladania faktur przez przegladarke internetowa. Drugi to REST API — interfejs programistyczny umozliwiajacy automatyczna komunikacje maszyna-maszyna, ktory stanowi podstawe kazdej integracji systemowej.

Proces integracji mozna podzielic na kilka etapow: zapoznanie sie z dokumentacja techniczna API, wybor metody uwierzytelniania, przygotowanie srodowiska testowego, implementacja generowania XML FA(2), wdrozenie komunikacji z API KSeF oraz testowanie na srodowisku testowym przed przejsciem na produkcje. Kazdy z tych etapow omowimy szczegolowo w dalszej czesci przewodnika.

Integracja z KSeF jest obowiazkowa dla kazdego oprogramowania do fakturowania, ktore ma byc uzywane po wejsciu w zycie obowiazku obowiazkowego KSeF. Niezaleznie od tego, czy jestes tworca oprogramowania, integratorem systemowym czy przedsiebiorca z wlasnym systemem IT — zrozumienie API KSeF jest kluczowe dla plynnego przejscia na nowy model fakturowania.

API KSeF — struktura i endpointy

API Krajowego Systemu e-Faktur to interfejs REST oparty na protokole HTTPS, ktory umozliwia programistyczna komunikacje z systemem. Ministerstwo Finansow opublikowalo pelna specyfikacje OpenAPI (Swagger), ktora opisuje wszystkie dostepne endpointy, parametry wejsciowe, formaty odpowiedzi oraz kody bledow.

System KSeF udostepnia dwa srodowiska z osobnymi adresami bazowymi. Srodowisko produkcyjne dziala pod adresem https://ksef.mf.gov.pl/api i sluzy do wystawiania prawdziwych faktur z pelna moca prawna. Srodowisko testowe (demo) dostepne jest pod adresem https://ksef-test.mf.gov.pl/api i pozwala na testowanie integracji bez skutkow prawnych — wszystkie faktury wystawione w srodowisku testowym sa ignorowane przez administracje skarbowa.

Glowne grupy endpointow API KSeF obejmuja:

• Sesja (Session) — endpointy do otwierania i zamykania sesji uwierzytelnionych, generowania tokenow dostepu oraz sprawdzania statusu sesji. Kazda operacja w KSeF wymaga aktywnej sesji uwierzytelnionej
• Wystawianie faktur (Invoice Send) — endpointy do przesylania faktur w formacie XML FA(2). Po pomyslnej walidacji system nadaje fakturze unikalny numer referencyjny KSeF
• Pobieranie faktur (Invoice Get) — endpointy do pobierania faktur przychodzacych i wychodzacych na podstawie numeru referencyjnego KSeF, NIP kontrahenta lub zakresu dat
• Status faktury — endpointy do sprawdzania statusu wyslanych faktur i pobierania Urzedowego Poswiadczenia Odbioru (UPO)
• Wyszukiwanie (Query) — endpointy do przeszukiwania zbioru faktur z filtrowaniem po datach, NIP-ach, typach dokumentow i statusach
• Batch (pakietowe) — endpointy do wysylania wielu faktur jednoczesnie w ramach jednej sesji, co jest kluczowe dla systemow przetwarzajacych duze wolumeny dokumentow

Wszystkie odpowiedzi API sa zwracane w formacie JSON (z wyjatkiem samych faktur, ktore sa w XML). API stosuje standardowe kody HTTP — 200 dla sukcesu, 400 dla bledow walidacji, 401 dla problemow z uwierzytelnianiem, 404 gdy faktura nie zostala znaleziona, oraz 500 dla bledow wewnetrznych systemu.

Format XML FA(2) — struktura faktury ustrukturyzowanej

Kazda faktura przesylana do KSeF musi byc zapisana w formacie XML zgodnym ze schema FA(2) opracowana przez Ministerstwo Finansow. Schema FA(2) to formalny dokument XSD (XML Schema Definition), ktory scisle definiuje strukture dokumentu — kazdy element, atrybut, typ danych, dlugosc pola i reguly walidacji.

Struktura dokumentu XML FA(2) sklada sie z kilku glownych sekcji. Element glowny <Faktura> zawiera naglowek z informacjami o wersji schematu i rodzaju faktury. Sekcja <Podmiot1> opisuje dane sprzedawcy — NIP, pelna nazwe, adres siedziby oraz opcjonalnie dane kontaktowe i numer rachunku bankowego. Sekcja <Podmiot2> zawiera analogiczne dane nabywcy.

Sekcja <Fa> to serce dokumentu, zawierajace wlasciwe dane faktury: numer dokumentu, daty (wystawienia, sprzedazy, terminu platnosci), walute, pozycje towarowe lub uslugowe z cenami, ilosciami i stawkami VAT, a takze podsumowanie kwotowe. Kazda pozycja faktury jest opisana w elemencie <FaWiersz> z polami takimi jak <P_7> (nazwa towaru/uslugi), <P_8A> (jednostka miary), <P_8B> (ilosc), <P_9A> (cena jednostkowa netto) i <P_12> (stawka VAT).

Nazwy pol w schemacie FA(2) sa oparte na numeracji paragrafow ustawy o VAT, co sprawia, ze poczatkowo moga wydawac sie malo intuicyjne. Na przyklad pole <P_1> to data wystawienia, <P_2> to numer faktury, a <P_13_1> to kwota netto dla danej stawki VAT. Pelna dokumentacja pol jest dostepna na stronie Ministerstwa Finansow i w oficjalnej specyfikacji XSD.

Przed wyslaniem faktury do KSeF nalezy przeprowadzic lokalna walidacje XML wzgledem schematu XSD. Pozwala to na wykrycie bledow jeszcze przed komunikacja z API i unikniecie niepotrzebnych zapytan do systemu. Wiekszosc jezykow programowania oferuje wbudowane biblioteki do walidacji XML/XSD — w Javie jest to javax.xml.validation, w Pythonie lxml, a w .NET System.Xml.Schema.

Metody uwierzytelniania w API KSeF

Dostep do API KSeF wymaga uwierzytelnienia, ktore potwierdza tozsamosc podmiotu wystawiajacego lub pobierajacego faktury. Ministerstwo Finansow udostepnia trzy glowne metody uwierzytelniania, kazda przeznaczona dla innego scenariusza uzycia.

Token autoryzacyjny to najbardziej popularna metoda w kontekscie integracji systemowej. Token jest generowany jednorazowo w portalu KSeF po zalogowaniu profilem zaufanym lub podpisem kwalifikowanym, a nastepnie uzywany programistycznie do otwierania sesji API. Token moze byc ograniczony czasowo lub bezterminowy, a takze moze miec zawezone uprawnienia — na przyklad tylko do wystawiania faktur, bez mozliwosci ich pobierania. To idealne rozwiazanie dla systemow dzialajacych w tle (batch processing, cron jobs, integracje ERP), gdzie nie ma mozliwosci interaktywnego logowania.

Pieczec elektroniczna (e-pieczec) to metoda przeznaczona dla podmiotow prawnych — spolek, fundacji, stowarzyszen. Pieczec elektroniczna jest wydawana przez kwalifikowanego dostawce uslug zaufania i potwierdza tozsamosc organizacji (nie osoby fizycznej). W procesie integracji pieczec jest uzywana do podpisywania zadania otwarcia sesji API. Ta metoda jest szczegolnie zalecana dla duzych firm z wieloma uzytkownikami systemu fakturowania.

Podpis kwalifikowany to metoda oparta na certyfikacie kwalifikowanym wydawanym przez akredytowanego dostawce (np. Certum, SimplySign, Szafir). Podpis kwalifikowany jest rownowazny podpisowi odrecznemu i moze byc uzywany zarowno do logowania interaktywnego, jak i do programistycznego otwierania sesji API. W integracji systemowej podpis kwalifikowany wymaga dostepu do pliku certyfikatu i hasla, co moze byc mniej wygodne niz token, ale zapewnia najwyzszy poziom bezpieczenstwa.

Niezaleznie od wybranej metody uwierzytelniania, proces otwarcia sesji API przebiega podobnie: klient wysyla zadanie autoryzacji do endpointu sesji, system KSeF weryfikuje dane uwierzytelniajace, a w odpowiedzi zwraca token sesji, ktory jest dolaczany do kazdego kolejnego zapytania w naglowku HTTP SessionToken. Sesja ma ograniczony czas zycia i musi byc jawnie zamknieta po zakonczeniu operacji.

Wyslanie faktury do KSeF przez API

Proces wyslania faktury do KSeF przez API sklada sie z kilku kolejnych krokow, ktore musza byc wykonane w scislej kolejnosci. Ponizej przedstawiamy pelny przeplyw integracji — od przygotowania danych po otrzymanie potwierdzenia.

1. Przygotowanie danych faktury — zbierz wszystkie wymagane dane: informacje o sprzedawcy i nabywcy, pozycje towarowe lub uslugowe, stawki VAT, warunki platnosci. Dane moga pochodzic z systemu ERP, bazy danych lub formularza uzytkownika.
2. Generowanie XML FA(2) — przeksztalc dane faktury w dokument XML zgodny ze schema FA(2). Uzyj biblioteki XML w swoim jezyku programowania lub dedykowanego szablonu. Pamietaj o poprawnym kodowaniu znakow (UTF-8) i formatowaniu dat (YYYY-MM-DD).
3. Walidacja lokalna — zwaliduj wygenerowany XML wzgledem schematu XSD przed wyslaniem. Pozwoli to wykryc bledy strukturalne (brakujace pola, nieprawidlowe typy danych, przekroczone dlugosci) bez angazowania API KSeF.
4. Otwarcie sesji — wyslij zapytanie POST do endpointu /api/online/Session/InitSigned (lub odpowiedniego dla Twojej metody uwierzytelniania) z danymi autoryzacyjnymi. W odpowiedzi otrzymasz token sesji.
5. Wyslanie faktury — wyslij zapytanie PUT do endpointu /api/online/Invoice/Send z dokumentem XML w ciele zapytania i tokenem sesji w naglowku. System KSeF zwaliduje fakture i — jesli jest poprawna — nada jej numer referencyjny.
6. Odczytanie odpowiedzi — system zwraca odpowiedz JSON zawierajaca numer referencyjny KSeF (np. 1234567890-20260331-ABC123DEF456-78), date i godzine przyjecia faktury oraz hash dokumentu. Zapisz te dane w swoim systemie — numer referencyjny bedzie potrzebny do pobierania UPO i identyfikacji faktury.
7. Zamkniecie sesji — po zakonczeniu operacji wyslij zapytanie GET do endpointu /api/online/Session/Terminate, aby zamknac sesje. Niezamkniete sesje wygasaja automatycznie po okreslonym czasie, ale dobra praktyka jest jawne ich konczenie.

W przypadku bledow walidacji API zwraca szczegolowy komunikat z informacja o blednym polu, oczekiwanym formacie i regule, ktora zostala naruszona. Dzieki temu mozna szybko zidentyfikowac i naprawic problem w generowanym XML.

Pobieranie UPO i statusu faktury

Po wyslaniu faktury do KSeF kluczowym krokiem jest pobranie Urzedowego Poswiadczenia Odbioru (UPO). UPO to oficjalny dokument potwierdzajacy, ze faktura zostala prawidlowo przyjeta przez Krajowy System e-Faktur. Ma on moc dowodowa i moze byc wymagany podczas kontroli skarbowej lub w sporach z kontrahentami.

UPO mozna pobrac za pomoca endpointu /api/online/Invoice/Status/{invoiceElementReferenceNumber}, przekazujac numer referencyjny KSeF otrzymany podczas wysylania faktury. Odpowiedz zawiera status faktury (przyjeta, w trakcie przetwarzania, odrzucona), date i godzine przetworzenia oraz sam dokument UPO w formacie XML.

Warto pamietac, ze generowanie UPO moze nie byc natychmiastowe — w okresach duzego obciazenia systemu czas oczekiwania moze wynosic od kilku sekund do kilku minut. Dlatego zaleca sie implementacje mechanizmu odpytywania (polling) z opoznieniem — na przyklad sprawdzanie statusu co 5-10 sekund, maksymalnie przez 5 minut. W przypadku przekroczenia tego czasu nalezy zalogowac sytuacje i ponowic probe pozniej.

Oprocs UPO dla pojedynczych faktur, API KSeF umozliwia rowniez pobieranie zbiorczego UPO dla calej sesji. Po zamknieciu sesji, w ktorej wystawiono wiele faktur, mozna pobrac jeden dokument UPO potwierdzajacy odbiory wszystkich faktur z danej sesji. Jest to szczegolnie przydatne w systemach przetwarzajacych duze wolumeny dokumentow.

Srodowisko testowe KSeF

Ministerstwo Finansow udostepnia pelne srodowisko testowe KSeF pod adresem https://ksef-test.mf.gov.pl, ktore jest identyczne funkcjonalnie z systemem produkcyjnym, ale nie generuje faktur o mocy prawnej. Kazdy zespol programistyczny pracujacy nad integracja z KSeF powinien zaczac wlasnie od tego srodowiska.

Srodowisko testowe pozwala na pelny cykl operacji: otwarcie sesji, wyslanie faktur, sprawdzenie statusu, pobranie UPO, pobranie faktur przychodzacych oraz zamkniecie sesji. Dane testowe sa izolowane od systemu produkcyjnego — nie ma ryzyka wystawienia prawdziwej faktury ani wplywu na rozliczenia podatkowe.

Aby rozpoczac testowanie, nalezy wygenerowac token autoryzacyjny w srodowisku testowym. Proces jest identyczny jak na produkcji — logowanie profilem zaufanym lub podpisem kwalifikowanym do portalu testowego, a nastepnie wygenerowanie tokena w panelu zarzadzania uprawnieniami. Wazne: tokeny z srodowiska testowego nie dzialaja na produkcji i odwrotnie.

Podczas testowania warto przetestowac nie tylko scenariusze pozytywne (poprawna faktura, pomyslne wyslanie), ale takze negatywne: nieprawidlowy XML, brakujace pola, bledny NIP, wygasly token, duplikat faktury. Pozwoli to na zbudowanie solidnej obslugi bledow w Twoim systemie, zanim przejdziesz na produkcje.

Ministerstwo Finansow okresowo resetuje dane w srodowisku testowym. Nie nalezy wiec traktowac go jako trwalego magazynu danych — wszystkie testowe faktury i sesje moga zostac usuniete bez uprzedzenia. Zapisuj wyniki testow lokalnie i utrzymuj zautomatyzowane testy integracyjne, ktore mozna uruchomic w dowolnym momencie.

Typowe bledy integracji z KSeF

Integracja z KSeF wiaze sie z wieloma potencjalnymi pulapkami, ktore moga spowolnic wdrozenie lub powodowac bledy w produkcji. Ponizej przedstawiamy najczesciej spotykane problemy i sposoby ich rozwiazywania.

• Bledy walidacji XML — najczestszy problem. Wynikaja z niezgodnosci wygenerowanego XML ze schema FA(2): brakujace wymagane pola, nieprawidlowe typy danych (tekst zamiast liczby), przekroczone dlugosci pol lub niepoprawne formaty dat. Rozwiazanie: zawsze waliduj XML lokalnie przed wyslaniem i utrzymuj aktualna wersje schematu XSD
• Bledy uwierzytelniania — wygasly token, nieprawidlowy certyfikat lub brak uprawnien do wystawiania faktur dla danego NIP. Rozwiazanie: implementuj automatyczne odnawianie tokenow, monitoruj daty waznosci certyfikatow i sprawdzaj uprawnienia w panelu KSeF
• Timeout sesji — sesja KSeF ma ograniczony czas zycia. Jesli wystawianie faktur trwa dluzej niz limit sesji, polaczenie zostanie przerwane. Rozwiazanie: dziel duze partie faktur na mniejsze paczki, otwieraj nowa sesje dla kazdej paczki
• Problemy z kodowaniem znakow — polski tekst zawierajacy znaki diakrytyczne moze powodowac bledy, jesli dokument XML nie jest prawidlowo zakodowany w UTF-8. Rozwiazanie: upewnij sie, ze deklaracja XML zawiera encoding="UTF-8" i ze pliki sa rzeczywiscie zapisane w tym kodowaniu
• Nieprawidlowe obliczenia kwotowe — KSeF automatycznie weryfikuje poprawnosc obliczen VAT na fakturze. Jesli suma pozycji nie zgadza sie z podsumowaniem lub kwota VAT jest nieprawidlowo obliczona, faktura zostanie odrzucona. Rozwiazanie: implementuj precyzyjne obliczenia z zaokraglaniem zgodnym z przepisami (do dwoch miejsc po przecinku, zaokraglanie w gore od 0.005)
• Brak obslugi bledow API — API KSeF moze zwracac rozne kody bledow, w tym bledy tymczasowe (503 — serwis niedostepny). Rozwiazanie: implementuj mechanizm ponawiania prob (retry) z wykladniczym opoznieniem (exponential backoff) oraz logowanie wszystkich odpowiedzi API dla celow diagnostycznych
• Rozbieznosc wersji schematu — Ministerstwo Finansow moze aktualizowac scheme FA(2). Uzywanie nieaktualnej wersji schematu powoduje odrzucenie faktur. Rozwiazanie: monitoruj komunikaty Ministerstwa Finansow i aktualizuj schemat w swoim systemie niezwlocznie po publikacji nowej wersji

Faktuj API — gotowa integracja z KSeF

Faktuj to darmowy generator faktur VAT online, ktory oferuje rowniez REST API do automatycznego generowania faktur. Dzieki Faktuj nie musisz samodzielnie implementowac calej logiki generowania XML FA(2) i komunikacji z API KSeF — wystarczy, ze wyslisz dane faktury do API Faktuj, a reszta zostanie wykonana automatycznie.

API Faktuj dziala jako warstwa posrednia miedzy Twoim systemem a KSeF. Zamiast bezposredniej integracji z API Ministerstwa Finansow — co wymaga znajomosci schematu FA(2), obslugi sesji, tokenow i walidacji — mozesz uzyc prostego REST API Faktuj z danymi faktury w formacie JSON. Faktuj automatycznie przeksztalca dane w poprawny XML FA(2), waliduje dokument i przesyla go do KSeF.

Glowne zalety integracji przez Faktuj API:

• Prosty format wejsciowy — dane faktury wysylasz w JSON, nie musisz generowac XML FA(2) samodzielnie
• Automatyczna walidacja — Faktuj waliduje dane przed wyslaniem do KSeF i zwraca czytelne komunikaty bledow
• Obsluga sesji — Faktuj automatycznie zarzadza sesjami KSeF, tokenami i ich odnawianiem
• Generowanie PDF — oprocs wyslania do KSeF Faktuj generuje rowniez czytelna wersje PDF faktury
• Calkowicie darmowe — API Faktuj jest bezplatne, bez limitow, abonamentow ani ukrytych kosztow

Szczegolowa dokumentacja API Faktuj jest dostepna na stronie dokumentacji. Znajdziesz tam pelna liste endpointow, przyklady zapytan w cURL, JavaScript i Python, a takze opisy wszystkich parametrow i odpowiedzi.

Dowiedz sie wiecej o KSeF

Przygotowalismy szczegolowe przewodniki dotyczace Krajowego Systemu e-Faktur:

• KSeF 2026 — kompletny przewodnik po Krajowym Systemie e-Faktur
• KSeF co to jest — czym jest Krajowy System e-Faktur i jak dziala
• KSeF obowiazkowy — kiedy KSeF staje sie obowiazkowy i kogo dotyczy
• Jak wystawic fakture w KSeF — poradnik krok po kroku
• KSeF dla malych firm — praktyczny przewodnik dla mikro i malych przedsiebiorstw
• Faktura elektroniczna KSeF — wszystko o e-fakturach w Krajowym Systemie

Zobacz rowniez

• Faktura VAT — podstawowy dokument sprzedazy miedzy podatnikami
• Dokumentacja API Faktuj — pelna specyfikacja REST API do generowania faktur
• Rodzaje faktur — kompletne porownanie wszystkich typow faktur
• Faktura korygujaca — korekta bledow na fakturze
• Faktura proforma — dokument ofertowy przed sprzedaza