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"

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.

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, nipu). Jeśli nawet wejdziesz w posiadanie kodu QR, nie pobierzesz faktury nie mając dostępu do informacji w niej zawartych (zabezpieczenie KSeF).

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 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:

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.