API KSeF
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.
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.
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.
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.
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ć.
Cztery rzeczy, które w naszym przypadku kosztowały realny czas. Wszystkie są do uniknięcia, o ile wie się o nich zawczasu.
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.
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.
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ę.
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.
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.
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.
Dotychczasowy kierunek zakładał, że token jest rozwiązaniem przejściowym, a po 31 grudnia 2026 r. jego rolę przejmie certyfikat KSeF. Na konsultacjach z 9 czerwca 2026 r. pojawiła się propozycja utrzymania tokenów również po tej dacie. To jednak wciąż propozycja, a nie przepis, więc rozsądnie jest przygotować się na certyfikaty i nie rezygnować z tokenów, dopóki nic się nie zmieni.
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.
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.
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.
Jeżeli budujesz własne połączenie z KSeF i masz problem z uwierzytelnianiu, sesji albo poświadczeniach, 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.