- Dla kogo
- Firma z własnym systemem sprzedaży, panelem lub ERP, który ma sam wysyłać i pobierać faktury z KSeF
- Co jest potrzebne
- Faktury w formacie FA(3), uwierzytelnienie w KSeF, szyfrowanie, obsługa statusów, błędów i trybów offline
- Gdzie testować
- Środowisko testowe, potem przedprodukcyjne (demo), dopiero na końcu produkcja
- Źródła
- Wyłącznie materiały Ministerstwa Finansów: ksef.podatki.gov.pl i dokumentacja CIRFMF na GitHubie, stan na 10 listopada 2026
Szybka odpowiedź
Integracja własnego systemu z KSeF przez API 2.0 polega na tym, że program uwierzytelnia się w KSeF (podpisem XAdES, certyfikatem KSeF albo tokenem KSeF), otwiera sesję, wysyła fakturę XML w formacie FA(3) zaszyfrowaną kluczem AES, sprawdza jej status i zapisuje nadany numer KSeF oraz UPO. Faktury zakupowe pobiera przyrostowym eksportem. Zacznij od środowiska testowego i oficjalnych bibliotek Ministerstwa Finansów w C# lub Javie, a przed produkcją przejdź testy na środowisku przedprodukcyjnym.
Ten tekst jest dla właściciela lub kierownika firmy, który ma własny program: system sprzedaży, panel do obsługi zamówień, sklep na zamówienie albo ERP, i zastanawia się, czy podłączyć go bezpośrednio do KSeF. Opisuję, jak działa API, co trzeba zbudować i w jakiej kolejności. Szczegóły techniczne pochodzą z oficjalnej dokumentacji KSeF API 2.0 na GitHubie Ministerstwa Finansów (wersja API 2.9.0, wdrożona na produkcji 15 października 2026) i z serwisu ksef.podatki.gov.pl.
Jeśli prowadzisz małą firmę i szukasz listy kontrolnej bez programowania, przeczytaj raczej KSeF w jednoosobowej firmie od 2027. Podstawy samego systemu wyjaśniam w tekście czym jest KSeF w prostych słowach.
Terminy, które wyznaczają harmonogram integracji
Według strony „Zasady obowiązywania KSeF” obowiązek wystawiania faktur w KSeF obejmuje: od 1 lutego 2026 podatników, których sprzedaż w 2024 roku przekroczyła 200 mln zł, od 1 kwietnia 2026 pozostałych podatników, a od 1 stycznia 2027 tych, u których sprzedaż udokumentowana fakturami nie przekracza 10 000 zł brutto miesięcznie. Kary za błędy w stosowaniu KSeF według obecnych przepisów mają być stosowane od 1 stycznia 2027. 20 października 2026 Rada Ministrów przyjęła projekt ustawy przesuwający kary do 31 grudnia 2027. To projekt, a nie obowiązujące prawo, więc sprawdź jego status przed planowaniem.
Wniosek praktyczny: jeśli Twoja firma wystawia faktury z własnego systemu, to od kwietnia 2026 i tak musi je jakoś dostarczać do KSeF. Pytanie brzmi, czy robi to Twój system bezpośrednio, czy przez program do faktur. Kwestie podatkowe, np. które dokumenty muszą trafić do KSeF, rozstrzyga księgowa lub doradca podatkowy.
Czy w ogóle potrzebujesz własnej integracji
Nie każda firma z własnym systemem powinna pisać integrację z KSeF. Często prościej przekazać dane do programu do faktur, który już obsługuje KSeF.
| Sytuacja | Rozsądne rozwiązanie |
|---|---|
| Kilkadziesiąt faktur miesięcznie, program księgowy z KSeF | System eksportuje dane do programu do faktur, a ten wysyła do KSeF |
| Sklep na popularnej platformie | Gotowa wtyczka lub integracja programu do faktur |
| Własny system, setki lub tysiące faktur, faktury powstają automatycznie (zamówienia, wynajem, abonamenty) | Bezpośrednia integracja z API KSeF |
| Firma ma odbierać faktury kosztowe do własnego obiegu dokumentów | Integracja tylko w zakresie pobierania faktur |
Wysyłka wymaga szyfrowania AES-256 i RSA-OAEP, liczenia skrótów SHA-256, odświeżania tokenów, kolejki z ponowieniami, obsługi limitów i trybów offline. Platformy no-code nie są do tego zrobione, a każdy błąd oznacza fakturę, która formalnie nie została wystawiona. Takie automatyzacje mogą przekazać dane do programu do faktur, ale samą komunikację z KSeF powinien obsługiwać program z prawdziwą obsługą błędów.
Jak działa KSeF API 2.0 w skrócie
Każda wysyłka przechodzi przez te same etapy: uwierzytelnienie, sesja, wysyłka zaszyfrowanej faktury, sprawdzenie statusu, zamknięcie sesji i pobranie potwierdzeń. Ścieżki adresów poniżej podaję względem adresu API danego środowiska.
Środowiska: gdzie testować
Ministerstwo udostępnia trzy publiczne środowiska. Według dokumentu „Środowiska KSeF API 2.0” wyglądają tak:
| Środowisko | Do czego | Dokumentacja API | Na co uważać |
|---|---|---|---|
| TEST (testowe) | Budowa i testy integracji, wersje kandydujące | api-test.ksef.mf.gov.pl/docs/v2 | Dozwolone samopodpisane certyfikaty, dane nie są odizolowane między integratorami. Tylko losowe NIP, nigdy prawdziwe dane. Limity dziesięciokrotnie wyższe niż na produkcji |
| DEMO (przedprodukcyjne) | Końcowa walidacja w warunkach zbliżonych do produkcji | api-demo.ksef.mf.gov.pl/docs/v2 | Konfiguracja jak na produkcji, nadal bez faktur produkcyjnych |
| PROD (produkcyjne) | Faktury z pełną mocą prawną | api.ksef.mf.gov.pl/docs/v2 | Faktura przyjęta tutaj jest wystawiona. Tu nie ma miejsca na testy |
Na środowiskach testowych prowadzone są cykliczne prace serwisowe w godzinach 16:00–18:00, więc nie planuj na ten czas automatycznych testów. Zmiany w API Ministerstwo ogłasza w changelogu w repozytorium dokumentacji. Warto obserwować go na bieżąco, bo nowe wersje wchodzą co kilka tygodni.
Uwierzytelnianie: certyfikat, podpis czy token
Uwierzytelnienie zawsze dotyczy dwóch rzeczy: kontekstu, czyli firmy, w imieniu której działasz (zwykle NIP), oraz podmiotu, który się loguje. KSeF sprawdza, czy ten podmiot ma w danym kontekście co najmniej jedno aktywne uprawnienie. Metody według dokumentacji uwierzytelniania:
- Podpis XAdES dokumentu
AuthTokenRequest– kwalifikowanym certyfikatem osoby lub pieczęcią firmową, podpisem zaufanym albo certyfikatem KSeF. Na produkcji przy certyfikatach kwalifikowanych KSeF sprawdza ich status u wystawcy, co może potrwać. - Certyfikat KSeF – wydawany przez sam KSeF. Ministerstwo zaleca go na produkcji, bo weryfikacja odbywa się wewnątrz systemu bez czekania na wystawcę certyfikatu. Typ
Authenticationsłuży do logowania, typOfflinedo kodu QR na fakturach offline. Jeden certyfikat nie łączy obu funkcji, a ważność to maksymalnie 2 lata. - Token KSeF – sekret generowany po jednorazowym uwierzytelnieniu podpisem, z określonym zakresem uprawnień, np. tylko odczyt faktur. Przesyła się go zaszyfrowany razem ze znacznikiem czasu z wyzwania.
Na stronie „Certyfikaty KSeF” (aktualizacja z 1 września 2026) Ministerstwo podaje, że tokeny miały działać do końca 2026, ale zostaną utrzymane bezterminowo, a rozporządzenie zostanie w tej sprawie zmienione. Pod koniec października 2026 opublikowano projekt zmiany rozporządzenia, który według doniesień prasowych przewiduje odrębne zasady dla tokenów generowanych od 1 stycznia 2027. To projekt, a szczegóły mogą się jeszcze zmienić. Do czasu publikacji zmian w Dzienniku Ustaw projektuj system tak, żeby obsługiwał certyfikat KSeF, a token traktuj jako metodę pomocniczą.
Po udanym uwierzytelnieniu dostajesz accessToken ważny krótko (dokumentacja mówi o kilkunastu minutach, dokładny czas jest w polu exp) oraz refreshToken ważny do 7 dni, którym odświeżasz dostęp. Oba, podobnie jak token KSeF i klucz prywatny certyfikatu, przechowuj jak hasło do bankowości: w zaszyfrowanym magazynie sekretów, nie w kodzie ani w pliku konfiguracyjnym w repozytorium. Uwierzytelnienie można dodatkowo ograniczyć do listy adresów IP serwera. O ochronie takich danych piszę w tekście jak zabezpieczyć dane firmowe przed utratą i wyciekiem.
Wysyłka faktur: sesja interaktywna i wsadowa
Faktura musi być plikiem XML zgodnym ze schematem FA(3), który na produkcji jest wymagany (środowisko testowe przyjmuje jeszcze FA(2)). Przed wysyłką Twój system generuje klucz AES-256 i wektor IV, szyfruje nim fakturę, a sam klucz szyfruje kluczem publicznym Ministerstwa Finansów algorytmem RSA-OAEP z SHA-256. Oficjalne biblioteki ksef-client-csharp i ksef-client-java mają to gotowe. Jeśli Twój system jest w innym języku, korzystaj z nich przynajmniej jako wzorca.
| Sesja interaktywna | Sesja wsadowa | |
|---|---|---|
| Do czego | Pojedyncze faktury wysyłane na bieżąco | Wiele faktur naraz w paczce ZIP |
| Czas życia i limity | Sesja do 12 godzin, do 10 000 faktur | Do 10 000 faktur, do 50 części po maks. 100 MB, łącznie do 5 GB. Na przesłanie każdej części jest 20 minut razy liczba części |
| Załączniki | Nie (wyjątek: korekta techniczna faktury offline) | Tak, po wcześniejszym zgłoszeniu w e-Urzędzie Skarbowym |
| Kiedy | Sprzedaż w ciągu dnia, wynajem, zamówienia | Fakturowanie zbiorcze, abonamenty na koniec miesiąca |
Według zasad weryfikacji faktury KSeF odrzuci plik, który nie jest poprawnym XML w UTF-8 bez znacznika BOM, nie zgadza się ze schematem albo przekracza 1 MB (3 MB z załącznikami). Duplikat rozpoznaje po trójce: NIP sprzedawcy, rodzaj faktury, numer faktury, i zwraca wtedy błąd 440. Data wystawienia (pole P_1) nie może być późniejsza niż data przyjęcia do KSeF. Jeśli faktury wystawia kilka oddziałów pod tym samym NIP, numeracja musi być wspólnie uzgodniona.
Numer KSeF i UPO: co zapisać w swoim systemie
Po przyjęciu faktury KSeF nadaje jej numer o długości 35 znaków, np. 5265877635-20250826-0100001AF629-AF: NIP sprzedawcy, data przyjęcia, część techniczna i suma kontrolna CRC-8. Datą otrzymania faktury przez nabywcę jest data nadania numeru KSeF. Po zamknięciu sesji dostępne jest UPO, czyli urzędowe poświadczenie odbioru, podpisane przez Ministerstwo Finansów w formacie XAdES.
Odbiór faktur zakupowych
Do pobierania faktur, na których Twoja firma jest nabywcą, Ministerstwo rekomenduje przyrostowy eksport (POST /invoices/exports). System co jakiś czas zleca eksport faktur z kolejnego, przylegającego okna czasowego, KSeF przygotowuje zaszyfrowaną paczkę ZIP z plikami XML i plikiem _metadata.json, a Twój system ją pobiera, odszyfrowuje i usuwa duplikaty. Okna wyznacza się po dacie trwałego zapisu (PermanentStorage) z mechanizmem High Water Mark, który gwarantuje, że żadna faktura nie zostanie pominięta.
Ważne limity z dokumentacji przyrostowego pobierania: do 20 eksportów na godzinę i nie częściej niż co 15 minut dla danego typu podmiotu. Firma może występować na fakturze w różnych rolach (nabywca, podmiot trzeci, podmiot upoważniony), a każdą trzeba pobierać osobno. Po przekroczeniu limitów KSeF zwraca kod 429 z nagłówkiem Retry-After, a powtarzające się przekroczenia wydłużają blokadę. Limity liczone są dla pary: kontekst (NIP) i adres IP.
Tryby offline i kody QR
Twój system musi umieć wystawić fakturę, gdy KSeF nie odpowiada. Zestawienie trybów według dokumentacji trybów offline:
| Tryb | Kiedy | Termin dosłania do KSeF |
|---|---|---|
| offline24 | Z dowolnej przyczyny po stronie podatnika | Do następnego dnia roboczego po dacie wystawienia |
| offline (niedostępność KSeF) | Niedostępność ogłoszona w BIP i w API | Do następnego dnia roboczego po zakończeniu niedostępności |
| awaryjny | Awaria KSeF ogłoszona komunikatem | Do 7 dni roboczych od zakończenia awarii |
| awaria całkowita | Ogłoszona w środkach masowego przekazu | Faktury nie dosyła się do KSeF |
Fakturę offline wysyła się później z parametrem offlineMode: true. Wizualizacja faktury przekazywana klientowi poza KSeF ma kod QR. Faktura wystawiona online ma jeden kod (KOD I, do weryfikacji i pobrania faktury), a offline dwa: KOD I i KOD II, potwierdzający wystawcę. KOD II generuje się certyfikatem KSeF typu Offline, który trzeba pobrać wcześniej, bo w czasie awarii KSeF go nie wyda. Kody generuje Twój system lokalnie, zgodnie z normą ISO/IEC 18004:2024.
Plan integracji krok po kroku
- Ustal zakres z księgową
Jakie dokumenty system wystawia (faktury, korekty, zaliczkowe), czy ma też pobierać faktury zakupowe, kto w firmie ma uprawnienia w KSeF. Bez tego programista zgaduje, a zgadywanie przy fakturach kończy się korektami.
- Zmapuj dane do FA(3)
Przejdź pola schematu i sprawdź, skąd Twój system je weźmie: dane nabywcy, stawki, jednostki, kursy walut, adnotacje. To zwykle najdłuższy etap. Często wychodzi, że w bazie brakuje pól albo dane są w złym formacie, np. NIP z myślnikami.
- Wybierz bibliotekę i architekturę
Oficjalny klient C# albo Java, ewentualnie osobna usługa pośrednicząca, z którą rozmawia Twój system. Komunikacja z KSeF powinna iść przez kolejkę z ponowieniami, a nie bezpośrednio z przycisku „Wystaw fakturę”.
- Zbuduj i przetestuj na środowisku TEST
Samopodpisany certyfikat, losowy NIP, faktury testowe. Sprawdź wysyłkę, odrzucenia, duplikaty, wygaśnięcie tokena, limity. KSeF udostępnia na środowisku testowym endpoint, który włącza limity takie jak na produkcji.
- Obsłuż wszystkie statusy i tryby offline
Odrzucenie, brak odpowiedzi, kod 429, awaria, dosyłanie offline, korekta techniczna faktury offline. To one decydują, czy integracja jest bezpieczna.
- Przejdź walidację na DEMO
Środowisko przedprodukcyjne ma konfigurację jak produkcja. Tu sprawdzasz prawdziwy sposób uwierzytelnienia i kompletny scenariusz dnia pracy.
- Uruchom produkcję z certyfikatem KSeF i właściwymi uprawnieniami
Certyfikat do uwierzytelniania, osobny do trybu offline, zapisana data ich wygaśnięcia, uprawnienia nadane we właściwym zakresie. Pierwsze dni obserwuj wszystkie wysyłki.
- Monitoruj i aktualizuj
Alert, gdy faktura długo czeka na numer KSeF albo zostaje odrzucona. Obserwuj changelog API, bo zmiany w kontrakcie wchodzą regularnie.
# Kolejność wywołań przy wysyłce jednej faktury (ścieżki względem adresu API środowiska)
POST /auth/challenge # wyzwanie, ważne 10 minut
POST /auth/xades-signature # albo POST /auth/ksef-token
GET /auth/{referenceNumber} # odpytuj do skutku
POST /auth/token/redeem # accessToken + refreshToken
POST /sessions/online # klucz AES zaszyfrowany RSA-OAEP
POST /sessions/online/{ref}/invoices # zaszyfrowana faktura FA(3)
GET /sessions/{ref}/invoices/{invoiceRef} # status: numer KSeF albo błąd
POST /sessions/online/{ref}/close # zamknięcie, generowanie UPO
GET /sessions/{ref}/invoices/{invoiceRef}/upo
POST /auth/token/refresh # gdy accessToken wygaśnieIntegracja z KSeF rzadko jest jedynym problemem. Częściej wychodzi przy niej, że dane o klientach i sprzedaży żyją w kilku arkuszach. O tym, kiedy przenieść je do jednego systemu, piszę w tekście program zamiast Excela w firmie. Od czego zależy koszt takiej pracy, wyjaśniam we wpisie ile kosztuje program dla firmy na zamówienie.
Firma ma własny panel do obsługi zamówień i do tej pory wystawiała faktury, przepisując dane do programu księgowego. Przed obowiązkiem KSeF właściciel chce, żeby panel wysyłał faktury sam. Mapowanie danych pokazuje, że część klientów ma NIP zapisany z myślnikami, a adresy w jednym polu tekstowym. Po uporządkowaniu danych faktury przechodzą przez środowisko testowe, a testy wychwytują duplikaty numerów przy fakturach wystawianych równolegle przez dwie osoby. Numeracja trafia do jednego miejsca w bazie, faktury wysyłane są przez kolejkę, a panel pokazuje przy każdej fakturze numer KSeF albo powód odrzucenia.
Kiedy lepiej to zlecić
Jeśli masz w zespole programistę, który zna szyfrowanie, podpisy XML i pracę z API, dokumentacja Ministerstwa jest wystarczająco dokładna, żeby zrobić to samodzielnie. Pomoc z zewnątrz przydaje się, gdy:
- system pisała firma, która już go nie rozwija, a nikt nie zna jego bazy danych,
- trzeba zmapować dane do FA(3) i uporządkować je przed pierwszą wysyłką,
- potrzebujesz tylko pobierania faktur zakupowych do własnego obiegu dokumentów,
- chcesz, żeby ktoś ocenił, czy integracja w ogóle się opłaca, czy lepiej przekazywać dane do programu do faktur,
- zależy Ci na obsłudze błędów, trybów offline i monitoringu, a nie tylko na „wysyła się”.
Integracje i programy dla firm buduję w ramach usługi automatyzacji procesów i programowania na zamówienie. Kwestie podatkowe zostawiam księgowym, a sam zajmuję się tym, żeby technicznie wszystko działało.
Twój system ma sam wysyłać faktury do KSeF?
Opisz, w czym działa Twój system, ile faktur wystawiacie i czy chcecie też pobierać faktury zakupowe. Ocenię, czy integracja ma sens, i zaproponuję plan, a wycenę dostajesz przed rozpoczęciem pracy. Pracuję zdalnie w całej Polsce, w Sieradzu i okolicach mogę przyjechać.
Najczęstsze pytania
Od czego zacząć integrację z KSeF API?
Od ustalenia z księgową zakresu dokumentów i zmapowania danych systemu do schematu FA(3). Potem przeczytaj dokumentację KSeF API 2.0 Ministerstwa Finansów na GitHubie, wybierz oficjalną bibliotekę w C# lub Javie i zbuduj integrację na środowisku testowym z losowym NIP. Przed produkcją przejdź testy na środowisku przedprodukcyjnym.
Czym się uwierzytelnić w KSeF API na produkcji?
Ministerstwo Finansów zaleca certyfikat KSeF typu uwierzytelniającego, bo jego weryfikacja odbywa się wewnątrz KSeF bez czekania na wystawcę certyfikatu kwalifikowanego. Możliwe są też podpis XAdES certyfikatem kwalifikowanym lub pieczęcią oraz token KSeF, który według strony Ministerstwa z września 2026 ma zostać utrzymany bezterminowo.
Czy środowisko testowe KSeF jest bezpieczne dla prawdziwych danych?
Nie. Na środowisku testowym dopuszczalne są samopodpisane certyfikaty, a dane nie są odizolowane między integratorami. Ministerstwo zaleca używanie losowych numerów NIP i nieprzesyłanie tam faktur produkcyjnych ani rzeczywistych danych firm.
Co zrobić, gdy KSeF nie działa w chwili wystawiania faktury?
System wystawia fakturę w trybie offline z dwoma kodami QR i dosyła ją do KSeF z parametrem offlineMode: true. W trybie offline24 termin to następny dzień roboczy po wystawieniu, przy ogłoszonej niedostępności następny dzień roboczy po jej zakończeniu, a przy awarii 7 dni roboczych od jej zakończenia. Do kodu QR II potrzebny jest certyfikat KSeF typu Offline pobrany wcześniej.
Czy mogę zintegrować KSeF przez Make albo Zapier?
Nie polecam tego do wysyłki faktur. KSeF API wymaga szyfrowania AES i RSA-OAEP, skrótów SHA-256, odświeżania tokenów, kolejki z ponowieniami i obsługi trybów offline. Platformy no-code mogą przekazywać dane do programu do faktur, ale samą komunikację z KSeF powinien obsługiwać program z pełną obsługą błędów.
Powiązane wpisy
