
Integracja z KSeF przez API polega na tym, że Twój system samodzielnie wysyła faktury do Krajowego Systemu e-Faktur i odbiera potwierdzenia z numerem KSeF, bez ręcznego logowania do portalu. Żeby to działało, potrzebujesz tokena uwierzytelniającego, biblioteki do budowania XML w formacie FA(3) i kolejki z ponawianiem, bo KSeF bywa niedostępny. Poniżej opisuję kolejność działań tak, jak robimy to w praktyce: przy wystawianiu faktur w naszym systemie CRM i przy imporcie faktur zakupowych w Spario.
Jak działa KSeF API i co musisz wiedzieć przed startem
KSeF udostępnia dwa środowiska: testowe i produkcyjne. Adresy bazowe różnią się domeną, a struktura endpointów jest taka sama. Oficjalna dokumentacja API i schemat XSD dla FA(3) są dostępne na stronie Ministerstwa Finansów pod adresem ksef.mf.gov.pl.
API jest synchroniczne w jednym miejscu i asynchroniczne w innym. Wysyłasz fakturę, dostajesz identyfikator sesji, potem pytasz o status. Nie dostajesz numeru KSeF od razu w odpowiedzi na wysyłkę: to najczęstsze nieporozumienie przy pierwszym podejściu.
Uwierzytelnianie opiera się na tokenie wygenerowanym dla NIP firmy. Token może być wystawiony dla konkretnego zakresu uprawnień: wysyłanie, pobieranie albo oba. Nie ma jednego tokena do wszystkiego na zawsze: tokeny wygasają i trzeba je odnawiać.
Format faktury to XML zgodny ze schematem FA(3). Schemat jest wersjonowany, a KSeF odrzuca dokumenty niezgodne z aktualną wersją. Walidacja po Twojej stronie, przed wysyłką, oszczędza czas: błąd wykryty lokalnie nie generuje sesji i nie wchodzi do kolejki.
Krok 1: Sprawdź, czy Twój system ma API albo eksport
Zanim napiszesz pierwszą linijkę kodu integracyjnego, sprawdź, skąd wezmą się dane do faktury.
Jeśli Twój system ma REST API z endpointem zwracającym zamówienie lub transakcję w JSON, integracja jest prosta: czytasz dane, budujesz XML, wysyłasz. Jeśli system nie ma API, ale ma eksport do CSV lub XML, integracja jest możliwa, ale wymaga parsowania i harmonogramu uruchamiania eksportu. Jeśli system nie ma ani API, ani eksportu, zostaje dostęp do bazy danych albo robot klikający w interfejsie, a to inna wycena i inne ryzyko.
Po czym poznasz, że krok się udał: masz listę pól, które zwraca Twój system, i wiesz, które z nich odpowiadają polom FA(3): NIP nabywcy, nazwa, adres, pozycje z kwotami netto, stawka VAT, data sprzedaży, forma płatności.
Najczęstszy błąd: zakładanie, że skoro system wystawia faktury PDF, to ma gdzieś ustrukturyzowane dane. Faktura PDF może być generowana z szablonu HTML bez żadnego modelu danych, który dałoby się odczytać programowo.
Krok 2: Zarejestruj token i skonfiguruj środowisko testowe
Token uwierzytelniający generujesz w portalu KSeF dla NIP firmy. Do środowiska testowego możesz użyć dowolnego NIP, bo dane testowe nie trafiają do produkcji.
Token ma zakres uprawnień. Przy integracji wysyłającej faktury potrzebujesz uprawnienia do wystawiania dokumentów. Przy imporcie faktur zakupowych potrzebujesz uprawnienia do odczytu. Przy obu kierunkach potrzebujesz obu zakresów, ale możesz użyć dwóch osobnych tokenów z węższymi uprawnieniami: to bezpieczniejsze, bo kompromitacja jednego nie blokuje drugiego.
Token przechowujesz po stronie swojego systemu, nie po stronie KSeF. Oznacza to, że jesteś odpowiedzialny za jego bezpieczeństwo: nie trafia do repozytorium kodu, nie pojawia się w logach, nie jest hardkodowany w konfiguracji.
Po czym poznasz, że krok się udał: wywołujesz endpoint uwierzytelniający na środowisku testowym i dostajesz odpowiedź z kodem 200 oraz sesją. Każde inne zachowanie to problem z tokenem albo z NIP-em.
Najczęstszy błąd: użycie tokena produkcyjnego na środowisku testowym albo odwrotnie. Adresy bazowe są różne i system powinien mieć osobną konfigurację dla każdego środowiska, z przełącznikiem.
Krok 3: Zbuduj i zwaliduj XML w formacie FA(3)
Schemat FA(3) jest dostępny jako plik XSD na stronie Ministerstwa Finansów. Pobierz go i zwaliduj swój XML lokalnie, zanim wyślesz cokolwiek do KSeF.
Faktura FA(3) ma kilka sekcji obowiązkowych: nagłówek z danymi stron, pozycje, podsumowanie VAT i sekcję płatności. Każda sekcja ma wymagane pola i dozwolone wartości dla kodów, na przykład kod stawki VAT to nie liczba, ale kod słownikowy ze schematu.
Przy budowaniu XML zwróć uwagę na trzy rzeczy. Pierwsza: kolejność elementów w XML musi być zgodna ze schematem, bo XSD jest ordered. Druga: daty mają format ISO 8601, a nie format z polskiej faktury PDF. Trzecia: kwoty mają określoną liczbę miejsc po przecinku i nie mogą być zaokrąglane inaczej niż wynika ze schematu.
Walidacja lokalna przez bibliotekę XSD zajmuje milisekundy i wychwytuje większość błędów przed wysyłką. W projekcie Planeta Konopi używamy walidacji po stronie Node.js przed każdą próbą wysyłki: faktura, która nie przechodzi walidacji lokalnej, nie wchodzi do kolejki.
Po czym poznasz, że krok się udał: Twój XML przechodzi walidację XSD bez błędów i możesz go otworzyć w przeglądarce XML bez ostrzeżeń o strukturze.
Najczęstszy błąd: budowanie XML przez konkatenację stringów zamiast przez bibliotekę DOM albo dedykowany builder. Konkatenacja nie pilnuje kolejności elementów ani kodowania znaków specjalnych, a KSeF odrzuci dokument z nieprawidłowym XML bez czytelnego komunikatu o przyczynie.
Krok 4: Wyślij fakturę i odbierz identyfikator sesji
Wysyłka faktury to żądanie POST z XML-em zakodowanym w Base64. W odpowiedzi dostajesz identyfikator sesji, nie numer KSeF. Numer KSeF jest dostępny dopiero po tym, jak KSeF przetworzy dokument, co może trwać od sekund do kilku minut.
Kolejka po Twojej stronie jest konieczna. Jeśli KSeF jest chwilowo niedostępny albo zwraca błąd 503, Twój system musi zapamiętać fakturę i ponowić próbę. Bez kolejki faktura przepada albo jest wysyłana podwójnie, co generuje duplikaty.
Przy wdrożeniu dla Spario import faktur zakupowych działa przez polling: system co określony czas pyta KSeF o nowe dokumenty wystawione na NIP firmy i importuje te, których jeszcze nie ma w bazie. To prostsze niż webhook, bo KSeF nie wysyła powiadomień push.
Po czym poznasz, że krok się udał: dostajesz identyfikator sesji z kodem 200, a po odpytaniu o status sesji dostajesz numer KSeF przypisany do dokumentu.
Najczęstszy błąd: brak idempotentności. Jeśli sieć przerwie żądanie po wysyłce, ale przed odebraniem odpowiedzi, nie wiesz, czy faktura dotarła. Bez mechanizmu sprawdzającego, czy dokument o danym identyfikatorze wewnętrznym jest już w KSeF, wyślesz go drugi raz.
Krok 5: Zapisz numer KSeF przy dokumencie i obsłuż korekty
Numer KSeF to ciąg znaków przypisany przez system do każdego dokumentu. Przechowujesz go przy fakturze w swojej bazie. Bez tego numeru nie możesz wystawić korekty do tej faktury.
Korekta w KSeF to osobny dokument z referencją do numeru KSeF faktury korygowanej. Ścieżka jest taka sama jak przy zwykłej fakturze: budowanie XML, walidacja, wysyłka, odebranie numeru KSeF korekty. Jeśli Twój system obsługuje korekty, musi przechowywać numery KSeF wszystkich wystawionych faktur.
Alert przy nieudanej wysyłce powinien trafiać do konkretnej osoby, nie tylko do logu. W naszych wdrożeniach alert idzie na e-mail albo do kanału w narzędziu do komunikacji wewnętrznej, z informacją o numerze faktury i komunikatem błędu z KSeF.
Po czym poznasz, że krok się udał: numer KSeF jest zapisany przy fakturze w Twoim systemie, faktura jest widoczna w portalu KSeF po zalogowaniu, a korekta wystawiona do tej faktury ma poprawną referencję.
Najczęstszy błąd: przechowywanie numeru KSeF tylko w logu albo tylko w pliku, bez zapisu do bazy. Przy awarii serwera tracisz możliwość wystawienia korekty.
Krok 6: Uruchom na środowisku produkcyjnym i monitoruj
Przed przełączeniem na produkcję przetestuj pełny przepływ na środowisku testowym z danymi jak najbardziej zbliżonymi do produkcyjnych: różne stawki VAT, faktury walutowe jeśli je wystawiasz, korekty.
Na produkcji pierwsze faktury wysyłaj ręcznie wyzwalanym przepływem, nie automatycznie. Sprawdź każdą w portalu KSeF. Dopiero po kilku dniach bez błędów włącz automatyczne wysyłanie przy zdarzeniu w systemie.
Monitoring powinien obejmować trzy rzeczy: liczbę faktur w kolejce, liczbę nieudanych prób wysyłki i czas od wystawienia faktury do odebrania numeru KSeF. Jeśli czas rośnie, KSeF może być przeciążony albo Twoja kolejka ma problem.
Po czym poznasz, że krok się udał: przez tydzień bez interwencji ręcznej wszystkie faktury mają numery KSeF, a alerty nie wychodzą.
Najczęstszy błąd: brak monitoringu po wdrożeniu. KSeF zmienia strukturę schematu, a Twój system przestaje walidować bez żadnego ostrzeżenia, dopóki ktoś nie zauważy, że faktury nie trafiają do systemu.
Ile to kosztuje
Integracja z KSeF to usługa, którą wyceniamy po rozmowie, bo cena zależy od systemu po Twojej stronie. Stałą kwotę dostajesz w 3 dni robocze od pierwszej rozmowy, która jest bezpłatna i trwa 45 minut.
Wysyłka faktur z jednego systemu w jednym kierunku to najkrótszy wariant: do 2 tygodni wdrożenia. Jeśli Twój system ma publiczne API z dokumentacją, jest to tańsze niż wtedy, gdy trzeba się dobierać przez eksport pliku albo dostęp do bazy.
Jeśli integrujesz kilka systemów jednocześnie, na przykład sklep, CRM i ERP, albo potrzebujesz obu kierunków, wysyłki i importu zakupowych, to dwie osobne części wyceny. Reguły przypisywania kosztów przy imporcie faktur zakupowych różnią się w każdej firmie i są osobnym etapem.
Jeśli KSeF jest jednym z modułów większego systemu, na przykład ERP albo dedykowanego systemu fakturowania, cena mieści się w kwocie systemu, który zaczyna się od 19 500 zł netto. Więcej o tym, jak wygląda wycena systemu z integracją KSeF, opisujemy na stronie integracji z KSeF.
Korzystanie z API KSeF nie kosztuje nic: Ministerstwo Finansów nie pobiera opłat za korzystanie z systemu. Aktualny regulamin jest dostępny na stronie ksef.mf.gov.pl.
Ile to trwa
Wdrożenie integracji w jednym kierunku, od zatwierdzenia zakresu do produkcji, zajmuje do 2 tygodni, gdy łączymy jeden system z publicznym API.
Przed tym są dwa kroki o stałym czasie: 45 minut rozmowy i 3 dni robocze na zakres ze stałą ceną. Termin liczymy od zatwierdzenia zakresu i od chwili, w której mamy dostęp do Twojego systemu oraz uprawnienia w KSeF.
Dłużej trwa to w trzech sytuacjach. Pierwsza: Twój system nie ma API i trzeba budować adapter do eksportu pliku. Druga: integrujesz kilka systemów naraz. Trzecia: potrzebujesz obu kierunków, wysyłki i importu, bo to dwie osobne części z osobnymi testami.
Przy wdrożeniu dla Planeta Konopi automatyczne e-faktury KSeF 2.0 w formacie FA(3) działają produkcyjnie od 2 czerwca 2026. Projekt ruszył 5 maja 2026. Więcej szczegółów o tym projekcie znajdziesz w opisie realizacji sklepu Planeta Konopi.
Przy wdrożeniu dla Spario import faktur zakupowych z KSeF jest częścią systemu ERP dla firmy transportowej. Opis tego projektu jest dostępny na stronie klientów CRM i ERP.
Czego potrzebujemy od klienta
Na pierwszej rozmowie potrzebujemy odpowiedzi na cztery pytania.
Pierwsze: z jakiego systemu pochodzi faktura? Nazwa systemu i to, czy ma API, eksport czy żadne z tych dwóch.
Drugie: w którą stronę idą faktury? Wysyłasz faktury sprzedażowe, importujesz zakupowe czy oba kierunki?
Trzecie: jakie rodzaje dokumentów wystawiasz? Zwykłe faktury to podstawa. Korekty, faktury zaliczkowe i faktury w walucie obcej dokładają reguł, o które pytamy przed wyceną.
Czwarte: kto w Twojej firmie ma uprawnienia do KSeF? Token musi być wygenerowany przez osobę z odpowiednimi uprawnieniami do NIP firmy.
Po zatwierdzeniu zakresu potrzebujemy dostępu do środowiska testowego Twojego systemu albo do jego dokumentacji API, oraz tokena do środowiska testowego KSeF. Na produkcję przechodzimy dopiero po testach.
Jeśli Twój system to gotowe oprogramowanie, na przykład program księgowy albo platforma e-commerce, sprawdź najpierw, czy producent nie udostępnia już wtyczki do KSeF. Jeśli udostępnia, integracja może być konfiguracją, a nie programowaniem.
Kiedy to nie jest potrzebne
Integracja przez API nie jest potrzebna w kilku sytuacjach.
Jeśli wystawiasz kilka faktur miesięcznie, ręczne wystawianie przez portal KSeF albo przez program księgowy z wbudowaną obsługą KSeF jest szybsze i tańsze niż budowanie integracji. Koszt wdrożenia zwróci się dopiero przy wystarczającej liczbie dokumentów, żeby ręczna praca zajmowała ludziom realny czas.
Jeśli Twój program księgowy już obsługuje KSeF, nie potrzebujesz osobnej integracji. Większość popularnych programów księgowych w Polsce wbudowała obsługę KSeF bezpośrednio. Sprawdź u swojego dostawcy, zanim zamówisz cokolwiek.
Jeśli wystawiasz faktury tylko w jednym systemie i nie masz potrzeby łączenia go z innymi, wystarczy konfiguracja tego systemu, a nie pisanie kodu.
Jeśli Twój system nie ma API i nie ma eksportu danych w ustrukturyzowanym formacie, koszt budowania adaptera może przewyższyć korzyść. W takim przypadku uczciwa odpowiedź brzmi: zmień system albo wystawiaj faktury ręcznie przez portal.
Integracja przez API ma sens wtedy, gdy faktury powstają jako zdarzenie w systemie, na przykład przy zamówieniu w sklepie albo przy zamknięciu transakcji w CRM, i chcesz, żeby numer KSeF wracał automatycznie do tego samego systemu bez żadnej ręcznej czynności.
Najczęstsze błędy na każdym kroku
Poniżej zebrałem błędy, które powtarzają się niezależnie od systemu po stronie klienta.
**Brak kolejki z ponawianiem.** KSeF ma okna niedostępności. System, który wysyła fakturę synchronicznie przy zdarzeniu i nie ma mechanizmu ponawiania, traci faktury przy każdej przerwie. Kolejka to nie opcja, to warunek konieczny.
**Brak walidacji lokalnej przed wysyłką.** KSeF zwraca błędy walidacji, ale komunikaty nie zawsze wskazują dokładne pole. Walidacja przez XSD po Twojej stronie jest szybsza i czytelniejsza.
**Przechowywanie tokena w kodzie źródłowym.** Token w repozytorium to wyciek uprawnień do KSeF firmy. Token trafia do zmiennych środowiskowych albo do sejfu na sekrety, nie do pliku konfiguracyjnego commitowanego do repozytorium.
**Brak obsługi asynchroniczności.** Wysyłasz i czekasz na numer KSeF w tym samym żądaniu HTTP. KSeF nie działa synchronicznie: dostajesz identyfikator sesji, potem pytasz o status. System, który blokuje wątek na czekanie, będzie miał problemy przy wolnym KSeF.
**Brak referencji do numeru KSeF przy korekcie.** Korekta bez numeru KSeF faktury korygowanej jest odrzucana. Jeśli nie zapisałeś numeru KSeF przy wystawieniu faktury, nie możesz wystawić korekty programowo.
**Testowanie tylko na środowisku testowym z prostymi danymi.** Środowisko testowe nie symuluje wszystkich błędów produkcyjnych. Testuj z danymi jak najbardziej zbliżonymi do produkcyjnych: różne stawki VAT, długie nazwy kontrahentów, znaki specjalne w adresach.
**Brak alertu przy nieudanej wysyłce.** Faktura w kolejce z błędem, o której nikt nie wie, to faktura, która nie trafiła do KSeF. Alert musi wychodzić do konkretnej osoby, nie tylko do logu systemowego.
Jeśli budujesz integrację w ramach większego projektu sklepu albo CRM, warto przeczytać też artykuł o tym, od czego zacząć automatyzację procesów biznesowych, bo KSeF jest często jednym z kilku procesów do zautomatyzowania naraz.
Przy projektach, gdzie fakturowanie jest częścią CRM, opisujemy podejście do integracji na stronie wdrożenia CRM. Jeśli rozważasz, czy integrację KSeF wdrożyć jako osobną usługę czy jako część systemu, artykuł o integracji systemów w firmie pokazuje, kiedy middleware ma sens, a kiedy lepiej zbudować jeden spójny system.
Dla firm, które rozważają własny system z modułem fakturowania i KSeF, punkt wyjścia to strona oprogramowania na zamówienie, gdzie opisujemy, jak wygląda wycena i jakie warunki musi spełnić projekt, żeby dedykowany system miał sens finansowy.