Komunikacja z Krajowym Systemem e-Faktur (KSeF)
O tym czym jest KSeF napisano wiele artykułów, nagrano wiele materiałów video. Często niestety nie do końca prawdziwych. Jeśli chcesz zorientować się lepiej czym jest ten system, zacznij od kompendium wiedzy przygotowanego przez Ministerstwo Finansów: https://ksef.podatki.gov.pl/informacje-ogolne-ksef-20
Jeśli chcesz poznać szczegóły funkcjonwania KSeF, najlepszym pomysłem będzie przeczytać 'Podręcznik KSeF' który pobierzesz wchodząc kolejno:
https://ksef.podatki.gov.pl/ => "Pliki do pobrania" [dół strony] => "Podręczniki KSeF"
Szukasz sprawdzonego sposobu na połączenie swojego oprogramowania z Krajowym Systemem e-Faktur? Pomożemy Ci szybko i bezproblemowo zintegrować Twój system z bramką KSeF. Mamy praktyczne doświadczenie w obsłudze API i wiemy, jak uniknąć najczęstszych pułapek technicznych – od poprawnej autoryzacji po wydajne pobieranie dużych zbiorów danych. Napisz do nas.
Spis treści
Wystawianie i odbieranie faktur w systemie KSeF
Odbieranie wystawionych faktur przez firmy i osoby prywatne
Automatyzacja komunikacji z KSeF
Komunikacja z API - autentykacja
Wyzwania i wymagania przy integracji z API KSeF
Specyficzne zachowanie API podczas pobierania faktur
Strefa czasowa która posługuje się KSeF
Wizualizacja faktur - tworzenie PDF z pobranych XML
Podstawowe rodzaje faktur (Definicje)
Klasyfikacja dokumentów sprzedażowych w dobie KSeF
Typy faktur w strukturze logicznej FA(3) - faktury XML które wysyła sie do KSeF
Dokumenty, których nie przesyła się do KSeF
Analityka - dane szczegółowe faktur KSeF
Wystawianie i odbieranie faktur w systemie KSeF
Jeśli nie korzystasz z programu księgowego który obsługuje komunikację z KSeF (popularne na rynku programy zapewniaja taką komunikację) masz dwie możliwości by przesłać fakturę do KSeF lub ją odebrać z KSeF.
Menu web KSeF
Połączenie ze stroną https://ap.ksef.mf.gov.pl i dostęp do menu które umożliwia przeglądanie, odbieranie i wysyłanie faktur. By mieć dostęp do tej strony Twoja firma musi wystąpić o dostęp a po jego nadaniu kolejne osoby są dodawane przez administratora i najczęściej logują się używając profilu zaufanego (inne formy to e-dowód i certyfikat).
Logowanie do tej aplikacji z wykorzystaniem profilu zaufanego jest wyjątkowo uciążliwe. By się tam dostać, musisz dwa razy zalogować się do banku i cztery razy zaakceptować podpisywanie dokumentu w bankowej aplikacji mobilnej. SZEŚĆ interakcji by zalogować sie do aplikacji! Dlatego też jeśli już tam jesteś, trzymaj sesję aktywną by aplikacja Cię nie wylogowała i byś nie musiał(a) logować sie ponownie.
Najwygodniejszą formą jest aplikacja mObywatel - w aplikacji wybierasz menu 'QR code' => Scan QR code', skanujesz kod QR z ekranu komputera a następnie wybierasz 'Share data' w smartfonie. Na ekranie smartfona pojawi się komunikat o potwierdzeniu danych a po stronie PC przeglądarka samoczynnie otworzy okno aplikacji KSeF.
Wystawianie faktur
Masz dwie możliwości przesłania faktury do KSeF. Możesz wczytać fakturę co oznacza przesłanie wcześniej przygotowanego pliku XLM. Możesz też wystawić fakturę. Ta druga opcja daje Ci możliwość skomponowania całej faktury w dość wygodnym menu.
Pobieranie faktur
W aplikacji tej możesz też przeglądać faktury i je pobierać. Pobieranie większej ilości niż jedna niestety jest bardzo niewygodne - możesz co prawda pobrać paczkę faktur ale musisz każdą z faktur zaznaczyć ręcznie a na stronie nie możesz wyświetlić wiecej faktur niż 10. Ta aplikacja jest dostępna dla jednoosobowych działalności gospodarczych i firm. W KSeF masz dostęp do 4 kategorii faktur:
-
Faktury sprzedażowe (Podmiot1): Twoje faktury przychodowe, gdzie występujesz jako sprzedawca.
-
Faktury zakupowe (Podmiot2): Twoje faktury kosztowe, gdzie występujesz jako nabywca.
-
Faktury podmiotu innego (Podmiot3): Dokumenty, w których jesteś stroną trzecią, np. płatnikiem, czynnikiem lub dodatkowym nabywcą.
-
Faktury podmiotu upoważnionego: Dokumenty wystawione w Twoim imieniu przez organy zewnętrzne, np. przez komornika lub przedstawiciela podatkowego.
Z KSeF możesz pobrać fakturę w formacie XML, HTML lub PDF.
E-mikrofirma
Aplikacja e-mikrofirma jest dostępna po zalogowaniu do e-Urzędu Skarbowego i jest przeznaczona wyłącznie dla osób na JDG. Ta druga jest znacznie lepsza dla małych firm, ponieważ działa jak klasyczny program do fakturowania: zapamiętuje listę Twoich klientów oraz usług, a dodatkowo automatycznie przygotowuje pliki JPK_VAT. Narzędzie to jest w pełni zintegrowane z KSeF, co pozwala na bezpośrednie wysyłanie wystawionych faktur do systemu krajowego oraz ich automatyczne odbieranie. Jeśli więc prowadzisz jednoosobową działalność, najwygodniej będzie Ci korzystać z e-mikrofirmy wewnątrz e-Urzędu Skarbowego.
Odbieranie wystawionych faktur przez firmy i osoby prywatne
Jeśli firma wystawia fakturę innej firmie, zostanie ona dostarczona pod właściwy adres dzięki numerowi NIP. NIP jest adresem dostarczenia tak jak w komunikacji SMTP takim adresem jest adres e-mail. Faktury bez NIP lub z błędnym NIP nigdy nie trafią do odbiorcy. To oznacza że niewielki jest sens wystawiania faktur dla osób prywatnych w systemie KSef ...ALE takie wystwienie jest możliwe (choć w ustawie VAT zapisano że takiego obowiązku nie ma). Z KSeF zatem muszą pobierać wszystkie firmy za wyjątkiem podmiotów zagranicznych - ich faktury jednak bezwzględnie muszą być zapisane w KSeF i dostarczone do nich uzgodnioną drogą. Jeśli będą chciały pobrać te faktury z KSeF, mogą to zrobić. Podmioty nie posiadające siedziby na terenie Polski nie będą Ci jednak dostarczać faktur do systemu KSeF.
Kody QR na fakturach
Na każdej fakturze papierowej powinien znaleźć się kod QR który prowadzi do strony KSeF umożliwiającej weryfikację faktury i jej pobranie: https://qr.ksef.mf.gov.pl - w kodzie zawarty jest unikalny link (skomponowany z hash xml faktury, daty wystawienia, NIP'u). Jeśli nawet wejdziesz w posiadanie kodu QR, nie pobierzesz faktury nie mając dostępu do informacji w niej zawartych (zabezpieczenie KSeF) - musisz znać kwotę faktury, nip odbiorcy i numer faktury:
Klikając na pobierz przechodzisz do następnej strony gdzie możesz wybrać w jakim formacie chcesz pobrać fakturę z KSeF; XML lub PDF.
Automatyzacja komunikacji z KSeF
KSeF oferuje jednak bardzo proste menu i ograniczoną listę funkcji w stosunku do potrzeb nawet przeciętnej firmy. Jeśli chcesz zautomatyzować komunikację z KSeF, musisz wykorzystać API które oferuje ten system dostępne pod adresem https://api.ksef.mf.gov.pl
API jest wykorzystywane przez systemy ERP i programy księgowe - dzięki temu komunikacja z KSeF jest dla Ciebie niewidoczna. Jeśli nie masz takiego programu, jest to Twoja bramka do atutomatyzacji komunikacji z tym systemem. Oto lista najważniejszych funkcji, do których możesz użyć API KSeF:
Operacje na fakturach
-
Automatyczne wystawianie i wysyłka: Przesyłanie faktur ustrukturyzowanych (XML) bezpośrednio z Twojego systemu ERP/fakturującego.
-
Odbieranie faktur kosztowych: Automatyczne pobieranie dokumentów od dostawców prosto do Twojej ewidencji księgowej (bez e-maili i plików PDF).
-
Pobieranie UPO: Uzyskiwanie oficjalnego Urzędowego Poświadczenia Odbioru dla każdej wysłanej faktury.
-
Podgląd faktur (Wizualizacja): Generowanie czytelnych plików PDF lub HTML na podstawie danych XML z systemu.
-
Wysyłka wsadowa (Batch): Przesyłanie dużych paczek faktur jednocześnie, co jest kluczowe dla firm o dużej skali sprzedaży.
Zarządzanie sesjami i bezpieczeństwem
-
Uwierzytelnianie: Logowanie do systemu przy użyciu tokenów dostępowych, podpisów kwalifikowanych lub pieczęci elektronicznej.
-
Generowanie tokenów: Tworzenie specjalnych kluczy dostępu, które pozwalają aplikacji na działanie bez Twojej ciągłej obecności przy logowaniu.
-
Szyfrowanie: Zapewnienie bezpieczeństwa danych poprzez szyfrowanie faktur lokalnie jeszcze przed ich wysyłką.
Zarządzanie uprawnieniami
-
Nadawanie dostępów: Elektroniczne przyznawanie uprawnień do wystawiania lub przeglądania faktur dla pracowników lub biura rachunkowego.
-
Weryfikacja kontrahentów: Sprawdzanie, czy dany podmiot jest uprawniony do korzystania z KSeF i czy dane na fakturze są poprawne technicznie przed wysyłką.
Funkcje zaawansowane
Obsługa załączników: Wysyłanie faktur z dodatkową dokumentacją (np. umowami), co będzie nowością w wersji KSeF 2.0.
-
Tryb offline (QR kody): Generowanie kodów QR i danych niezbędnych do wystawiania faktur w przypadku braku internetu lub awarii systemu.
-
Zapytania o status: Sprawdzanie w czasie rzeczywistym, na jakim etapie przetwarzania jest wysłany przez Ciebie dokument.
Dzięki API stworzyć możesz np. system powiadamiania o nadchodzących fakturach wg. róznych kryteriów. Te powiadomienia mogą mieć różną formę, docierać do Ciebie w różny sposób.
Komunikacja z API - autentykacja
Upoważnienia do komunikacji z API mają dwie formy; token oraz certyfikat + klucz. Token wydaje się być łatwiejszą formą ale w rzeczywistości jest zupełnie odwrotnie - na dzień pisania tego artykułu komunikacja z użyciem token nie była możliwa.
Zarówno token jak i certyfikat generowane są przez administratora panelu firmowego ksef - w aplikacji web. Token można pobrać tylko w momencie jego generowania. Certyfikat może być pobrany wielokrotnie. Zarówno dla tokena jak i certyfikatu niemożliwy jest podgląd nadanych uprawnień; certyfikat ma pełne uprawnienia podczas gdy token można nadać do: wystawianie faktur, przeglądanie faktur, przeglądanie uprawnień, zarządzanie uprawnieniami, zarządzanie jednostkami podrzędnymi, wykonywanie operacji egzekucyjnych.
Wyzwania i wymagania przy integracji z API KSeF
Wbrew pozorom, by korzystać z API KSeF nie musisz być programistą. Wystarczy że masz jakieś pojęcie o 'informatyce'. Jeśli np. potrafisz napisać prosty program w Python lub, jeszcze lepiej, nie obce Ci są narzędzia klasy ETL - jesteś w domu. Opis wszystkich dostępnych metod API znajdziesz pod adresem https://api.ksef.mf.gov.pl/docs/v2/index.html [nowe adresy po uruchomieniu wersji produkcyjnej KSef: https://www.gov.pl/web/finanse/przypominamy-o-zmianie-adresow-srodowisk-ksef--komunikat-dla-integratorow].
Uzyskanie tokenu dostępowego
Do każdej operacji pobierania lub wysyłania danych potrzebować będziesz tokenu dostępowego. Aby go uzyskać musisz kolejno wykonać metody API [kiedy używasz certyfikatu i klucza]:
- auth/challenge - generowanie unikalnego challenge wymaganego w kolejnym kroku operacji uwierzytelnienia.
- auth/xades-signature - rozpoczęcie operacji uwierzytelniania za pomocą dokumentu XML podpisanego podpisem elektronicznym XAdES.
- auth/token/redeem - pobranie pary tokenów (access token i refresh token) wygenerowanych w ramach pozytywnie zakończonego procesu uwierzytelniania. tokeny można pobrać tylko raz.
Pobieranie faktur z API
Z KSeF, wykorzystując API można pobrać faktury TYLKO w formacie XML. Mamy dostępne dwie metody API które umożliwiają transfer faktur z KSeF:
- invoices/ksef/{ksefNumber} - Zwraca fakturę o podanym numerze KSeF. Możesz pobrać tylko jedną fakturę [Możesz pobrać tylko 16 faktur na minutę, maksymalnie 64 na godzinę]
- invoices/exports - Rozpoczyna asynchroniczny proces wyszukiwania faktur w systemie KSeF na podstawie przekazanych filtrów oraz przygotowania ich w formie zaszyfrowanej paczki. Maksymalny rozmiar paczki; 10 tyś sztuk faktur [tylko maks. 20 zapytań w ciągu godziny]
- invoices/exports/{referenceNumber} - Pobranie statusu eksportu paczki faktur. Paczka faktur jest dzielona na części o maksymalnym rozmiarze 50 MB. Każda część jest zaszyfrowana algorytmem AES-256-CBC z dopełnieniem PKCS#7, przy użyciu klucza symetrycznego przekazanego podczas inicjowania eksportu.
Specyficzne zachowanie API podczas pobierania faktur
{"exception":{"exceptionDetailList":[{"exceptionCode":21405,"exceptionDescription":"B\u0142\u0105d
walidacji danych wej\u015Bciowych.","details":["You cannot retrieve invoices
starting from number 10 000 or higher. Please narrow your
filters."]}],"serviceCode":"00-1f0f7a58026393d4ce7b65b9de242dd6-76eeb2dd925ab0d2-00","timestamp":"2026-02-11T15:15:55.1230935Z"}}
- System otwiera wszystkie partycje/paczki faktur z tych dwóch dni (zakres N partycji).
- W tych dwóch dniach wpłynęło np. 1 200 000 faktur wszystkich podatników (realistyczna liczba w KSeF w 2026 r.).
- Faktury są posortowane np. po AcquisitionTimestamp (kolejność nadania numeru KSeF).
- System nie filtruje od razu po NIP-ie – zaczyna sekwencyjne skanowanie całej listy w partycjach/paczkach.
- Dla każdej faktury: → licznik zeskanowanych rekordów źródłowych rośnie o 1, → sprawdza NIP → jeśli nie pasuje → odrzuca i idzie dalej, → jeśli pasuje → dodaje do wyników (lub pomija, jeśli jest w offsetcie).
- Gdy licznik zeskanowanych rekordów źródłowych (przed filtrem NIP) osiągnie 10 001 → system przerywa i zwraca błąd „starting from number 10000 or higher”, niezależnie od tego, ile faktur już znalazł/pominął.
Ta „faktura 10 001” (lub „starting from number 10,000 or higher”) nie odnosi się do żadnego konkretnego numeru faktury (ani Twojego własnego numeru FV, ani numeru KSeF nadanego przez system). To jest wewnętrzny numer pozycji / offset w posortowanej liście faktur, którą system KSeF musi najpierw „zobaczyć / załadować / przeskanować” przed zastosowaniem filtra po NIP-ie.
Rozwiązanie? Jak możesz sie domyślić; pobieranie mniejszych zakresów czasowych i 'sklejanie' wyników po swojej stronie. Zderzysz się też z partycjami/paczkami podczas korzystania z metody invoices/exports. Dość szybko zauważysz że mimo podania precyzyjnego zakresu dat/czasu - możesz otrzymać faktury wcześniejsze i ewentualne późniejsze. Dlaczego? W /invoices/exports system zwraca faktury z gotowych paczek faktur, „najbardziej pasujące” do zapytania, dlatego mogą pojawić się faktury spoza podanego zakresu dat. Jak mówi MF: "Jest to normalne zachowanie KSeF i nie jest błędem API. Zalecamy więc pobierać faktury w mniejszych porcjach i zawsze dodatkowo filtrować wyniki po NIP oraz dacie po stronie aplikacji, aby ominąć problem ograniczeń systemu."
Strefa czasowa która posługuje się KSeF
KSeF używa czasu z „Z” – to jest UTC (Coordinated Universal Time). Krótko i prosto:
- „Z” w dacie typu 2026-03-05T12:34:56Z oznacza Zulu time (kod wojskowy/marynarki). Z to tylko marker informujący o czasie UTC (a raczej 'Zulu')
- A Zulu time = UTC = czas uniwersalny / Greenwich Mean Time (GMT) bez przesunięć letnich
- Greenwich → to historyczna nazwa, bo punkt zerowy (0°) przebiega przez obserwatorium w Greenwich (Londyn)
Budując oprogramowanie pamiętaj zatem o odpowiednim przesunięciu czasu letniego po swojej stronie jak i o konwersji czasu lokalnego na UTC.
Wizualizacja faktur - tworzenie PDF z pobranych XML
Integralność faktury nie polega na tym że faktura musi mieć ten sam wygląd który jest w KSeF (dla wielu nie jest to oczywiste) - integralna musi być informacja zawarta na fakturze. Zatem możesz przygotować swoją własną wizualizację danych z pobranych XML chociaż Ministerstwo Finansów publikuje styl XSL do wizualizacji faktury. W ten sposób uzyskać możesz fakture w formacie HTML. Istnieje wiele bibliotek i gotowych programów które wykonują taką prace. Jeśli korzystasz z Python moze to być np saxonche czy lxml.
Jeśli masz już HML, konwersja do PDF jest następnym krotkiem. Polecanym narzędziem może być weasyprint który jest uznanym standardem. Pamiętaj o zawarciu kodu QR na fakturze. Kod QR zawiera link do interfejsu KSeF który służy weryfikacji faktury i jej pobraniu. Czytaj więcej jak tworzy się linki do umieszczenia w kodach QR KSeF: https://github.com/CIRFMF/ksef-docs/blob/main/kody-qr.md
Pewnym wyzwaniem przy tworzeniu wizualizacji faktury KSeF jest to, że w KSeF mogą być różne typów faktur.
Podstawowe rodzaje faktur (Definicje)
Klasyfikacja dokumentów sprzedażowych w dobie KSeF
KSeF rozróżnia trzy fundamentalne formy faktur:
- Faktura papierowa - Tradycyjny wydruk fizyczny. Od lutego 2026 r. będzie dopuszczalna tylko w ściśle określonych przypadkach (np. dla małych firm w okresie przejściowym lub w relacjach z konsumentami/B2C)
- Faktura elektroniczna – Wystawiona i otrzymana w dowolnym formacie elektronicznym, np. PDF.
- Faktura ustrukturyzowana (e-Faktura) – Wystawiona przy użyciu KSeF w formacie XML, z przydzielonym numerem KSeF.
Typy faktur w strukturze logicznej FA(3) - faktury XML które wysyła sie do KSeF
W rozdziale 2 podręcznika KSeF opisano konkretne rodzaje dokumentów, które podatnicy wystawiają w ramach procesów biznesowych:
Faktura zaliczkowa (ZAL) – dokumentująca otrzymanie całości lub części zapłaty przed dokonaniem czynności.
Faktura rozliczająca (ROZ) – wystawiana po wydaniu towaru lub wykonaniu usługi, rozliczająca wcześniej otrzymane zaliczki.
Faktura końcowa „zerowa” – specyficzny rodzaj faktury rozliczającej, gdy zaliczki pokryły 100% należności.
Faktura korygująca (KOR, KOR_ZAL, KOR_ROZ) – służąca do poprawiania błędów lub uwzględniania zwrotów i rabatów . Podręcznik opisuje też faktury korygujące zbiorcze.
Faktura VAT marża – dla procedur dotyczących biur podróży, towarów używanych, dzieł sztuki czy antyków.
Faktura uproszczona (UPR) – dla transakcji o wartości do 450 zł lub 100 euro.
Faktury dokumentujące WDT i eksport towarów – ze specyficznymi oznaczeniami stawek (np. „0 WDT”, „0 EX”).
Dokumenty, których nie przesyła się do KSeF
Podręcznik wyraźnie wskazuje, że do systemu nie trafiają:
Faktury pro forma
Noty obciążeniowe i uznaniowe
Noty korygujące (zostają uchylone od 1 lutego 2026 r.)
Faktury wewnętrzne
Rachunki
W terminologii dokumentów KSeF funkcjonują jeszcze „potwierdzenia transakcji”, które nie są fakturami, ale dobrowolnymi dokumentami wydawanymi nabywcy, zanim faktury otrzymają numery KSeF.
Analityka - dane szczegółowe faktur KSeF
Endpointy KSeF nie dają dostępu do wszystkich danych które znajdują się na fakturach. Uzyskanie tych danych jest jednak możliwe - w końcu faktury mają ustrukturyzowaną formę i odczyt tych danych nie powoduje większych problemów. Jednak z racji specyficznej reakcji API KSeF na filtry dat, odpowienia kultura przetwarzania danych musi być zastosowana po stronie pobierającego dane by uniknąć np. duplikatów.
Po kilku miesiącach funkcjonowania KSeF można powiedzieć że API jest raczej stabilne, z dość szybkim czasem reakcji. Jeśli pobierasz większe ilości danych do analityki, wykonuj te zlecenia raczej w godzinach nocnych - krótsze czasy odpowiedzi, przygotowania danych.