Integracja z KSeF 2.0 — jak podpiąć własny system do API e-faktur

Krajowy System e-Faktur (KSeF) przestał być tematem „na później". Obowiązek wystawiania faktur ustrukturyzowanych objął dużych podatników od 1 lutego 2026 r., pozostałe firmy od 1 kwietnia 2026 r., a mikroprzedsiębiorców o obrotach do 10 tys. zł miesięcznie dopiero od 1 stycznia 2027 r. Do końca 2026 roku trwa okres przejściowy, w którym fiskus nie nakłada kar — ale gdy się skończy, sankcje mogą sięgnąć nawet 100% kwoty podatku wykazanego na fakturze wystawionej poza systemem.

Innymi słowy: jeśli budujesz lub utrzymujesz ERP, system fakturowy albo backend obsługujący sprzedaż, masz jeszcze kilka miesięcy realnego marginesu na dopięcie integracji z API KSeF 2.0. Ten artykuł to praktyczny przewodnik po architekturze integracji: co musisz zrozumieć, jak wygląda przepływ wysyłki faktury i o czym łatwo zapomnieć przy wdrożeniu produkcyjnym.

Uwaga: poniższy tekst opisuje logikę i architekturę integracji na wysokim poziomie. Konkretne nazwy endpointów, pola i schematy potrafią się zmieniać między wersjami — zawsze weryfikuj szczegóły w oficjalnej dokumentacji Ministerstwa Finansów (ksef.gov.pl oraz repozytorium API i schematów). Nie koduj integracji z pamięci ani z artykułów blogowych.

Czym jest KSeF od strony technicznej

Z perspektywy dewelopera KSeF to centralna platforma państwowa, która:

• przyjmuje faktury ustrukturyzowane w formacie XML zgodnym z narzuconym schematem (FA(2), docelowo FA(3)),
• waliduje je względem schemy XSD i reguł biznesowych,
• nadaje każdej fakturze unikalny numer KSeF oraz datę przyjęcia (moment ten jest datą wystawienia w rozumieniu prawa),
• zwraca UPO — Urzędowe Poświadczenie Odbioru, czyli dowód, że faktura została skutecznie przyjęta,
• udostępnia faktury wystawione na danego podatnika (jesteś zarówno wystawcą, jak i odbiorcą e-faktur).

Twój system nie „wysyła PDF-a do klienta". Twój system rozmawia z API państwa, a faktura krąży wewnątrz KSeF. To zmiana modelu mentalnego, którą trzeba przełożyć na architekturę.

Środowiska

Ministerstwo Finansów udostępnia oddzielne środowiska. W praktyce integrację prowadzisz na środowisku testowym / przedprodukcyjnym (do developmentu i testów akceptacyjnych, bez skutków prawnych) i dopiero po weryfikacji przełączasz się na produkcję. Każde środowisko ma własny adres bazowy API i własną pulę tokenów oraz certyfikatów — nie mieszaj poświadczeń między nimi.

Kluczowe pojęcia, bez których się nie ruszysz

• Numer KSeF — identyfikator nadawany fakturze przez system po pozytywnej walidacji. Dopiero jego otrzymanie oznacza, że faktura „istnieje".
• UPO — urzędowe potwierdzenie przyjęcia (dla sesji zbiorczej wystawiane dla całej paczki). To dokument, który musisz przechowywać.
• Sesja — komunikacja z KSeF odbywa się w ramach sesji. Otwierasz ją, wysyłasz jedną lub wiele faktur, a na koniec zamykasz, co inicjuje wystawienie UPO.
• Sesja interaktywna vs wsadowa — interaktywna nadaje się do wysyłki pojedynczych faktur „na bieżąco"; wsadowa (batch) służy do wysyłki dużych paczek jednym pakietem (np. nocny eksport z ERP).
• Schemat FA — XSD definiujący strukturę faktury. Mapowanie danych z Twojego modelu na pola schemy to zwykle najbardziej pracochłonna część wdrożenia.
• Uprawnienia — dostęp do wystawiania/odbioru faktur w imieniu podmiotu wynika z modelu uprawnień (właściciel, uprawnienia nadane pracownikowi, dostęp dla systemu przez token/certyfikat).

Uwierzytelnianie w KSeF 2.0

To najczęstszy punkt zapalny integracji. W KSeF 2.0 uwierzytelnienie systemu opiera się o poświadczenia kryptograficzne — certyfikat KSeF i/lub token przypisany do uprawnień danego podmiotu. Uproszczony przebieg wygląda tak:

1. Uzyskujesz challenge (wyzwanie autoryzacyjne) od API dla konkretnego NIP-u/podmiotu.
2. Podpisujesz żądanie uwierzytelnienia — podpisem kwalifikowanym, pieczęcią kwalifikowaną albo tokenem/certyfikatem KSeF nadanym systemowi.
3. Otrzymujesz token sesyjny (dostępowy), którym autoryzujesz kolejne wywołania w ramach sesji.

# Schematycznie (pseudo-przepływ, nazwy pól zależne od wersji API):

POST /auth/challenge          -> { challenge, timestamp }
   podpisz payload (certyfikat / token)
POST /auth/token   (podpisany)-> { sessionToken, expiresIn }
   nagłówek kolejnych żądań: Authorization: Bearer <sessionToken>

Praktyczne wnioski dla architektury:

• Tokeny są krótkożyjące — zaprojektuj odświeżanie i bezpieczne przechowywanie (sekret manager / vault, nigdy w repo).
• Certyfikaty i klucze prywatne trzymaj w KMS/HSM lub przynajmniej w szyfrowanym magazynie sekretów.
• Wielopodmiotowość — jeśli obsługujesz wielu klientów (np. SaaS ERP), potrzebujesz izolacji poświadczeń per NIP i modelu nadawania uprawnień.

Przepływ wysyłki faktury krok po kroku

Docelowy „happy path" dla pojedynczej faktury wygląda następująco:

1. Wygeneruj XML faktury zgodny ze schematem FA i zwaliduj go lokalnie względem XSD (walidacja po stronie klienta oszczędza mnóstwo round-tripów).
2. Uwierzytelnij się i otwórz sesję.
3. Wyślij fakturę do sesji. W odpowiedzi dostajesz zwykle identyfikator referencyjny (numer referencyjny elementu), a nie od razu numer KSeF.
4. Odpytuj o status (polling) — walidacja bywa asynchroniczna. Status przechodzi od „przyjęto do przetwarzania" do „zaakceptowano" (z numerem KSeF) lub „odrzucono" (z listą błędów).
5. Zamknij sesję — to inicjuje wygenerowanie UPO.
6. Pobierz i zarchiwizuj UPO oraz numer KSeF przy fakturze w Twojej bazie.

# Uproszczony cykl życia (pseudo-kod):

session = openSession(sessionToken)
ref     = session.sendInvoice(xmlFaktury)

status = poll(ref, until = ["ACCEPTED", "REJECTED"], backoff = expo)
if status == ACCEPTED:
    ksefNumber = status.ksefReferenceNumber
    persist(invoiceId, ksefNumber, status)
else:
    handleValidationErrors(status.errors)

session.close()          # generuje UPO
upo = session.fetchUPO() # zarchiwizuj (obowiązek przechowywania)

Czego nie widać w „happy path" — a wywróci Ci wdrożenie

Idempotencja i deduplikacja. Sieć potrafi zerwać połączenie po wysłaniu faktury, ale przed odebraniem odpowiedzi. Bez klucza idempotentnego i twardej deduplikacji po Twojej stronie ryzykujesz podwójne wystawienie tej samej faktury w KSeF — a to już problem księgowy, nie techniczny.

Asynchroniczność. Traktuj wysyłkę jako proces, nie jak synchroniczne INSERT. Kolejka (np. outbox pattern), worker z retry i eksponencjalnym backoffem oraz stan „w trakcie / zaakceptowana / odrzucona" per faktura to minimum.

Walidacja lokalna. Zwaliduj XML względem XSD przed wysyłką. Osobno pilnuj reguł biznesowych (NIP, sumy, waluty, stawki VAT), bo część odrzuceń nie wynika ze schemy, lecz z reguł systemu.

Przechowywanie UPO i numerów KSeF. To dane, które musisz archiwizować i umieć odtworzyć. Zaprojektuj tabelę powiązań faktura ↔ numer KSeF ↔ UPO ↔ status od pierwszego dnia.

Obsługa awarii KSeF. System państwowy miewa okna serwisowe i przestoje. Przepisy przewidują tryby offline/awaryjne z późniejszym dosłaniem faktur — Twój backend musi umieć kolejkować i dosyłać, a nie blokować sprzedaż.

Limity i przepustowość. Przy dużym wolumenie rozważ sesje wsadowe zamiast setek pojedynczych wywołań. Zaprojektuj throttling i monitoruj czasy odpowiedzi.

Jak to wpiąć w istniejący ERP / backend

Sprawdzony wzorzec to warstwa pośrednia (adapter KSeF) oddzielona od logiki ERP:

• Mapper — tłumaczy Twój model faktury na XML FA (i z powrotem dla faktur przychodzących). To serce integracji; hermetyzuj go i pokryj testami na realnych przykładach.
• Outbox + kolejka — faktura po zatwierdzeniu w ERP trafia do tabeli outbox; worker asynchronicznie wysyła ją do KSeF i aktualizuje status. Sprzedaż nie czeka na państwo.
• Klient KSeF — cienka biblioteka obsługująca auth, sesje, wysyłkę, polling i UPO, z retry i idempotencją.
• Magazyn poświadczeń — UPO, numery KSeF, logi żądań/odpowiedzi (przydatne przy reklamacjach i audycie).
• Panel operacyjny — widok faktur odrzuconych z powodem błędu, możliwość ponowienia. Bez tego dział księgowości utonie w niewidocznych błędach.

Plan wdrożenia na najbliższe miesiące

Masz realistycznie kilka miesięcy do końca okresu przejściowego. Sensowna kolejność:

1. Rejestracja i uprawnienia — załatw dostęp systemu do środowiska testowego, wygeneruj tokeny/certyfikaty, ogarnij model uprawnień per podmiot.
2. Mapowanie danych — zmapuj model faktury na schemat FA. Zbierz „trudne" przypadki: korekty, faktury zaliczkowe, waluty obce, odwrotne obciążenie, złożone stawki.
3. Klient i przepływ — zaimplementuj auth, sesje, wysyłkę, polling, UPO. Dodaj idempotencję i retry.
4. Testy na środowisku przedprodukcyjnym — przepuść realny wolumen i scenariusze błędów (odrzucenia, timeouty, awaria KSeF).
5. Archiwizacja i raportowanie — UPO, numery KSeF, statusy, panel dla księgowości.
6. Przełączenie na produkcję — najpierw równolegle/pilotażowo, potem pełne wdrożenie. Zaplanuj monitoring i alerty.

Podsumowanie

Integracja z KSeF 2.0 to nie „dodanie jednego endpointu". To zaprojektowanie odpornego, asynchronicznego przepływu: uwierzytelnianie kryptograficzne, sesje, walidacja względem schemy FA, polling statusów, obsługa UPO, idempotencja i tryby awaryjne. Techniczne szczegóły dobierzesz z oficjalnej dokumentacji MF — ale architekturę i twarde punkty ryzyka warto zaprojektować z góry, zanim skończy się okres bez kar.

W Mobilesoft budujemy backendy i integracje ERP, w tym adaptery do systemów państwowych takich jak KSeF. Jeśli chcesz przejść od „mamy jeszcze czas" do działającej, przetestowanej integracji zanim ruszą sankcje — porozmawiajmy. Pomożemy zaprojektować warstwę integracyjną tak, by KSeF był w Twoim systemie niewidoczną instalacją hydrauliczną, a nie ciągłym pożarem w księgowości.