Przejdź do treści
Integruj.pl

Integracja z KSeF bez chaosu

Praktyczny przewodnik po e-fakturach ustrukturyzowanych: od schematu FA(3) i uwierzytelniania, po testy, tryb offline i monitoring.

Krajowy System e-Faktur (KSeF) to ogólnopolska platforma Ministerstwa Finansów, w której wystawia się, przechowuje i odbiera faktury w jednolitym, ustrukturyzowanym formacie. Większość firm nie wystawia faktur ręcznie w serwisie rządowym. Faktury powstają w systemie księgowym, ERP, sklepie internetowym, hurtowni albo module magazynowym, dlatego potrzebne jest połączenie tych systemów z KSeF. Właśnie to nazywamy integracją.

Poniżej znajdziesz uporządkowany przegląd tematu: czym jest e-faktura ustrukturyzowana, od kiedy obowiązuje, z jakich elementów składa się integracja i jak zaplanować projekt, żeby uniknąć chaosu tuż przed terminem.

Laptop z kodem programu na ekranie i okularami na klawiaturze, symbol pracy nad integracją systemu z KSeF

Czym jest KSeF i e-faktura ustrukturyzowana #

E-faktura ustrukturyzowana to plik XML zgodny z ustalonym schematem logicznym. Aktualnie obowiązuje schemat FA(3). Nie jest to PDF ani skan: dokument ma z góry określoną strukturę pól, które system może odczytać i zwalidować bez udziału człowieka.

W praktyce oznacza to, że:

  • faktura trafia do KSeF i po pozytywnej weryfikacji otrzymuje unikalny numer KSeF,
  • nadawca dostaje UPO, czyli urzędowe poświadczenie odbioru,
  • nabywca pobiera fakturę z systemu, a nie z wiadomości e-mail,
  • wizualizacja faktury (na przykład w PDF) może istnieć, ale źródłem danych jest plik XML.

Harmonogram obowiązku KSeF #

Obowiązek wprowadzono etapami. Poniższe zestawienie odpowiada przepisom obowiązującym w 2026 r. i ma charakter orientacyjny. Zawsze sprawdź aktualny stan prawny, bo przepisy i komunikaty mogą ulec zmianie.

Kto lub coTermin według obecnych przepisów
Podatnicy, których wartość sprzedaży w 2024 r. przekroczyła 200 mln złod 1 lutego 2026 r.
Pozostali podatnicyod 1 kwietnia 2026 r.
Najmniejsi podatnicy (sprzedaż dokumentowana fakturami do 10 tys. zł miesięcznie)mogą wystawiać faktury poza KSeF do końca 2026 r.
Kary za naruszenia związane z KSeFprzewidziane od 2027 r.

Niezależnie od tego, kiedy zaczynasz wystawiać faktury w KSeF, faktury od kontrahentów mogą pojawiać się w systemie wcześniej. Warto więc zadbać o odbiór faktur zakupowych. Oficjalne informacje publikuje portal ksef.podatki.gov.pl .

Na czym polega integracja z KSeF #

Integracja to połączenie Twojego systemu z interfejsem API KSeF tak, aby faktury były wystawiane, wysyłane, odbierane i archiwizowane automatycznie, w ramach dotychczasowych procesów. Dzięki temu pracownicy nie przepisują danych, a księgowość dostaje komplet dokumentów bez dodatkowych kroków. Integracja z KSeF dla Twojego systemu składa się z kilku elementów.

Zakres prac zależy od tego, jakich systemów używasz:

Rodzaj systemuNa czym zwykle polega integracja
System księgowy lub ERPwystawianie i księgowanie faktur, odbiór dokumentów zakupowych, uzgadnianie statusów
Sklep internetowyautomatyczne wystawianie faktur do zamówień, korekty po zwrotach
Hurtownia lub system magazynowypowiązanie dokumentów magazynowych z fakturami, duże wolumeny, wysyłka wsadowa
Kilka systemów jednocześniewspólna warstwa komunikacji z KSeF, jedno miejsce na uprawnienia i monitoring

Uwierzytelnianie i uprawnienia #

System musi udowodnić swoją tożsamość i działać w imieniu podatnika. W zależności od scenariusza stosuje się:

  • certyfikat KSeF, wygenerowany przez uprawnioną osobę,
  • token powiązany z określonymi uprawnieniami,
  • kwalifikowany podpis lub pieczęć elektroniczną.

Uprawnienia w KSeF nadaje się osobom i systemom osobno, na przykład do wystawiania faktur albo tylko do ich przeglądania. Dobrą praktyką jest przyznawanie najmniejszego zakresu, który wystarcza do pracy.

Wysyłka faktur #

Faktury można przesyłać w dwóch trybach. Sesja interaktywna sprawdza się przy bieżącym wystawianiu pojedynczych dokumentów. Sesja wsadowa pozwala przesłać wiele faktur w jednej paczce, co ma sens przy dużych wolumenach, na przykład po rozliczeniu okresu. Po przyjęciu faktury system zwraca numer KSeF i UPO, które warto zapisywać razem z dokumentem.

Odbiór faktur zakupowych #

Integracja działa w dwie strony. Faktury zakupowe powinny być pobierane z KSeF, przypisywane do właściwego kontrahenta i przekazywane do księgowania. Trzeba też zadbać o to, aby ta sama faktura nie została zaksięgowana dwa razy.

Tryb offline i awaria systemu #

KSeF może być chwilowo niedostępny, a firma nadal musi wystawiać dokumenty. Przepisy przewidują tryby offline i awaryjne, w których fakturę przygotowuje się poza systemem i przesyła później, w terminie określonym w przepisach. Wizualizacja takiej faktury zawiera kod QR umożliwiający jej weryfikację. Integracja powinna obsługiwać te scenariusze, a nie tylko „szczęśliwą ścieżkę”.

Typowe etapy projektu integracji #

  1. Analiza. Inwentaryzacja systemów i procesów fakturowania: sprzedaż, zakupy, korekty, faktury zaliczkowe, kilka podmiotów, kilka oddziałów.
  2. Mapowanie danych. Przełożenie pól z Twojego systemu na strukturę FA(3) oraz ustalenie, skąd brać dane, których dziś brakuje.
  3. Środowisko testowe. Budowa połączenia, uwierzytelnienie i wysyłka faktur próbnych bez wpływu na dane produkcyjne.
  4. Testy. Scenariusze błędów walidacji, korekt, trybu offline, dużych paczek oraz odbioru faktur zakupowych.
  5. Wdrożenie produkcyjne. Nadanie uprawnień, instalacja certyfikatów, przełączenie procesów i przeszkolenie osób, które z nich korzystają.
  6. Monitoring. Kontrola statusów, odrzuconych dokumentów i komunikatów o niedostępności oraz reagowanie na zmiany schematu i interfejsu.

Czy Twoja firma jest gotowa #

Szybki test gotowości

  • Wiem, od kiedy obowiązek dotyczy mojej firmy (sprawdzone w aktualnych przepisach).
  • Mam listę wszystkich systemów, w których powstają lub są księgowane faktury.
  • Wiem, kto w firmie odpowiada za uprawnienia i certyfikaty w KSeF.
  • Moje dane (kontrahenci, stawki, jednostki miary) są kompletne i spójne.
  • Mam plan postępowania na wypadek niedostępności KSeF.
  • Wysyłka i odbiór faktur zostały przetestowane w środowisku testowym.
  • Wiem, gdzie i jak długo przechowuję numery KSeF oraz UPO.

Jeśli na większość punktów odpowiadasz „jeszcze nie”, zacznij od analizy. To najtańszy etap, a pozwala uniknąć kosztownych poprawek w trakcie wdrożenia.

Najczęstsze pytania #

Czy faktura w PDF nadal jest ważna? #

W obszarze objętym KSeF fakturą jest dokument ustrukturyzowany w formacie XML, a PDF może pełnić rolę wizualizacji lub kopii. Poza zakresem obowiązku, na przykład w okresach przejściowych, nadal mogą obowiązywać inne zasady. Sprawdź swoją sytuację w aktualnych przepisach.

Co z fakturami dla konsumentów? #

Obowiązek KSeF dotyczy co do zasady faktur wystawianych podatnikom, a nie osobom prywatnym niebędącym przedsiębiorcami. Szczegóły i wyjątki warto potwierdzić w aktualnych przepisach lub u doradcy podatkowego.

Co zrobić, gdy KSeF nie działa? #

Skorzystaj z trybów przewidzianych na taką okoliczność: offline lub awaryjnego. Warto mieć opisaną procedurę, wiedzieć, kto ją uruchamia, i śledzić komunikaty Ministerstwa Finansów o dostępności systemu.

Czy potrzebuję programisty? #

To zależy od Twojego systemu. Część rozwiązań ma gotowe moduły do obsługi KSeF, a wtedy wystarczy konfiguracja. Jeśli korzystasz z własnych lub mocno rozbudowanych systemów, integracja przez API zwykle wymaga pracy zespołu technicznego.

Ile trwa integracja? #

Zależy od liczby systemów, złożoności procesów fakturowania, jakości danych, dostępności środowisk testowych oraz zespołów po stronie firmy. Dlatego rzetelną ocenę czasu da dopiero analiza.

Zaplanuj integrację #

Im wcześniej zaczniesz, tym spokojniej przejdziesz przez wdrożenie. Zaplanuj integrację z odpowiednim wyprzedzeniem i skontaktuj się z dostawcą lub zespołem odpowiedzialnym za Twoje systemy fakturowania. Zakres obowiązków i terminy zawsze weryfikuj w oficjalnych źródłach.