Mam własny system i muszę go podpiąć do KSeF 2.0 — jak to zrobić

Gotowe programy do fakturowania obsługują KSeF od dawna. Problem zaczyna się wtedy, gdy faktura nie powstaje w programie do fakturowania, tylko w twoim ERP, w sklepie, w systemie zleceń albo w aplikacji, którą ktoś napisał pod twoją branżę osiem lat temu. Wtedy nikt nie sprzeda ci pudełka. Trzeba podpiąć własny system do API.

Czym integracja własnego systemu z KSeF różni się od kupienia gotowego programu?

Kupując gotowy program, kupujesz cudzy interfejs i cudzą bazę faktur — ludzie przepisują dane albo wgrywają pliki. Integrując własny system, zostawiasz fakturę tam, gdzie powstaje, i dokładasz warstwę, która rozmawia z API KSeF. Różnica jest w odpowiedzialności: mapowanie danych, ponowienia wysyłki i archiwum są po twojej stronie.

Wynikają z tego trzy praktyczne rzeczy:

• Nie ma osobnego procesu „wyeksportuj i wgraj”. Faktura idzie do KSeF w tym samym momencie, w którym system ją zatwierdza.
• Numer KSeF wraca do twojej bazy i staje się częścią dokumentu, a nie zapisem w cudzym panelu.
• Każdy nietypowy przypadek, który twój system dziś obsługuje — korekty, faktury walutowe, sprzedaż w imieniu innego podmiotu, załączniki — musi mieć odwzorowanie w strukturze faktury. Nikt tego za ciebie nie zgadnie.

Ile realnie zostało czasu na integrację z KSeF 2.0?

Obowiązek już działa. Od 1 lutego 2026 obejmuje duże podmioty, czyli te, których sprzedaż brutto w 2024 przekroczyła 200 mln zł. Od 1 kwietnia 2026 obejmuje pozostałych przedsiębiorców. Najmniejsi podatnicy mogą wystawiać faktury poza KSeF do końca 2026, o ile łączna sprzedaż na fakturach nie przekracza 10 000 zł miesięcznie.

Kluczowa jest druga data. W okresie od 1 lutego 2026 do 31 grudnia 2026 nie ma sankcji — organy nie nakładają kar administracyjnych za błędy techniczne, opóźnienia w wysyłce ani pomyłki wynikające z wdrażania nowych procesów. Od 1 stycznia 2027 kary sięgają 100% kwoty VAT z faktury, a dla faktur bez VAT — 18,7% kwoty brutto.

Zostały cztery miesiące. To jest okno na spokojne wdrożenie, a nie powód do zwłoki. Różnica jest zasadnicza: dziś możesz wypuścić integrację, wyłapać na produkcji przypadki, których nie przewidziałeś, i poprawić je bez konsekwencji finansowych. Firma, która zacznie w listopadzie, będzie testować na ostro w styczniu — już pod sankcjami.

Co konkretnie trzeba zbudować, żeby podpiąć własny system do API KSeF?

Integracja to sześć bloków: uwierzytelnienie i tokeny, mapowanie danych na schemat FA(3), wysyłka i odbiór numeru KSeF, obsługa błędów i ponowień, tryb offline/awaryjny oraz archiwizacja z UPO. Każdy z nich da się zrobić źle w sposób, który wychodzi dopiero po miesiącu produkcji.

Uwierzytelnienie i tokeny

System musi umieć uwierzytelnić się w imieniu podmiotu i utrzymać sesję. Tokeny trzeba przechowywać poza kodem i poza repozytorium, z kontrolą dostępu i rotacją. Jeżeli obsługujesz kilka podmiotów — spółki zależne, biuro rachunkowe, sprzedaż w imieniu innego podatnika — od początku projektuj to jako wiele kontekstów, nie jeden globalny token. Przerabianie tego później jest droższe niż zrobienie od razu.

Mapowanie danych na FA(3)

To jest najdłuższa część pracy i większość zespołów ją niedoszacowuje. Schemat faktury ustrukturyzowanej to FA(3). Twoja baza ma własne pola, własne słowniki stawek, własny sposób zapisu rabatów i własne konwencje na dane kontrahenta. Trzeba przejść pole po polu, wskazać źródło, ustalić, co zrobić z brakami, i dopisać walidację przed wysyłką. Faktura odrzucona po stronie API to zawsze gorsza sytuacja niż faktura zatrzymana przez własną walidację.

Osobno warto przejrzeć dokumenty, które w firmie uchodzą za „wyjątki”: korekty do korekt, faktury zaliczkowe, rozliczenia w walucie obcej, pozycje z jednostkami niestandardowymi. To zwykle one wychodzą jako pierwsze po starcie.

Wysyłka i numer KSeF

Wysyłka jest asynchroniczna. System wysyła dokument, dostaje potwierdzenie przyjęcia, a numer KSeF pojawia się później. Twoja aplikacja musi mieć stan dokumentu — na przykład: roboczy, wysłany, przyjęty, odrzucony — i pokazywać go użytkownikowi. Nie da się tego skleić jednym polem typu „wysłano tak/nie”.

Błędy i ponowienia

Rozdziel dwie klasy błędów. Błąd danych (dokument nie przejdzie nigdy, dopóki ktoś go nie poprawi) trafia do kolejki do obsługi przez człowieka. Błąd techniczny (przerwa w łączności, chwilowa niedostępność) idzie do ponowienia z rosnącym odstępem. Kluczowa zasada: ponowienie nie może stworzyć drugiej faktury. Każdy dokument potrzebuje własnego identyfikatora, po którym rozpoznasz, że już go wysłałeś.

Tryb offline i awaryjny

Załóż, że łącze albo API będzie chwilowo niedostępne. System musi umieć wystawić fakturę lokalnie, oznaczyć ją jako oczekującą i dosłać, gdy połączenie wróci — bez ręcznego wklepywania i bez blokowania sprzedaży. To ten sam wzorzec, który stosujemy w autoPolar — aplikacja liczy i zapisuje dane na jachcie bez zasięgu. Kolejka i idempotencja, nic więcej, ale trzeba to zaprojektować, a nie dopisać w panice.

Archiwizacja i UPO

Potrzebujesz trwałego zapisu: wysłany XML, numer KSeF, UPO i data. To jest twój dowód, że faktura poszła. Trzymaj to w formie, którą da się odtworzyć niezależnie od aplikacji — plik plus wpis w bazie, z kopią zapasową. Nie zakładaj, że zawsze pobierzesz to z KSeF.

Jak przetestować integrację z KSeF przed produkcją?

Ministerstwo Finansów udostępniło API KSeF 2.0 do weryfikacji systemów komercyjnych oraz Aplikację Podatnika KSeF 2.0 w wersji Demo. Testujesz na środowisku Demo, a Aplikacji Podatnika używasz jako punktu odniesienia — sprawdzasz, czy dokument wysłany z twojego systemu wygląda tak, jak powinien. Dokumentacja i środowiska są na ksef.podatki.gov.pl.

Sensowny zestaw testowy to nie jedna ładna faktura. To komplet: faktura zwykła, korekta in plus i in minus, zaliczkowa, walutowa, z rabatem, ze zwolnieniem z VAT, z odwrotnym obciążeniem, jeżeli to twój przypadek. Do tego celowe zepsucie danych, żeby zobaczyć, jak system reaguje na odrzucenie, i celowe odcięcie sieci w trakcie wysyłki.

Gotowy integrator czy własna integracja z KSeF — co wybrać?

Kiedy nie warto budować własnej integracji z KSeF?

W kilku sytuacjach to zły pomysł i mówimy to wprost:

• Wystawiasz kilkanaście faktur miesięcznie, wszystkie standardowe. Gotowy program wystarczy i będzie tańszy w utrzymaniu.
• Twój system to popularny ERP w standardowej wersji, dla którego producent wypuścił moduł KSeF. Nie buduj drugi raz tego samego.
• Planujesz wymianę systemu w ciągu roku. Integruj nowy, nie stary.
• Nie masz nikogo, kto po wdrożeniu będzie oglądał kolejkę błędów. Integracja to nie projekt jednorazowy — ktoś musi reagować na odrzucone dokumenty.

Jeżeli którykolwiek punkt pasuje, powiemy to na rozmowie i nie będziemy przekonywać do projektu.

Kto zrobi integrację KSeF z własnym systemem?

Robi to zespół, który potrafi wejść w istniejący kod, przeczytać schemat bazy i zbudować warstwę integracyjną — nie firma, która sprzedaje własny program do fakturowania. RIDOA jest software house'em z Warszawy. Budujemy własne produkty, w których te same mechanizmy działają na co dzień: BARVEA wymienia dane w ustrukturyzowanych formatach IFC i BCF 2.1 według ISO 19650, ClimaBox to firmware, czujniki i aplikacja zbudowane przez ten sam zespół, autoPolar działa w całości offline.

Czego nie robimy: body leasingu, samego hostingu bez projektu i drobnych zleceń poniżej progu budżetu. Robimy integracje, automatyzację i systemy, które mają działać po zakończeniu wdrożenia.

Napisz, jaki masz system i ile faktur miesięcznie wystawiasz. Odpowiadamy zakresem prac i wyceną w jeden dzień roboczy — kontakt. Pełna oferta: co robimy.