Co zmieniło się w KSeF API 2.0?
Ministerstwo Finansów utrzymuje dokumentację techniczną publicznie, wraz z oficjalnymi klientami w C# i Javie. Cztery różnice względem wersji 1.0 wymagają decyzji projektowych:
- Uwierzytelnianie rozdzielone od inicjowania sesji. Token JWT jest wielokrotnego użytku między sesjami, co upraszcza pulę połączeń, ale wymaga świadomego zarządzania cyklem życia tokenu.
- Szyfrowanie obowiązkowe w obu trybach — wsadowym i interaktywnym. W 1.0 dla interaktywnego było opcjonalne. To najczęstsza przyczyna nieudanych migracji.
- Tryb wsadowy przetwarza faktury niezależnie, zamiast odrzucać całą paczkę przy pierwszym błędzie. Zmienia to obsługę błędów: po częściowym niepowodzeniu nie wolno wysłać paczki ponownie w całości.
- Nazewnictwo ujednolicone zgodnie ze standardem REST.
Jak działa uwierzytelnianie w KSeF API 2.0?
Dostępnych jest pięć metod:
| Metoda | Zastosowanie |
|---|---|
| Kwalifikowany podpis elektroniczny (XAdES) | Osoba fizyczna z podpisem kwalifikowanym |
| Token KSeF | Procesy automatyczne; szyfrowany RSA-OAEP SHA-256 |
| Certyfikat osoby fizycznej | Ścieżka XAdES, identyfikacja przez PESEL lub NIP |
| Pieczęć kwalifikowana | Podmiot, identyfikacja przez NIP |
| Profil Zaufany | Ścieżka XAdES |
Przebieg jest jednolity: pobranie wyzwania, podpisanie lub zaszyfrowanie, przesłanie, a następnie wymiana na token dostępowy JWT wraz z tokenem odświeżającym o siedmiodniowej ważności.
Dla integracji serwerowej naturalnym wyborem jest token KSeF albo pieczęć kwalifikowana. Warto zaplanować rotację: od 1 stycznia 2027 r. ważność tokenów będzie konfigurowalna w zakresie od 1 do 365 dni z automatycznym odnawianiem, ale integracja nie powinna zakładać, że token jest wieczny.
Certyfikaty KSeF: tożsamość, nie uprawnienia
Właściwość, którą trzeba znać przed zaprojektowaniem kontroli dostępu: certyfikaty KSeF nie niosą żadnych uprawnień — uprawnienia są zarządzane odrębnie. Certyfikat służy wyłącznie potwierdzeniu tożsamości.
Występują dwa wzajemnie wykluczające się typy:
- Authentication — keyUsage Digital Signature, do uwierzytelnienia.
- Offline — keyUsage Non-Repudiation, do podpisywania KOD II na fakturach wystawianych w trybie offline.
Certyfikaty wydawane są na podstawie żądania PKCS#10 (RSA 2048 lub krzywa NIST P-256). Organizacja, która przewiduje korzystanie z trybów offline, musi mieć wydany certyfikat typu Offline zanim będzie potrzebny — a to zwykle wychodzi na jaw w środku incydentu.
Jakie środowiska KSeF są dostępne?
| Środowisko | Adres | Charakterystyka |
|---|---|---|
| Testowe | api-test.ksef.mf.gov.pl/docs/v2 | Zawiera także wersje RC nowych funkcji |
| Przedprodukcyjne (Demo) | api-demo.ksef.mf.gov.pl/docs/v2 | Konfiguracja odpowiadająca produkcyjnej |
| Produkcyjne | api.ksef.mf.gov.pl/docs/v2 | — |
W środowiskach testowym i demo nie wolno używać prawdziwych faktur ani danych rzeczywistych podmiotów — należy stosować losowe numery NIP. Środowisko demo jest właściwym miejscem do testów wydajnościowych i scenariuszy awaryjnych, bo odwzorowuje konfigurację produkcyjną.
Wzorce, które warto wdrożyć od początku
Trwały identyfikator operacji przed pierwszym wywołaniem
Nadany deterministycznie z dokumentu źródłowego, ten sam dla wszystkich ponowień. Bez niego nie da się odpowiedzieć na pytanie, czy dokument został już przyjęty — i stąd biorą się duplikaty.
Zapis stanu przed wywołaniem, nie po nim
Stan „wysyłka rozpoczęta" musi być utrwalony, zanim żądanie opuści proces. System zapisujący dopiero po odpowiedzi nie ma śladu prób, które nie wróciły.
Odpytanie zamiast ponowienia
Po timeoucie domyślną reakcją musi być sprawdzenie statusu, nie ponowna wysyłka. Standardowe polityki retry w bibliotekach HTTP są w tym kontekście szkodliwe i trzeba je świadomie wyłączyć dla operacji wystawiania.
Walidacja lokalna przed wysyłką
Walidacja względem struktury FA(3) po własnej stronie eliminuje najczęstsze odrzucenia i zmniejsza liczbę zapytań. Pamiętaj, że FA(3) stosuje się także do korekt do dokumentów pierwotnych wystawionych wcześniej w FA(2) lub FA(1).
Kontrola pola P_1
KSeF uznaje za datę wystawienia wyłącznie P_1. Rozbieżność między P_1 a faktycznym momentem utworzenia dokumentu jest cichym źródłem przekroczeń terminu w trybach offline. Walidacja należy do warstwy integracyjnej.
Rozliczanie paczek dokument po dokumencie
Skoro tryb wsadowy przetwarza faktury niezależnie, wynik trzeba rozliczyć per dokument. Kod, który sprawdza wyłącznie status całej paczki, przeoczy pojedyncze odrzucenia — albo, gorzej, ponowi całość.
Obsługa błędów: trzy kategorie
| Kategoria | Przykład | Reakcja |
|---|---|---|
| Trwałe | Błąd struktury, niepoprawny NIP | Nie ponawiać. Skierować do poprawy. |
| Przejściowe | Przekroczony limit zapytań, chwilowa niedostępność | Ponowić z opóźnieniem, po sprawdzeniu statusu. |
| Nierozstrzygnięte | Timeout, zerwane połączenie | Wyłącznie odpytać status. Nigdy nie wysyłać ponownie. |
Trzecia kategoria jest tą, której brak w większości implementacji — błędy nierozstrzygnięte są traktowane jak przejściowe i ponawiane. Od 1 stycznia 2027 r. konsekwencje tego wyboru stają się finansowe.
Limity i wydajność
Limity zapytań mają zostać podniesione od 1 stycznia 2027 r., wraz z innymi zmianami zapowiedzianymi po konsultacjach z czerwca 2026 r. Do tego czasu warto zaprojektować kolejkowanie po własnej stronie, z kontrolą tempa, zamiast polegać na obsłudze odmowy. Kolejka daje przy okazji punkt, w którym można wpiąć progi zatwierdzania.
Najczęstsze pytania
Jakie metody uwierzytelnienia obsługuje KSeF API 2.0?
Podpis kwalifikowany XAdES, token KSeF, certyfikat osoby fizycznej, pieczęć kwalifikowana i Profil Zaufany. Od lutego 2026 r. także mObywatel.
Czy szyfrowanie jest obowiązkowe?
Tak, w trybie wsadowym i interaktywnym. To zmiana względem API 1.0.
Jakie środowiska są dostępne?
Testowe, przedprodukcyjne demo i produkcyjne. W dwóch pierwszych obowiązuje zakaz używania prawdziwych danych.
Jak długo ważny jest token?
Uwierzytelnienie zwraca token dostępowy JWT i token odświeżający o siedmiodniowej ważności. Od 1 stycznia 2027 r. ważność tokenów KSeF ma być konfigurowalna w zakresie 1–365 dni.
Czy certyfikat KSeF nadaje uprawnienia?
Nie. Certyfikat potwierdza tożsamość; uprawnienia są zarządzane odrębnie.
Dalej w tym cyklu
- KSeF, automatyzacja i AI — kompletny przewodnik dla firm
- Duplikaty i ponawianie operacji
- Tryby offline w KSeF
- Ślad audytowy w KSeF
BarzelVault działa jako warstwa między integracją a KSeF: egzekwuje polityki i progi zatwierdzania przed wykonaniem operacji oraz zapisuje każde wywołanie w formie odpornej na modyfikację.
W praktyce
Kontrola musi zadziałać, zanim faktura stanie się nieodwracalna.
Przyjętą fakturę ustrukturyzowaną można skorygować, ale nigdy usunąć, a od dnia wejścia kar każdy błąd ma swoją cenę. Barzel stawia próg akceptacji, kontrolę duplikatów i podpisany zapis przed wysyłką, tak aby proces dało się obronić w dniu, w którym zapyta o niego audytor albo urząd skarbowy.
Pozostało 95 dniKary KSeF obowiązują od 1 stycznia 2027 r.
BarzelVault
Firewall działań AI: decyduj, co agent może zrobić, zanim to zrobi.
- Progi akceptacji i reguły polityki egzekwowane przed wykonaniem; zatwierdzenia przez człowieka z terminem ważności i eskalacją.
- Kryptograficznie podpisane potwierdzenia audytowe: wyzwalacz, dane wejściowe, wersja polityki, osoba zatwierdzająca, wynik.
- Izolacja poświadczeń, limity kwot i działań oraz awaryjny wyłącznik.
Plan bezpłatny: 10 000 wywołań miesięczniePlany płatne od 199 USD miesięcznieDostępne na MCPize
Zacznij bezpłatnie Zapytaj e-mailemStrona produktuDokumentacja
BarzelOps
Nadzorowana automatyzacja procesów między systemami, na których działa firma.
- Trwałe, idempotentne wykonanie: przekroczenie czasu jest ponawiane raz, faktura nigdy nie trafia do systemu dwa razy.
- Punkty zatwierdzenia przez człowieka, które wstrzymują proces i wznawiają go.
- Izolacja per podmiot lub klient, podpisane dowody i przenośny manifest; integracje HubSpot, Xero, Gmail, Google Drive i Slack.
Plan bezpłatny: 100 wywołań dzienniePlany płatne od 19 USD miesięcznieDostępne na MCPize
Zacznij bezpłatnie Zapytaj e-mailemStrona produktuDokumentacja
Enterprise: pisemna wycena e-mailem w ciągu dwóch dni roboczych. Bez rozmowy handlowej.
Źródła
- Ministerstwo Finansów, Uwierzytelnianie i Przegląd kluczowych zmian KSeF API 2.0 — github.com/CIRFMF/ksef-api.
- Ministerstwo Finansów, Certyfikaty KSeF — github.com/CIRFMF/ksef-docs.
- Ministerstwo Finansów, podsumowanie konsultacji, 11 czerwca 2026 r.
Artykuł ma charakter informacyjny i nie stanowi porady podatkowej ani prawnej.