API KSeF
Jak działa interfejs Krajowego Systemu e-Faktur
Ministerstwo Finansów udostępnia interfejs programistyczny, przez który systemy zewnętrzne wysyłają faktury do KSeF i odbierają poświadczenia. Poniżej opisujemy, jak wygląda ten przepływ w praktyce i co w nim najczęściej zaskakuje.
Opisy pochodzą z działającej integracji produkcyjnej, nie z samej dokumentacji. Część rzeczy widać dopiero wtedy, gdy przez system przejdzie kilkaset faktur.
- Uwierzytelnienie
- Otwarcie sesji
- Wysyłka i weryfikacja
- Numer KSeF i UPO
Przepływ, krok po kroku
Uwierzytelnienie
Integracja loguje się do KSeF tokenem albo certyfikatem wystawionym dla danego NIP-u. W odpowiedzi dostaje referencję operacji, którą odpytuje się do momentu potwierdzenia. Uprawnienia są przypisane do kontekstu podmiotu, więc biuro działające za klienta musi mieć je nadane wcześniej.
Otwarcie sesji
Faktury wysyła się w ramach sesji: interaktywnej dla pojedynczych dokumentów albo wsadowej dla paczki. Przy otwarciu sesji generowany jest symetryczny klucz szyfrujący, opakowany kluczem publicznym systemu (RSA-OAEP, SHA-256). Klucz powstaje na sesję i nie nadaje się do ponownego użycia.
Wysyłka i weryfikacja
Dokument musi być zgodny ze schematem FA(3). System weryfikuje go po przyjęciu, a nie w trakcie wysyłki, więc błąd semantyczny wraca osobnym komunikatem. Odrzucenie zwykle dotyczy pojedynczej faktury i nie unieważnia pozostałych z tej samej paczki.
Numer KSeF i UPO
Przyjęta faktura dostaje numer KSeF o stałej budowie i długości 35 znaków. Urzędowe Poświadczenie Odbioru powstaje osobno dla każdej faktury, ale pobiera się je przez sesję, w której dana faktura została złożona. Identyfikator tej sesji trzeba zapisać — bez niego poświadczenia nie da się już pobrać.
Czego nie widać w dokumentacji
Cztery rzeczy, które w naszym przypadku kosztowały realny czas. Wszystkie są do uniknięcia, o ile wie się o nich zawczasu.
UPO to nie jest jedno potwierdzenie na sesję
Najczęstsze nieporozumienie. Sesja wsadowa obejmująca dwieście faktur oznacza dwieście poświadczeń do pobrania i zarchiwizowania, a nie jedno. Referencja sesji dowodzi, że sesja się odbyła; dowodem dla konkretnej faktury jest jej własne UPO. Przy większych wolumenach to ten etap, a nie sama wysyłka, decyduje o czasie przetwarzania.
Nie każdy nabywca ma NIP, a nie chodzi wyłącznie o konsumentów
Schemat FA(3) przewiduje w danych nabywcy oznaczenie braku identyfikatora zamiast numeru, w schemacie zapisywane jako BrakID. Dotyczy ono nie tylko konsumentów: podatnikiem bez NIP jest choćby osoba prowadząca działalność nierejestrowaną, a faktura dla niej podlega obowiązkowi wystawienia w KSeF. Walidacja wymagająca NIP-u od każdego nabywcy odrzuci znaczną część normalnego rejestru sprzedaży.
Klucze sesji generuje się za każdym razem
Materiał szyfrujący powstaje przy otwarciu sesji i nie jest trwałym materiałem uwierzytelniającym, który można zapisać na później. Próba współdzielenia go między sesjami kończy się odrzuceniem po stronie systemu, zwykle na etapie, który nie wskazuje wprost na przyczynę.
Komunikat o błędzie nie zawsze wskazuje miejsce błędu
Część odpowiedzi zwracana jest kilka wywołań po tym, jak powstał problem, a treść potrafi sugerować błąd autoryzacji tam, gdzie chodzi o dane. Jeżeli system twierdzi, że problem leży po stronie danych podmiotu, warto sprawdzić tę hipotezę wprost, zanim zacznie się przeszukiwać własną konfigurację. Bywa, że to najszybsza droga do rozwiązania.
Kiedy własna integracja nie jest potrzebna: jeżeli faktury powstają w systemie, którego i tak nie planujesz rozwijać, a chodzi wyłącznie o doprowadzenie ich do KSeF, to zwykle taniej wychodzi droga przez plik albo bezpłatna Aplikacja Podatnika KSeF udostępniana przez Ministerstwo Finansów. Trzy możliwe drogi zestawiamy w tekście o integracji z KSeF, a przebieg wysyłki hurtowej opisujemy na stronie o hurtowej wysyłce faktur.
Najczęstsze pytania
Czy Ministerstwo Finansów udostępnia gotowe biblioteki?
Tak, w wersjach dla C# oraz Javy, publikowanych w oficjalnym repozytorium resortu razem ze specyfikacją interfejsu. Nie ma oficjalnej biblioteki dla JavaScriptu ani TypeScriptu, więc zespoły pracujące w tym stosie korzystają z rozwiązań społecznościowych albo implementują protokół samodzielnie.
Gdzie znajdę oficjalną dokumentację API KSeF?
Specyfikację interfejsu oraz przykładowe implementacje publikuje Ministerstwo Finansów w swoim repozytorium na GitHubie, razem ze schematem FA(3) i opisem kodów błędów. To jedyne źródło, które warto traktować jako wiążące. Opracowania takie jak to poniżej pomagają zrozumieć przepływ i uniknąć typowych pomyłek, ale przy rozbieżności zawsze rozstrzyga dokumentacja resortu, bo tylko ona nadąża za zmianami protokołu.
Token czy certyfikat?
Tokeny zostają, ale nie bezterminowo. Według zapowiedzi Ministerstwa Finansów z 10 września 2026 r. tokeny wygenerowane do 31 grudnia 2026 r. mają działać do 30 listopada 2027 r., a nowe tokeny zawsze będą miały termin ważności. To zapowiedź, nie jeszcze przepis. Certyfikat KSeF jest drugą, równoległą metodą logowania. FakturaFlow obsługuje obie.
Czym różni się sesja wsadowa od interaktywnej?
Interaktywna służy do wysyłania pojedynczych dokumentów w miarę ich powstawania. Wsadowa przyjmuje paczkę faktur naraz i sprawdza się przy rejestrach liczonych w setkach. Przy większych wolumenach różnica jest odczuwalna nie tyle w samej wysyłce, ile w liczbie wywołań potrzebnych do obsłużenia całości razem z poświadczeniami.
Czy FakturaFlow udostępnia własne API?
Nie. FakturaFlow działa na plikach: wgrywasz zestawienie w CSV, Excelu lub XML, a my odpowiadamy za mapowanie na FA(3), wysyłkę do KSeF i pobranie UPO. Jeżeli potrzebujesz połączenia programistycznego, napisz do nas — chcemy wiedzieć, ilu użytkowników tego szuka, zanim to zbudujemy.
Kiedy własna integracja przestaje się opłacać?
Wtedy, gdy faktury powstają w systemie, którego i tak nie będziemy rozwijać, a jedynym celem integracji jest doprowadzenie ich do KSeF. Utrzymanie własnego połączenia oznacza opiekę nad uwierzytelnianiem, sesjami, szyfrowaniem, poświadczeniami i zmianami po stronie systemu — bezterminowo. Przy jednym rejestrze sprzedaży miesięcznie rzadko się to zwraca.
Rozważamy
Potrzebujesz API zamiast pliku?
Dziś FakturaFlow działa na plikach i własnego API nie udostępniamy. Zastanawiamy się, czy je zbudować, i wolimy najpierw zapytać. Napisz, czego konkretnie potrzebujesz:
- jaki system wystawia u Ciebie faktury,
- ile dokumentów miesięcznie,
- czy chodzi tylko o wysyłkę do KSeF, czy też o generowanie FA(3),
- w jakim języku piszesz integrację.
Odpowiadamy na każdą wiadomość. Jeżeli zgłoszeń nie będzie, API nie powstanie, i to też jest uczciwa odpowiedź.
Masz pytanie o integrację?
Jeżeli budujesz własne połączenie z KSeF i masz problem z uwierzytelnianiem, sesjami albo poświadczeniami, napisz. Odpowiemy konkretnie, nawet jeżeli z tego nic dla nas nie wynika.
Stan prawny na 15 sierpnia 2026 r. Opis interfejsu odzwierciedla stan wdrożenia produkcyjnego z tej daty i nie zastępuje oficjalnej dokumentacji Ministerstwa Finansów ani nie stanowi porady podatkowej w rozumieniu ustawy o doradztwie podatkowym.