Integracja z KSeF przez API: jak podłączyć własny system
Integracja z KSeF przez API 2.0 to pięć kroków: uprawnienia (firma bez pieczęci kwalifikowanej zaczyna od zgłoszenia ZAW-FA), logowanie podpisem XAdES albo tokenem KSeF, zaszyfrowana sesja z wysyłką faktury w strukturze FA(3), odbiór UPO z numerem KSeF i synchronizacja faktur kosztowych do własnej bazy. Ministerstwo Finansów publikuje do tego specyfikację OpenAPI, środowiska TEST i DEMO oraz biblioteki w C# i Javie. Własna integracja ma sens, gdy faktury powstają automatycznie w Twojej aplikacji; przy kilkunastu fakturach miesięcznie wystarczy bezpłatna aplikacja Ministerstwa albo program księgowy.
- Obowiązek wystawiania faktur w KSeF objął 1 lutego 2026 r. podatników, u których sprzedaż z podatkiem przekroczyła w 2024 r. 200 mln zł, a 1 kwietnia 2026 r. pozostałych. Wyłączenie dla faktur o łącznej wartości do 10 000 zł z podatkiem w miesiącu działa do 31 grudnia 2026 r.
- Dokumentacja limitów API KSeF podaje sklep internetowy jako przykład dla sesji wsadowej: osobny proces zbiera wystawione faktury i cyklicznie, na przykład co 5 minut, wysyła je paczką.
- Faktura wystawiona w KSeF w trybie online i przekazana nabywcy poza systemem, na przykład jako PDF w mailu, musi mieć kod QR z numerem KSeF umieszczonym bezpośrednio pod nim.
- Dla nabywcy, który odbiera fakturę w KSeF, datą otrzymania jest data nadania numeru KSeF, a nie dzień, w którym jego program ją pobrał.
Terminy i kary: od kiedy obowiązuje e-faktura
Krajowy System e-Faktur nie jest kolejnym formatem pliku. Zmienia miejsce, w którym faktura powstaje, i moment, w którym uznaje się ją za wystawioną. Terminy, limity i nazwy endpointów w tym przewodniku podaję za stronami Ministerstwa Finansów na ksef.podatki.gov.pl i za jego przewodnikiem dla integratorów; pełna lista jest w źródłach na końcu strony.
Dotąd fakturę tworzył Twój program, a dostarczenie jej klientowi było Twoją sprawą. W KSeF dokument w strukturze logicznej FA(3) trafia najpierw do systemu Ministerstwa Finansów, tam dostaje numer KSeF i dopiero wtedy funkcjonuje w obrocie. Nabywca będący czynnym podatnikiem pobiera go z systemu, więc wysyłka mailem staje się co najwyżej uprzejmością.
Obowiązek wystawiania wszedł dwuetapowo: od 1 lutego 2026 r. objął podatników, u których wartość sprzedaży wraz z kwotą podatku przekroczyła w 2024 r. 200 mln zł, a od 1 kwietnia 2026 r. wszystkich pozostałych. Osobno ruszył obowiązek odbierania: od 1 lutego 2026 r. każdy podatnik musi umieć przyjąć fakturę przez KSeF, nawet jeśli sam nie musiał jeszcze w nim wystawiać.
Rok 2026 jest przejściowy i nie nakłada się w nim kar za błędy związane z korzystaniem z KSeF. 16 września 2026 r. Ministerstwo Finansów zapowiedziało wydłużenie tego odroczenia do 31 grudnia 2027 r. Wymaga to zmiany ustawy, więc do jej uchwalenia obowiązuje dotychczasowy termin. Odroczenie dotyczy kar, nie obowiązku: od 1 stycznia 2027 r. wchodzą dwie rzeczy naraz, obowiązek dla grupy korzystającej dotąd z wyłączenia dla drobnej sprzedaży oraz obowiązek podawania numeru KSeF albo identyfikatora zbiorczego w komunikacie przelewu, także w podzielonej płatności.
Podstawą prawną jest ustawa z 5 sierpnia 2025 r. (Dz. U. z 2025 r. poz. 1203). Harmonogram przesuwano już kilkakrotnie, więc przed ułożeniem planu potwierdź terminy na ksef.podatki.gov.pl.
Trzy drogi i ich koszt: aplikacja MF, program księgowy, własna integracja
Nie każda firma potrzebuje własnego połączenia z systemem. Wybór sprowadza się do dwóch pytań: gdzie powstaje faktura i ile ich jest w miesiącu.
Pierwsza droga to bezpłatne narzędzia Ministerstwa Finansów: Aplikacja Podatnika KSeF, aplikacja mobilna dostępna od 1 lutego 2026 r. oraz e-mikrofirma w e-Urzędzie Skarbowym. Wystarczą firmie, która wystawia kilkanaście faktur miesięcznie i nie ma własnego systemu sprzedaży.
Druga droga to program księgowy z integracją po stronie dostawcy. Wystawiasz dokument jak dotąd, a dostawca odpowiada za wysyłkę, odbiór UPO i aktualizacje pod zmiany schematu. Przy typowej sprzedaży to rozsądny domyślny wybór. Granicą jest moment, w którym faktura musi powstać automatycznie po zdarzeniu w Twoim systemie.
Trzecia droga to własna integracja przez API KSeF 2.0. Ministerstwo publikuje specyfikację OpenAPI 3.0.4 z interaktywną dokumentacją, udostępnia środowisko testowe TEST i przedprodukcyjne DEMO oraz utrzymuje publiczne repozytoria z przewodnikiem dla integratorów i bibliotekami klienckimi w C# i Javie.
Własna integracja to zły pomysł, gdy faktur jest kilkanaście miesięcznie, gdy program księgowy już wysyła je do KSeF albo gdy nikt w firmie nie będzie pilnował zmian API i ważności certyfikatów. Zła przesłanka brzmi też „napiszemy sobie sami, bo to tylko wysłanie XML-a”: samo wysłanie to kilka wywołań API, a pracochłonne jest to, co dzieje się, gdy system odrzuci dokument o drugiej w nocy.
| Kryterium | Aplikacja Podatnika KSeF | Program księgowy z integracją | Własna integracja przez API |
|---|---|---|---|
| Koszt | Narzędzia Ministerstwa Finansów są bezpłatne. Płacisz czasem osoby wpisującej dane. | Mieści się w abonamencie programu albo w dopłacie do modułu. | Jednorazowe wdrożenie plus opieka nad zmianami API. Największa pozycja to praca, nie licencje. |
| Czas wdrożenia | Godziny: uprawnienia i pierwsza faktura tego samego dnia. | Od kilku dni do kilku tygodni, głównie na uprawnienia i testy. | Tygodnie. Wysyłka powstaje szybko, dłużej trwa obsługa błędów i trybów offline. |
| Kto to utrzymuje | Ministerstwo Finansów. Po Twojej stronie zostaje wpisywanie danych. | Dostawca oprogramowania. Zmiany schematu i API są jego problemem. | Ty albo wykonawca. Każda nowa wersja API wraca jako zadanie. |
| Automatyzacja | Brak. Każdy dokument powstaje ręcznie. | Wysoka w granicach tego, co przewidział dostawca. | Pełna. Faktura powstaje z dowolnego zdarzenia i wraca z numerem KSeF. |
| Dopasowanie do procesu | Żadne. To Ty dopasowujesz się do formularza. | Dobre przy typowej sprzedaży, słabsze przy rozliczeniach okresowych. | Takie, jakie zaprojektujesz, w zamian za odpowiedzialność za dokument. |
| Kiedy wybrać | Kilkanaście faktur miesięcznie, bez własnego systemu sprzedaży. | Sprzedaż w standardzie, księgowość już w tym programie. | Faktura ma powstawać automatycznie po zdarzeniu w Twojej aplikacji. |
Jak działa API KSeF 2.0: wymagania, logowanie, sesja, UPO i tryby offline
Integracja to pięć kroków w stałej kolejności, a przewodnik Ministerstwa dla integratorów opisuje każdy z nich osobno. Pominięcie któregokolwiek kończy się dokumentem, którego formalnie nie ma.
Cała sekwencja wywołań przy jednej fakturze wysłanej interaktywnie wygląda więc tak: POST /auth/challenge, POST /auth/xades-signature albo POST /auth/ksef-token, odpytywanie GET /auth/{referenceNumber} do skutku, POST /auth/token/redeem, POST /sessions/online, POST /sessions/online/{referenceNumber}/invoices, sprawdzenie statusu faktury, POST /sessions/online/{referenceNumber}/close i pobranie UPO sesji.
Środowiska mają osobne adresy: produkcja api.ksef.mf.gov.pl, TEST api-test.ksef.mf.gov.pl i DEMO api-demo.ksef.mf.gov.pl, a każde publikuje własną specyfikację OpenAPI pod ścieżką /docs/v2. Faktury wysłane na TEST i DEMO nie mają skutków prawnych i są po pewnym czasie usuwane.
Osobny temat to sytuacje, w których wysyłka w czasie rzeczywistym jest niemożliwa. Tryb offline24 może zastosować każdy podatnik bez ograniczeń: fakturę wystawia się poza systemem i przesyła niezwłocznie, najpóźniej w następnym dniu roboczym, a datą wystawienia pozostaje ta z pola P_1. Dokument udostępniony nabywcy przed wysyłką musi mieć dwa kody QR, oznaczone OFFLINE i CERTYFIKAT; drugi wymaga certyfikatu typu drugiego.
Przy niedostępności ogłoszonej w BIP Ministerstwa, na przykład z powodu prac serwisowych, fakturę dosyła się najpóźniej w następnym dniu roboczym po zakończeniu przerwy. Tryb awaryjny działa, gdy Ministerstwo ogłosi awarię w BIP i w oprogramowaniu interfejsowym; wtedy na dosłanie jest 7 dni roboczych od jej zakończenia, a kolejna awaria w tym okresie liczy termin od nowa. Po ogłoszeniu awarii całkowitej faktur nie trzeba dosyłać.
Dochodzi jeszcze warstwa danych. Od 1 lutego 2026 r. obowiązuje struktura FA(3), z węzłem załącznika i szerszym polem opisu pozycji. Załącznik jest dobrowolny, wyłącznie w formacie XML, faktura z załącznikiem może mieć najwyżej 3 MB, a funkcję trzeba najpierw zgłosić w e-Urzędzie Skarbowym. Przed kodowaniem sprawdź aktualną specyfikację OpenAPI i dziennik zmian.
- Uprawnienia przed kodemWedług pytań i odpowiedzi Ministerstwa firma bez pieczęci kwalifikowanej zaczyna od zgłoszenia ZAW-FA, w którym wskazuje osobę uprawnioną do KSeF; ta osoba nadaje dalsze uprawnienia już elektronicznie. Uprawnienia mają osoby fizyczne, identyfikowane numerem PESEL, NIP albo odciskiem certyfikatu, oraz podmioty, a Twój system działa na uprawnieniach tego, czyim tokenem lub certyfikatem się loguje. Tokeny z wersji 1.0 w API 2.0 nie działają.
- Logowanie w APIWedług przewodnika Ministerstwa Twój system pobiera wyzwanie (POST /auth/challenge, ważne 10 minut) i odsyła je podpisane w formacie XAdES: podpisem albo pieczęcią kwalifikowaną, Profilem Zaufanym lub certyfikatem KSeF. Drugą drogą jest token zaszyfrowany kluczem publicznym Ministerstwa (RSA-OAEP). Po sprawdzeniu statusu odbiera accessToken, ważny kilkanaście minut, i refreshToken, ważny do 7 dni (POST /auth/token/redeem).
- Certyfikat KSeF w dwóch typachWedług strony Ministerstwa o certyfikatach logowanie certyfikatem działa od 1 lutego 2026 r., a certyfikat jest ważny najwyżej 2 lata od wytworzenia albo od wskazanej daty początku ważności. Typ pierwszy służy do logowania, typ drugi do kodu QR na fakturach offline. Firma z pieczęcią kwalifikowaną może pobrać certyfikat na sam podmiot, niezwiązany z konkretnym pracownikiem.
- Sesja i wysyłkaDla każdej sesji generujesz klucz AES-256, szyfrujesz nim faktury, a sam klucz szyfrujesz kluczem publicznym Ministerstwa. Sesję interaktywną otwiera POST /sessions/online, a faktury wysyła się w niej pojedynczo przez POST /sessions/online/{referenceNumber}/invoices; według przewodnika sesja trwa najwyżej 12 godzin. Sesja wsadowa przyjmuje paczkę. Dokumentacja limitów zaleca tryb wsadowy, gdy w jednym oknie wysyłasz więcej dokumentów, i podaje przykład sklepu, który co 5 minut wysyła zebrane faktury paczką. Interaktywna służy sytuacjom, w których numer KSeF jest potrzebny od razu: sprzedaży w punkcie albo pojedynczej korekcie. Weryfikacja jest asynchroniczna, więc kod czekający na numer w jednym żądaniu HTTP utknie.
- UPO i numer KSeFZamknięcie sesji (POST /sessions/online/{referenceNumber}/close) uruchamia generowanie zbiorczego Urzędowego Poświadczenia Odbioru. UPO zawiera datę przyjęcia dokumentu do systemu teleinformatycznego Ministerstwa Finansów i numer KSeF. Numer identyfikuje fakturę w systemie, nie zastępuje Twojej numeracji i nie jest elementem pliku XML. Zapisz go przy zamówieniu.
Plan wdrożenia krok po kroku: od uprawnień do produkcji
Kolejność jest stała: najpierw ZAW-FA i uprawnienia, potem certyfikaty i porządki w danych, na końcu kod i testy na środowiskach TEST i DEMO.
Daty w tym planie potwierdź na ksef.podatki.gov.pl, bo pojedyncze terminy bywały przesuwane już po ogłoszeniu.
- Ustal swoją datę i swój zakresSprawdź, do której grupy należysz i czy korzystasz jeszcze z wyłączenia do 10 000 zł miesięcznie, które kończy się 31 grudnia 2026 r. Wypisz typy dokumentów, jakie wystawiasz, i zaznacz objęte wyłączeniami.
- Uporządkuj uprawnieniaFirma bez pieczęci kwalifikowanej zaczyna od zgłoszenia ZAW-FA, potem nadaje uprawnienia osobom i biuru rachunkowemu. To krok administracyjny, zrób go przed programowaniem.
- Wygeneruj certyfikaty i zaplanuj wymianęPobierz certyfikat typu pierwszego do logowania i typu drugiego, jeśli będziesz oznaczać faktury kodem QR offline. Od razu wpisz do kalendarza datę wygaśnięcia, licząc najwyżej 2 lata.
- Przejrzyj dane, zanim dotkniesz koduZrób raport z własnej bazy: kontrahenci bez poprawnego NIP-u, adresy bez kodu kraju, nietypowe stawki VAT. Każdy taki przypadek wróci jako odrzucenie.
- Zbuduj wysyłkę na środowisku testowymPracuj na środowiskach TEST i DEMO, korzystając ze specyfikacji OpenAPI i bibliotek Ministerstwa Finansów. Najpierw pojedyncza faktura, potem korekta, potem sesja wsadowa.
- Dodaj obsługę błędów i trybów offlineZaprojektuj kolejkę z ponawianiem, powiadomienie o odrzuceniu i ścieżkę na wypadek ogłoszonej awarii, z terminem 7 dni roboczych od jej zakończenia. Ten etap trwa dłużej niż sama wysyłka.
- Przećwicz pełen miesiąc z księgowościąPrzepuść przez nowy proces dokumenty z jednego miesiąca: sprzedaż firmową, konsumencką, korekty i dokumenty wyłączone. Uzgodnienie wyniku z księgowością wychwyci rzeczy, których nie złapią testy jednostkowe.
- Przygotuj się na przelewy z numerem KSeFWedług strony Ministerstwa o numerze KSeF od 1 stycznia 2027 r. numer albo identyfikator zbiorczy trafia do komunikatu przelewu, także w podzielonej płatności. Identyfikator ma 35 znaków i agreguje co najmniej dwie faktury jednego sprzedawcy, więc zaplanuj miejsce na oba w eksportach do banku.
Cenniki i przepisy się zmieniają. Linki do źródeł są na dole strony.
Odbieranie faktur kosztowych i limity pobierania
Faktury kosztowe pobiera się do własnej bazy, a nie otwiera z systemu za każdym razem, gdy ktoś chce je zobaczyć. Dokumentacja limitów mówi o tym wprost.
Według dokumentacji Ministerstwa Finansów wyszukiwanie, filtrowanie i raportowanie mają działać na lokalnej bazie, zsynchronizowanej wcześniej z systemem. Wywoływanie API za każdym razem, gdy użytkownik otwiera fakturę albo pobiera jej plik XML, jest tam wprost wymienione jako niezalecany wzorzec, który może skończyć się blokadą dostępu do API.
Zalecanym mechanizmem jest przyrostowy eksport paczek w przylegających do siebie oknach czasowych, opartych na znaczniku kompletności danych (High Water Mark), osobno dla każdej roli, w jakiej Twoja firma występuje na fakturze: sprzedawcy, nabywcy, podmiotu trzeciego albo upoważnionego. Do synchronizacji służy endpoint /invoices/query/metadata, a przewodnik podaje limit 20 eksportów na godzinę. Pobieranie pojedynczych dokumentów po numerze (/invoices/ksef/{ksefNumber}) dokumentacja dopuszcza tylko przy małym wolumenie.
Cykliczna synchronizacja nie powinna ruszać częściej niż co 15 minut dla każdej roli. Przy małym wolumenie dokumentacja zaleca pobieranie na żądanie użytkownika, uzupełnione cyklem na przykład raz na dobę w nocy; w godzinach 20:00–6:00 limity pobierania mają być wyższe niż w dzień, a konkretne wartości Ministerstwo dopiero dostraja.
Dla nabywcy, który odbiera fakturę w KSeF, datą otrzymania jest data nadania numeru KSeF, a nie dzień, w którym jego program ją pobrał. Opóźniona synchronizacja nie zmienia więc daty otrzymania, zmienia tylko to, kiedy dowie się o fakturze księgowość. Limity są dynamiczne, więc aktualne wartości sprawdź w dokumentacji limitów.
Faktura przekazana poza systemem: kod QR i numer KSeF na PDF-ie
Według strony Ministerstwa o kodach weryfikujących każda wizualizacja e-faktury, którą przekazujesz poza systemem, na przykład PDF w mailu, musi mieć kod QR. Tę zmianę zobaczą Twoi klienci.
E-fakturę przekazujesz nabywcy poza systemem w sytuacjach z art. 106gb ust. 4 ustawy o VAT, między innymi gdy kupuje konsument, podmiot bez numeru NIP albo firma bez siedziby w Polsce. Wtedy, tak jak przy każdym innym użyciu faktury poza systemem, dokument trzeba oznaczyć kodem weryfikującym QR. Jeśli kodu nie da się nanieść na sam dokument, na przykład gdy odbiorca dostaje plik XML, przesyłasz mu razem z fakturą osobny link albo obraz kodu, z tym samym oznaczeniem.
Na fakturze wystawionej w trybie online jest jeden kod QR, a bezpośrednio pod nim numer KSeF. Po zeskanowaniu kodu widać podstawowe dane identyfikujące fakturę i informację, czy jest w systemie, a cały dokument można pobrać po podaniu dodatkowych danych dostępowych. Faktura wystawiona w trybie offline i udostępniona nabywcy przed wysłaniem do systemu ma dwa kody: pierwszy z napisem OFFLINE, drugi z napisem CERTYFIKAT. Gdy faktura offline trafi do systemu i dostanie numer, na jej wizualizacji wystarczy już jeden kod, z numerem KSeF.
Przy własnej integracji kod generuje Twoja aplikacja, lokalnie. Zawiera adres wskazany w dokumentacji, datę wystawienia z pola P_1, NIP sprzedawcy i skrót SHA-256 pliku XML faktury, a sam obraz ma spełniać normę ISO/IEC 18004:2024. W sklepie oznacza to zmianę szablonu PDF i kolejności kroków: kod z numerem KSeF powstaje dopiero po nadaniu numeru, więc wizualizację faktury online generujesz na końcu kolejki, po zapisaniu numeru i UPO.
Jeśli konsument albo nabywca bez NIP-u ma odebrać fakturę w systemie, musisz zapewnić mu do niej dostęp: podać kod weryfikujący i dane pozwalające zidentyfikować fakturę w systemie. Zasady potwierdź na stronie o kodach weryfikujących na ksef.podatki.gov.pl.
Ryzyka i błędy wdrożeniowe: jak ich uniknąć
Każdy z tych błędów ma konkretne zabezpieczenie: widoczny status przy zamówieniu, klucz chroniący przed duplikatem, obsługę nagłówka Retry-After albo alert o wygasającym certyfikacie.
Interfejs zmienia się częściej niż przepisy, więc terminy i zasady limitów, środowisk oraz korekty technicznej sprawdzaj w dzienniku zmian.
- Cicha porażka wysyłkiSystem wysyła dokument, dostaje błąd i zapisuje go tylko w logu, a o braku faktury dowiadujesz się przy zamknięciu miesiąca. Każde odrzucenie musi kończyć się powiadomieniem i widocznym statusem przy zamówieniu.
- Brak zabezpieczenia przed duplikatemPonowienie wysyłki bez klucza rozpoznającego powtórkę tworzy dwa dokumenty na jedną sprzedaż. Poprawka wymaga korekty, bo faktury przyjętej przez system nie da się wycofać.
- Ponawianie bez czytania Retry-AfterWedług dokumentacji limitów żądania liczy się osobno dla każdej pary: kontekst, czyli najczęściej NIP, w imieniu którego wysyłasz faktury, i adres IP. Po przekroczeniu API zwraca kod 429 z nagłówkiem Retry-After, a czas blokady rośnie z częstotliwością i skalą przekroczeń. Kolejka, która ponawia od razu, sama przedłuża przestój. Równoległe używanie wielu adresów IP w jednym kontekście dokumentacja opisuje jako próbę obchodzenia limitów, za którą system może zablokować dostęp do API.
- Numer KSeF zapisany tylko w UPONumer trzymaj przy zamówieniu i przy płatności, w osobnym polu. Od 1 stycznia 2027 r. trafia do komunikatu przelewu, a wyciąganie go wtedy z archiwum to praca, której da się dziś uniknąć jedną kolumną w bazie.
- Pominięte tryby offlineKod obsługuje tylko sytuację, w której system Ministerstwa odpowiada. Przy przerwie serwisowej albo ogłoszonej awarii sprzedaż staje, chociaż przepisy dają na dosłanie odpowiednio jeden dzień roboczy i 7 dni roboczych od zakończenia awarii.
- Odrzucona faktura offline poprawiana jak zwykłaFakturę offline odrzuconą z powodu technicznego, na przykład niezgodności ze schematem albo duplikatu, wysyła się ponownie jako korektę techniczną: wyłącznie w sesji interaktywnej, ze skrótem odrzuconego pliku w polu hashOfCorrectedInvoice. Treści faktury zmienić nie wolno. Nowy dokument dostaje własny numer i zostaje powiązany z pierwotnym, a kod z pierwszej wizualizacji pokaże, że fakturę skorygowano technicznie.
- Uprawnienia przypisane do osoby, która odeszłaJeśli Twój system loguje się tokenem albo certyfikatem pracownika, działa na jego uprawnieniach, a po ich odebraniu wysyłka przestaje działać. Firma z pieczęcią kwalifikowaną może zamiast tego użyć certyfikatu wystawionego na podmiot, ale wtedy sama odpowiada za to, kto ma do niego dostęp.
- Certyfikat bez przypomnienia o wygaśnięciuWedług strony Ministerstwa certyfikat KSeF jest ważny najwyżej 2 lata, a po tej dacie logowanie nim przestaje działać. Ustaw w monitoringu alert na kilka tygodni przed wygaśnięciem i miej gotową procedurę pobrania nowego.
- Testy wyłącznie na produkcjiFaktura testowa wysłana na produkcję jest prawdziwym dokumentem i zostaje w systemie. Testuj na środowisku TEST, które według opisu środowisk w przewodniku Ministerstwa dopuszcza samopodpisane certyfikaty; kilku integratorów może tam działać jako ta sama firma, a dane nie są od siebie odizolowane, więc używaj losowych numerów NIP zamiast prawdziwych danych. Dokumentacja limitów podaje, że na TEST limity są domyślnie dziesięć razy wyższe niż na produkcji. Środowisko DEMO ma konfigurację i limity produkcji i służy do końcowej walidacji.
Sklep internetowy i system sprzedaży: co trzeba zmienić
W sklepie e-faktura dotyka nie tylko samego dokumentu. Dotyka koszyka, danych klienta, kolejki zadań i tego, co widzi kupujący po zapłacie.
Zacznij od rozdzielenia sprzedaży konsumenckiej i firmowej. Faktury dla osób fizycznych nieprowadzących działalności nie podlegają obowiązkowi, a faktury z numerem NIP tak, więc kasa musi rozstrzygać, który przypadek zachodzi, i zapisywać tę decyzję przy zamówieniu. Pole „chcę fakturę” z opcjonalnym NIP-em przestaje wystarczać.
Druga zmiana dotyczy jakości danych. Schemat FA(3) sprawdza między innymi format numeru NIP, obecność kodu kraju i adresu oraz dozwolone wartości stawki VAT. Walidację trzeba więc przesunąć do kasy, zanim klient zapłaci, bo naprawianie danych po fakcie kończy się korektą.
Trzecia zmiana to sposób wystawiania. Faktura nie może powstawać synchronicznie w żądaniu obsługującym płatność. Właściwy układ to kolejka: płatność potwierdzona, zadanie w kolejce, wysyłka, zapis numeru KSeF i UPO, dopiero potem powiadomienie klienta. Chwilowa niedostępność systemu nie blokuje wtedy sprzedaży. Kiedy płatność można uznać za potwierdzoną i jak nie wystawić dwóch faktur z jednego powiadomienia, opisuje przewodnik płatności w sklepie internetowym.
Czwarta zmiana jest widoczna dla klienta. Nabywca będący czynnym podatnikiem odbierze fakturę z systemu, więc to, co wysyłasz mailem, jest wizualizacją, a nie dokumentem. Napisz to wprost w wiadomości i w panelu zamówień, razem z numerem KSeF. Taka wizualizacja musi mieć kod QR opisany w sekcji wyżej.
Piąta zmiana dotyczy strony kosztowej. Odbieranie e-faktur jest obowiązkowe dla wszystkich od 1 lutego 2026 r., więc obieg dokumentów zakupowych musi je pobierać z systemu, a nie czekać na załącznik.
Kto musi wystawiać e-faktury i co zostaje poza systemem
Wyłączenia z obowiązku mają trzy warstwy: status stron (siedziba za granicą, konsument), szczególne procedury (OSS, IOSS, SME) i rodzaj dokumentu (bilety, przejazdy autostradą, część usług finansowych).
Pierwsza warstwa dotyczy podmiotów. Faktur w KSeF nie muszą wystawiać firmy bez siedziby i bez stałego miejsca prowadzenia działalności w Polsce oraz te, których stałe miejsce nie uczestniczy w transakcji. W tej samej grupie są faktury dla osób fizycznych nieprowadzących działalności, więc sprzedaż konsumencka zostaje poza obowiązkiem, choć wolno ją przesłać dobrowolnie.
Druga warstwa to wyłączenia obowiązkowe, których nie obejdzie się dobrowolną wysyłką: procedura OSS w wariancie nieunijnym, procedura importu IOSS, okazjonalny międzynarodowy przewóz drogowy osób oraz unijna procedura SME z art. 113a ustawy o VAT. Tu wysłanie faktury do systemu jest błędem, a nie nadgorliwością.
Trzecia warstwa dotyczy rodzaju dokumentu. Poza systemem zostają faktury uproszczone za przejazd autostradą płatną, bilety jednorazowe uznane za faktury, faktury za usługi zwolnione z art. 43 ust. 1 pkt 7 i 37–41 ustawy o VAT (na przykład polisy uznane za faktury) oraz samofakturowanie bez polskiego numeru NIP po żadnej ze stron. Nie trafiają tam też proformy, faktury wewnętrzne oraz noty obciążeniowe i uznaniowe, a noty korygujące zniknęły z przepisów 1 lutego 2026 r.
Osobny kalendarz mają kasy rejestrujące: do końca 2026 r. faktury z kasy można wystawiać w dotychczasowej formie. Zakres wyłączeń bywa doprecyzowywany, więc sprawdź listę na ksef.podatki.gov.pl.
- Wyłączenie do 10 000 zł kończy się z rokiem 2026Do 31 grudnia 2026 r. można wystawiać faktury poza KSeF, jeśli ich łączna wartość z podatkiem nie przekracza w danym miesiącu 10 000 zł. Od 1 stycznia 2027 r. wyłączenie znika.
- Do limitu nie wlicza się wszystkiegoLiczą się wyłącznie faktury objęte obowiązkiem. Poza limitem zostają faktury z kasy, faktury dla konsumentów, sprzedaż udokumentowana samym paragonem oraz paragony z numerem NIP do 450 zł, czyli równowartości 100 EUR, uznane za faktury uproszczone.
- Przekroczenie progu jest nieodwracalnePo przekroczeniu 10 000 zł w danym miesiącu w KSeF trzeba wystawić fakturę, która próg przekroczyła, i każdą następną. Słabszy miesiąc nie przywraca wyłączenia.
Co zrobić teraz, zanim termin zacznie naciskać
Trzy rzeczy zrobisz jeszcze przed 1 stycznia 2027 r., zanim ktokolwiek zacznie pisać kod.
Jeśli masz zrobić tylko jedną rzecz, przejrzyj dane kontrahentów. Schemat FA(3) odrzuci plik z niepoprawnym formatem numeru NIP, adresem bez kodu kraju albo stawką VAT spoza listy, a te braki znajdziesz we własnej bazie bez integracji i bez decyzji o narzędziu.
Drugą rzeczą jest test odbioru. Obowiązek odbierania faktur przez KSeF objął wszystkich 1 lutego 2026 r., więc dokumenty kosztowe już tam są, niezależnie od tego, czy Twój obieg je pobiera. Sprawdź, czy księgowość widzi komplet faktur zakupowych z systemu, a nie tylko te przysłane mailem.
Trzecią jest decyzja o drodze. Firma wystawiająca kilkanaście faktur miesięcznie nie potrzebuje własnej integracji. Własne API ma sens wtedy, gdy faktura musi powstać automatycznie z konkretnego zdarzenia: opłaconego zamówienia, zakończonego okresu abonamentowego, rozliczonego projektu.
Jeśli sprzedajesz przez sklep, Stripe albo Base (dawniej BaseLinker), drogę wybierzesz w krótkim teście w przewodniku sklep, Stripe albo BaseLinker a KSeF od 1 stycznia 2027 r.. Wynik mówi, czy wystarczy aplikacja Ministerstwa, program do faktur, czy potrzebna jest integracja.
Pracuję sam, więc zaczynam od jednego pytania: w którym dokładnie momencie w Twoim systemie ma powstać faktura i co ma się stać, gdy KSeF ją odrzuci. Z tej odpowiedzi wynika zakres integracji, sposób obsługi błędów i to, czy w ogóle warto ją budować. Jeśli planujesz takie wdrożenie, napisz, skąd bierze się u Ciebie faktura i ile ich powstaje w miesiącu.
Pytania i odpowiedzi
Od kiedy KSeF jest obowiązkowy?
Obowiązek wystawiania faktur ustrukturyzowanych objął od 1 lutego 2026 r. podatników, u których wartość sprzedaży wraz z kwotą podatku przekroczyła w 2024 r. 200 mln zł, a od 1 kwietnia 2026 r. wszystkich pozostałych przedsiębiorców. Obowiązek odbierania faktur przez KSeF dotyczy wszystkich od 1 lutego 2026 r. Do 31 grudnia 2026 r. działa jeszcze wyłączenie dla faktur o łącznej wartości do 10 000 zł z podatkiem w miesiącu, a od 1 stycznia 2027 r. system obejmuje również tę grupę.
Czy muszę integrować własny system z KSeF przez API?
Nie, to jedna z trzech dróg. Możesz korzystać z bezpłatnej Aplikacji Podatnika KSeF, z aplikacji mobilnej albo z e-mikrofirmy w e-Urzędzie Skarbowym, możesz też użyć programu księgowego z gotową integracją. Własne API wybiera się wtedy, gdy faktura ma powstawać automatycznie z konkretnego zdarzenia w Twoim systemie, na przykład po opłaconym zamówieniu. Przy kilkunastu fakturach miesięcznie własna integracja się nie zwraca.
Jak wygląda uwierzytelnianie w API KSeF 2.0?
Integracja pobiera wyzwanie (POST /auth/challenge) i odsyła je podpisane w formacie XAdES podpisem lub pieczęcią kwalifikowaną, Profilem Zaufanym albo certyfikatem KSeF, ewentualnie wysyła token KSeF zaszyfrowany kluczem publicznym Ministerstwa. Po sprawdzeniu statusu odbiera accessToken, ważny kilkanaście minut, i refreshToken, ważny do 7 dni. Firma bez pieczęci kwalifikowanej zaczyna od zgłoszenia ZAW-FA. Tokeny wygenerowane w KSeF 1.0 nie działają w wersji 2.0, więc starą integrację trzeba przepiąć od nowa.
Sesja wsadowa czy interaktywna w sklepie internetowym?
Dokumentacja Ministerstwa Finansów podaje sklep internetowy jako przykład dla sesji wsadowej: faktury trafiają do kolejki i są wysyłane paczką cyklicznie, na przykład co 5 minut, co zużywa znacznie mniej żądań objętych limitami. Sesja interaktywna ma sens, gdy numer KSeF jest potrzebny natychmiast, na przykład przy sprzedaży w punkcie albo przy pojedynczej korekcie.
Czym jest numer KSeF i czy zastępuje numer faktury?
Numer KSeF to unikalny identyfikator faktury w systemie, nadawany automatycznie po jej przyjęciu i zwracany w Urzędowym Poświadczeniu Odbioru. Nie zastępuje Twojej własnej numeracji i nie jest elementem pliku faktury, więc oba numery funkcjonują równolegle. Warto zapisać go przy zamówieniu w osobnym polu, bo od 1 stycznia 2027 r. numer KSeF albo identyfikator zbiorczy trafia do komunikatu przelewu, także przy mechanizmie podzielonej płatności.
Czy faktura PDF wysłana klientowi mailem musi mieć kod QR?
Tak, jeśli to faktura wystawiona w KSeF, którą przekazujesz lub wykorzystujesz poza systemem, na przykład wysyłasz konsumentowi albo kontrahentowi z zagranicy. Na fakturze wystawionej online jest jeden kod QR, a bezpośrednio pod nim numer KSeF. Faktura wystawiona offline i udostępniona przed przesłaniem do KSeF ma dwa kody, z napisami OFFLINE i CERTYFIKAT. Przy własnej integracji kod generuje Twoja aplikacja z daty wystawienia, NIP-u sprzedawcy i skrótu SHA-256 pliku faktury.
Co zrobić, gdy KSeF jest niedostępny?
Przepisy przewidują trzy tryby szczególne. W trybie offline24, dostępnym dla każdego podatnika bez ograniczeń, fakturę przesyła się do systemu niezwłocznie, najpóźniej w następnym dniu roboczym. Przy niedostępności ogłoszonej w BIP Ministerstwa Finansów dosłanie następuje najpóźniej w następnym dniu roboczym po zakończeniu przerwy, a w trybie awaryjnym, ogłaszanym w BIP i w oprogramowaniu interfejsowym, w ciągu 7 dni roboczych od zakończenia awarii. Po ogłoszeniu awarii całkowitej faktur nie trzeba dosyłać.
Czy faktury dla konsumentów trzeba wystawiać w KSeF?
Nie. Faktury dla osób fizycznych nieprowadzących działalności gospodarczej są wyłączone z obowiązku, choć można je przesłać do systemu dobrowolnie. W praktyce oznacza to, że sklep musi jednoznacznie rozstrzygać w kasie, czy kupuje konsument, czy firma, i zapisywać tę decyzję przy zamówieniu, bo od niej zależy cała dalsza ścieżka dokumentu.
Jakie faktury nie trafiają do KSeF?
Poza obowiązkiem są między innymi faktury podmiotów bez siedziby i bez stałego miejsca prowadzenia działalności w Polsce oraz faktury dla konsumentów; te można wysłać dobrowolnie. Obowiązkowo poza systemem zostają procedura OSS nieunijna, IOSS, okazjonalny międzynarodowy przewóz drogowy osób i procedura SME z art. 113a ustawy o VAT. Nie trafiają tam też proformy, faktury wewnętrzne, noty obciążeniowe i uznaniowe, bilety jednorazowe uznane za faktury, faktury uproszczone za przejazd autostradą płatną ani faktury za usługi zwolnione z art. 43 ust. 1 pkt 7 i 37–41 ustawy o VAT. Listę potwierdź na ksef.podatki.gov.pl, bo bywa doprecyzowywana.
Czy za błędy w KSeF grożą kary?
W 2026 r. kar za błędy związane z korzystaniem z KSeF się nie nakłada. 16 września 2026 r. Ministerstwo Finansów zapowiedziało wydłużenie tego odroczenia do 31 grudnia 2027 r., ale wymaga to zmiany ustawy, więc do jej uchwalenia obowiązuje dotychczasowy termin. Odroczenie kar nie znosi obowiązku: od 1 stycznia 2027 r. KSeF jest obowiązkowy dla wszystkich przedsiębiorców, numer KSeF trafia do przelewów, a Krajowa Administracja Skarbowa zapowiada reakcję na faktury wystawiane poza systemem. Postęp prac nad ustawą sprawdź na stronach Ministerstwa Finansów.
Gdzie znajdę dokumentację API KSeF i środowisko testowe?
Ministerstwo Finansów publikuje specyfikację w standardzie OpenAPI 3.0.4 wraz z interaktywną dokumentacją dla trzech środowisk: produkcyjnego (api.ksef.mf.gov.pl), testowego TEST (api-test.ksef.mf.gov.pl) i przedprodukcyjnego DEMO (api-demo.ksef.mf.gov.pl). Udostępnia też publiczne repozytoria na GitHubie z przewodnikiem dla integratorów, dziennikiem zmian API oraz bibliotekami klienckimi w C# i Javie. Adresy wszystkich środowisk i repozytoriów zebrane są na stronie wsparcia dla integratorów na ksef.podatki.gov.pl.
Ile trwa i od czego zależy koszt wdrożenia integracji z KSeF?
Specyfikacja, środowiska testowe i biblioteki klienckie Ministerstwa są publicznie dostępne, więc koszt to głównie praca, a o niej decydują stan danych i liczba scenariuszy sprzedaży, nie sama wysyłka, którą uruchamia się szybko. Najwięcej czasu zajmują trzy rzeczy: uporządkowanie uprawnień i certyfikatów, oczyszczenie danych kontrahentów oraz obsługa błędów i trybów offline; potem dochodzi opieka nad zmianami API. Nie podam terminu bez zobaczenia konkretnego systemu, bo firma z jednym typem faktury i firma z pakietami, rabatami i rozliczeniami okresowymi mają zupełnie inny zakres pracy.
Czy sklep na Shopify albo WooCommerce poradzi sobie z KSeF?
Tak, ale wysyłkę do KSeF robi wtedy aplikacja lub wtyczka dostawcy fakturowania albo własna integracja, która nasłuchuje zdarzenia o opłaconym zamówieniu i tworzy dokument. W katalogu wtyczek WordPressa jest już kilka dodatków KSeF do WooCommerce. Wybierając dostawcę, zapytaj wprost o dwie rzeczy: co dzieje się, gdy system odrzuci dokument, i czy zapisuje numer KSeF przy zamówieniu. Cicha porażka wysyłki jest gorsza niż jej brak, bo odkrywa się ją przy zamknięciu miesiąca.
Źródła
Liczby i terminy w tym przewodniku sprawdziłem w oficjalnych źródłach. Ceny i przepisy się zmieniają, więc przy decyzji warto zajrzeć do nich ponownie.
- Ministerstwo Finansów: przedłużenie odroczenia kar za błędy w stosowaniu KSeF do końca 2027 r. (16.09.2026)
- KSeF: podstawy prawne oraz kluczowe terminy
- KSeF: zakres obowiązkowego KSeF i wyłączenia
- KSeF: wyłączenie dla sprzedaży poniżej 10 000 zł
- KSeF: numer KSeF i zbiorczy identyfikator
- KSeF: certyfikaty KSeF
- KSeF: tryby szczególne wystawiania faktur
- KSeF: tryb offline24
- KSeF: tryb offline przy niedostępności KSeF
- KSeF: tryb awaryjny
- KSeF: wsparcie dla integratorów i dokumentacja API
- KSeF: pytania i odpowiedzi do KSeF 2.0
- KSeF: informacje dla integratorów IT
- KSeF: informacje dla JDG i MŚP
- KSeF: informacje dla dużych firm
- Ministerstwo Finansów: co warto wiedzieć przed startem II etapu wdrożenia KSeF
- KSeF: kody weryfikujące QR
- Ministerstwo Finansów: schemat struktury logicznej FA(3) (XSD)
- Ministerstwo Finansów, przewodnik KSeF 2.0: uwierzytelnianie
- Ministerstwo Finansów, przewodnik KSeF 2.0: sesja interaktywna
- Ministerstwo Finansów, przewodnik KSeF 2.0: tokeny KSeF
- Ministerstwo Finansów, przewodnik KSeF 2.0: uprawnienia
- Ministerstwo Finansów, przewodnik KSeF 2.0: kody QR
- Ministerstwo Finansów, przewodnik KSeF 2.0: limity żądań API
- Ministerstwo Finansów, przewodnik KSeF 2.0: przyrostowe pobieranie faktur
- Ministerstwo Finansów, przewodnik KSeF 2.0: środowiska
- Ministerstwo Finansów, przewodnik KSeF 2.0: korekta techniczna faktury offline
- WordPress.org: katalog wtyczek, wyszukiwanie „KSeF”
Masz pytanie do swojego projektu?
Opisz, co chcesz osiągnąć. Odpowiem konkretnie, także wtedy, gdy najlepszą odpowiedzią jest „nie rób tego”.
Jonasz Jankowski · Bezpośrednia współpraca · Mikołów (Śląsk), zdalnie w całej Polsce
- Odpowiadam osobiście w ciągu jednego dnia roboczego.
- Krótka rozmowa o celu, funkcjach, materiałach i integracjach.
- Dostajesz zakres z etapami i konkretną kwotę, zanim cokolwiek zaczniemy.