KSeF 2.0 i FA(3): checklista integracji na 2026 (i jak przejść z FA(2) bez przestojów w fakturowaniu)

Większość tekstów o KSeF 2.0 jest pisana z myślą o księgowej, która chce wiedzieć, od kiedy musi wystawiać faktury w systemie. To ważne pytanie, ale jeśli odpowiadasz za integrację albo zlecasz ją programiście czy agencji, interesuje Cię co innego: które linijki konfiguracji, mapowania XML i obsługi tokenów przestaną działać z dniem przejścia na nową strukturę. Przy pierwszych wdrożeniach KSeF, które robiliśmy dla klientów, problem rzadko leżał w przepisach. Leżał w trzech miejscach kodu, o których nikt nie pomyślał wcześniej: sztywno zaszytym tokenie w konfiguracji, braku obsługi limitów API przy wysyłce hurtowej i walidacji XSD, która w teście przechodziła, a na produkcji odrzucała co dziesiątą fakturę.

Dlaczego to nie jest wyłącznie temat dla księgowości

Jeśli faktury u Ciebie wystawia jedna osoba ręcznie w systemie finansowo-księgowym, przejście na FA(3) to w dużej mierze kwestia aktualizacji oprogramowania dostawcy. Problem zaczyna się tam, gdzie faktura jest generowana automatycznie: ze sklepu internetowego, z systemu ERP po zamówieniu, z CRM po zamknięciu transakcji, albo masowo z biura rachunkowego obsługującego kilkadziesiąt firm. W takich przypadkach integracja z KSeF nie jest jednym kliknięciem „aktualizuj”, tylko kawałkiem kodu, który trzeba przetestować na realnych danych, zanim pójdzie na produkcję.

Harmonogram MF ma tu znaczenie techniczne, nie tylko prawne. Duzi podatnicy, u których wartość sprzedaży przekroczyła 200 mln zł, wchodzą do systemu od 1 lutego 2026. Pozostali czynni podatnicy VAT od 1 kwietnia 2026. Podatnicy zwolnieni podmiotowo i przedmiotowo oraz firmy wystawiające niewielkie wolumeny faktur mają czas do 1 stycznia 2027. Te terminy już raz się przesuwały (pierwotnie KSeF miał być obowiązkowy w 2024 roku), więc zakładamy pewien margines bezpieczeństwa, ale nie liczyłbym na kolejną odwłokę jako plan A. Jeśli Twoja firma mieści się w pierwszym progu, realistyczny termin na zakończenie testów integracji to listopad-grudzień 2025, nie styczeń 2026.

FA(2) kontra FA(3): co faktycznie zmienia się w strukturze

To jest ta część, którą programiści wdrażający integrację najczęściej bagatelizują, zakładając, że „to tylko nowa wersja schematu XSD, podmienimy plik i działa”. W praktyce zmiana struktury logicznej faktury oznacza, że pola, które w FA(2) były opcjonalne, w FA(3) mogą być wymagane w określonych scenariuszach, a mapowanie danych z ERP trzeba przejrzeć pole po polu, nie tylko zaktualizować bibliotekę.

Co to oznacza dla Twojego mapowania danych

Jeśli masz mapper, który konwertuje dane z ERP lub platformy e-commerce na XML zgodny z FA(2), nie podmieniaj samego pliku schematu i nie zakładaj, że testy jednostkowe sprzed roku wciąż mają sens. Przejdź przez minimum 20-30 realnych typów faktur, jakie wystawia Twoja firma: korekty, faktury zaliczkowe, faktury do paragonu, faktury w walucie obcej, faktury z rabatem pozycyjnym. Przy jednym z wdrożeń, które obserwowaliśmy na starcie, okazało się, że mapper poprawnie obsługiwał standardową fakturę sprzedażową, ale błędnie liczył podstawę opodatkowania przy fakturze korygującej in minus z wieloma pozycjami, bo logika korekty w nowym schemacie inaczej odnosi się do faktury pierwotnej. Takie błędy wychodzą dopiero na realnych danych, nie na przykładach z dokumentacji.

Autoryzacja: koniec sztywno zaszytego tokenu

W KSeF 1.0 większość integracji budowano wokół tokenu wygenerowanego raz przez osobę uprawnioną i wklejonego do konfiguracji systemu. Działało to, dopóki osoba nie zmieniła pracy albo token nie wygasł w nieoczekowanym momencie, blokując wysyłkę faktur w środę rano. KSeF 2.0 kładzie większy nacisk na uwierzytelnianie na poziomie podmiotu, czyli pieczęć kwalifikowaną przypisaną do firmy, a nie do konkretnego pracownika. To dobra zmiana dla ciągłości działania, ale wymaga rewizji procesu: kto w firmie odpowiada za certyfikat, gdzie jest przechowywany, jaki jest plan rotacji i kto dostaje alert 30 dni przed wygaśnięciem.

Środowisko testowe ksef-test: różnice i pułapki

Ministerstwo Finansów udostępnia odrębne środowisko testowe dla wersji 2.0, z własnymi danymi referencyjnymi i certyfikatami testowymi, innymi niż te używane do tej pory przy FA(2). Pierwszy błąd, jaki widzimy w zgłoszeniach klientów, to założenie, że skoro integracja przechodziła testy w starym środowisku, to w nowym zadziała tak samo, bo „to ten sam system, tylko nowsza wersja”. Nie zadziała automatycznie. Trzeba wygenerować nowe dane testowe, przepiąć punkt dostępowy API i powtórzyć cały cykl testów, łącznie z obsługą błędów odrzucenia i Urzędowym Poświadczeniem Odbioru. Drugi błąd to testowanie wyłącznie happy path, czyli faktury, która na pewno przejdzie. W środowisku testowym warto celowo wysłać kilka faktur z błędami: brakującym NIP-em kontrahenta, nieprawidłową sumą kontrolną, złym formatem daty, żeby sprawdzić, czy Twój system poprawnie łapie odrzucenie i nie wysyła faktury do klienta, zanim dostanie potwierdzenie z KSeF. To jest różnica między integracją, która działa w demie, a taką, która przetrwa prawdziwy ruch.

Limity zapytań API i wersjonowanie integracji

KSeF nakłada limity liczby zapytań w określonym przedziale czasu, naliczane w kontekście sesji i NIP-u. Dla firmy wystawiającej kilkanaście faktur dziennie to w praktyce nieodczuwalne. Dla sklepu internetowego generującego kilkaset zamówień w godzinach szczytowych, albo biura rachunkowego wysyłającego faktury hurtowo na koniec miesiąca za kilkudziesięciu klientów, limity trzeba uwzględnić w architekturze: kolejkowanie wysyłek, mechanizm retry z narastającym opóźnieniem (exponential backoff) zamiast natychmiastowego ponawiania, oraz plan na sytuację, w której API KSeF jest czasowo niedostępne.

Wersjonowanie API to drugi element, który łatwo przeoczyć. Endpointy obsługujące FA(2) nie znikną z dnia na dzień, ale po okresie przejściowym zostaną wyłączone lub ograniczone na rzecz wersji obsługującej FA(3). Jeśli Twoja integracja jest hostowana przez zewnętrznego dostawcę oprogramowania, zapytaj wprost, w jakim terminie planuje przełączenie na nową wersję API i czy będzie można przez jakiś czas wysyłać faktury w obu formatach równolegle. Jeśli piszesz integrację sama lub zlecasz ją programiście, zaplanuj przełącznik w kodzie, który pozwala przejściowo wysyłać do obu środowisk, zamiast robić migrację „na żywca” jednego dnia.

Checklist: co fizycznie trzeba zrobić

To jest lista, którą dajemy klientom przed rozpoczęciem prac nad migracją. Nie wszystkie punkty dotyczą każdej firmy, ale żaden nie jest opcjonalny dla integracji wysyłającej faktury automatycznie.

• Zaktualizuj schemat XSD w swoim mapperze na FA(3) i przejrzyj pole po polu różnice względem FA(2), zamiast zakładać kompatybilność wsteczną.
• Przetestuj na realnych typach faktur z Twojej firmy: standardowe, korygujące, zaliczkowe, w walucie obcej, z rabatem pozycyjnym, do paragonu.
• Zrewiduj mechanizm autoryzacji: kto ma dostęp do certyfikatu, jak wygląda plan rotacji, co się stanie, jeśli odpowiedzialna osoba odejdzie z firmy.
• Zaimplementuj obsługę limitów API: kolejkowanie, retry z opóźnieniem, logowanie odrzuceń zamiast cichego pomijania błędów.
• Przygotuj plan awaryjny na niedostępność KSeF, zgodnie z zasadami trybu offline przewidzianymi w przepisach, żeby sprzedaż nie stawała w miejscu.
• Ustal z biurem rachunkowym lub działem księgowości, kto po migracji odpowiada za monitorowanie odrzuconych faktur i ich korektę.

Jeśli po przejściu checklisty widzisz, że sama wysyłka faktur do KSeF to tylko fragment większego procesu (wystawianie, zatwierdzanie, archiwizacja, rozliczanie z klientem), warto spojrzeć na to szerzej niż sam schemat XML. Opisaliśmy to dokładniej przy okazji automatyzacji obiegu faktur, bo integracja z KSeF rzadko ma sens jako izolowany projekt, oderwany od reszty procesu księgowego.

Gdzie to się łączy z resztą automatyzacji firmy

Biura rachunkowe obsługujące wiele podmiotów są w najtrudniejszej sytuacji, bo muszą zapewnić zgodność z FA(3) jednocześnie dla kilkudziesięciu klientów, z różnymi systemami źródłowymi i różnymi terminami wejścia w obowiązek. Jeśli Twoja firma jest właśnie w takiej sytuacji, sensowniej jest zbudować jeden wspólny mechanizm integracyjny z warstwą mapowania per klient, niż powielać osobną integrację dla każdego podmiotu. Piszemy o tym szerzej przy automatyzacji procesów w biurze rachunkowym, bo skala zmienia podejście do projektu: to, co dla jednej firmy jest jednorazową aktualizacją, dla biura obsługującego 60 klientów jest projektem wymagającym osobnej architektury.

Firmy e-commerce mają inny problem: wolumen i presja czasu. Faktura musi powstać i trafić do KSeF niemal natychmiast po zamówieniu, a klient oczekuje dokumentu od razu, nie następnego dnia. Tu limity API i obsługa błędów nabierają znaczenia praktycznego, nie teoretycznego.