KSeF

Zastosowanie

Moduł KSeF został zaimplementowany w aplikacji w związku z wprowadzanymi zmianami przepisów prawa podatkowego. Nowe przepisy narzucają obowiązek zmiany systemu fakturowania z modelu faktur papierowych i elektronicznych (model post-audit) na model faktur ustrukturyzowanych (model clearance).

Ważne: Od 1 lutego 2026 r. obowiązuje nowa wersja API KSeF 2.0, która wprowadza znaczące zmiany w procesie uwierzytelniania, zarządzania uprawnieniami oraz technicznych aspektach integracji. Niniejsza dokumentacja została zaktualizowana zgodnie z wymaganiami wersji 2.0.

Każda faktura będzie zapisywana w formacie XML, zgodnym ze strukturą logiczną e-faktury. Wystawione e-faktury będą przesyłane elektronicznie do Krajowego Systemu e-Faktur (KSeF), gdzie zostaną zarejestrowane i zarchiwizowane. Dzięki wprowadzeniu modułu KSeF do aplikacji możliwe jest przejście przez cały proces w efektywny i bezpieczny sposób.

Moduł KSeF posiada wiele wbudowanych funkcjonalności, które mogą zostać wykorzystane w kilku celach:

• Zachowania zgodności z przepisami - proces wysyłania faktur do KSeF został wyznaczony zgodnie z nowymi przepisami prawa podatkowego (zmiana systemu fakturowania, dostosowanie formy uwierzytelniania, zachowanie struktury i formatu e-faktur). Pozwala to na uniknięcie błędów związanych z ręcznym przesyłaniem faktur.

• Automatyzacji procesu wysyłki faktur - zaakceptowane i poprawnie zwalidowane faktury będą mogły być wysyłane automatycznie do KSeF na podstawie ustawionej konfiguracji. Ingerencja operatora nie będzie wymagana do czasu wystąpienia błędu (np. walidacji faktur). Pozwala o na zwiększenie efektywności procesu i ograniczenie nakładu pracy operatora.

• Zachowania bezpieczeństwa danych - dzięki wprowadzonemu systemowi uwierzytelniania na podstawie NIP-u i certyfikatów KSeF, przesyłane dane wrażliwe na fakturach są bezpieczne. Nie ma możliwości, aby osoby postronne uzyskały dostęp do przekazywanych informacji. System zewnętrzny wymaga przejścia procesu uwierzytelnienia i autoryzacji, a dopiero wówczas uzyskuje się dostęp dodanych. Oprócz tego, możliwe jest nałożenie ograniczeń wewnętrznych przez przyznanie odpowiednich uprawnień do panelu KSeF jedynie dla wybranych operatorów.

• Raportowania o błędach - jeżeli system napotka problemy w trakcie walidacji lub wysyłki faktur do KSeF (w wyniku awarii wewnętrznej lub zewnętrznej), to faktura otrzyma status błędu, który może wymagać ingerencji operatora. Każdy błąd będzie informować o jego przyczynie i zalecanym postępowaniu, co pozwoli na odpowiednią reakcję operatora.

• Integracji z innymi modułami - moduł KSeF jest zintegrowany z innymi modułami aplikacji, takimi jak księgowość, czy sprzedaż. Dzięki temu e-faktury są generowane automatycznie na podstawie dokonanych transakcji, a następnie przekazywane do księgowości.

• Walidacji faktur - faktury są walidowane na podstawie przyjętego szablonu. Błędnie zwalidowane faktury będą otrzymywać status błędu, a ich przesył zostanie wstrzymany, do czasu rozwiązania problemu. Takie rozwiązanie pozwala na uniknięcie możliwości przesyłania do systemu KSeF faktur o nieprawidłowej strukturze oraz przyspieszy wykrywanie ewentualnych błędów.

• Archiwizacji wysłanych faktur - każda wysłana e-faktura do KSeF zostanie zapisana w przeznaczonym do tego folderze. Dokumenty będą w nim przechowywane do czasu ich ręcznego usunięcia. Faktury będą przechowywane w bezpieczny i zorganizowany sposób, tak aby można je było łatwo odnaleźć, odtworzyć oraz analizować w przyszłości. Jest to kluczowy element zarządzania fakturami w biznesie, zwłaszcza w kontekście spełniania wymogów prawnych i audytów.

• Monitorowania statusu przesłanych faktur - każda przesłana e-faktura do KSeF otrzyma odpowiedni status. Aplikacja pozwala na pobieranie statusów przetworzenia e-faktur bezpośrednio z KSeF. Przykładowo, jeśli deklaracja zostanie odrzucona przez system, to użytkownik otrzyma o tym informację, dzięki czemu będzie mógł szybko zareagować i poprawić błędy.

• Weryfikacji historii wykonanych operacji na fakturze - aplikacja pozwala na zweryfikowanie każdej operacji, która została wykonana na e-fakturze z uwzględnieniem danych wykonawcy działania oraz daty wykonania. Dodatkowo, w przypadku wystąpienia błędu, każdy z nich będzie opisany przyczyna oraz zalecanym postępowaniem. Dzięki temu każda niezgodność będzie mogła zostać szybko i skutecznie zidentyfikowana.

• Uzupełnienia parametrów faktury - system umożliwia uzupełnienie wybranych dodatkowych parametrów XML dla faktur, m.in. P_19A, P_19B i P_19C dla zwolnienia z podatku.

• Obsługi procedury marży VAT - system automatycznie obsługuje różne typy procedur marży VAT zgodnie z wymaganiami KSeF. Dla faktur oznaczonych jako marżowe, system automatycznie generuje odpowiednie znaczniki XML (P_PMarzy, P_PMarzy_2, P_PMarzy_3_1, P_PMarzy_3_2, P_PMarzy_3_3) w zależności od wybranego typu marży. Obsługiwane typy to: towary używane (MR_UZ), usługi turystyki (MR_T), dzieła sztuki (MR_DS) i przedmioty kolekcjonerskie (MR_PK).

• Generowania kodów QR na wydrukach faktur - system automatycznie dodaje kody QR do wydruków faktur KSeF, które zawierają linki do faktury w systemie KSeF. Kody są drukowane tylko dla faktur z wygenerowanym plikiem XML. W trybie offline drukowane są dwa kody QR (z numerem referencyjnym i certyfikatem), a dla faktur wysłanych - jeden kod QR z numerem referencyjnym.

• Wizualizacji XML faktury - system umożliwia podgląd wygenerowanego pliku XML faktury w formacie HTML na szablonie ministerstwa. Funkcjonalność pozwala na czytelne wyświetlenie zawartości XML bez możliwości modyfikacji szablonu, co ułatwia weryfikację poprawności danych przed wysłaniem do KSeF.

• Ulepszonego panelu zarządzania KSeF - system oferuje ulepszony panel zarządzania z lepszym filtrowaniem statusów, możliwością wyświetlania zablokowanych faktur oraz dostępem do panelu bezpośrednio z faktur sprzedaży. Panel umożliwia łatwiejsze zarządzanie fakturami i szybsze wykonywanie operacji.

Reasumując, wprowadzenie modułu pozwala na przejście przez cały proces przesyłania faktur ustrukturyzowanych do KSeF, spełniając przy tym szereg sprecyzowanych wymagań prawnych bez konieczności korzystania z systemów zewnętrznych.

Podstawowe pojęcia

W niniejszej instrukcji pojawia się szereg pojęć, wykorzystywanych w module KSeF. W celu lepszego zrozumienia obszaru, najistotniejsze z nich zostały przedstawione w tym rozdziale.

• Krajowy System e-Faktur (KSeF) - ogólnokrajowy system teleinformatyczny, służący do wystawiania, otrzymywania i przechowywania faktur ustrukturyzowanych. System pozwala również na oznaczanie przesłanych faktur numerem identyfikacyjnym przydzielonym przez sam program oraz walidację faktur.

• Model fakturowania post-audit - dotychczasowy system fakturowania, w którym płatności za faktury są dokonywane zanim przeprowadzony zostanie dokładny audyt tych faktur. Pozwala na wysyłanie i odbieranie faktur w sposób swobodny z obowiązkiem udowodnienia ich poprawności przez 10 lat za pomocą różnych form dokumentowania. Audyt taki ma na celu zweryfikowanie dokładności i zgodności faktur z umowami oraz innymi dokumentami źródłowymi.

• Model fakturowania clearance - nowy system fakturowania, w którym faktury są przekazywane przez centralny organ lub platformę do weryfikacji przed przekazaniem ich dalej do płatnika lub finalnego odbiorcy. Ten model jest często stosowany w kontekście elektronicznego fakturowania w wielu krajach, gdzie rząd chce mieć kontrolę nad procesem wystawiania faktur w celu zapobiegania oszustwom podatkowym i ułatwienia procesu zbierania podatków.

• Faktura ustrukturyzowana - elektroniczna forma faktury, w której wszystkie dane są przedstawione w ustalonym, strukturalnym formacie. Oznacza to, że poszczególne elementy faktury (takie jak data wystawienia, nazwa sprzedawcy, adres, pozycje faktury, stawki podatkowe itp.) są prezentowane w sposób spójny i są łatwo identyfikowalne dla oprogramowania przetwarzającego te dane. Ma format XML, który jest zgodny ze strukturą logiczną e-faktury (FA_VAT).

• Struktura logiczna - sposób organizacji i przedstawiania danych na fakturze w taki sposób, aby były one spójne, łatwo identyfikowalne i zrozumiałe dla systemów komputerowych. Struktura ta definiuje, w jaki sposób poszczególne elementy są organizowane i powiązane ze sobą na dokumencie.

• Walidacja - proces sprawdzania poprawności i spójności danych zawartych w fakturze elektronicznej. Celem walidacji jest zapewnienie, że faktura jest zgodna z określonymi standardami, spełnia określone wymagania i jest wolna od błędów.

• Token dostępowy (accessToken) - token JWT (JSON Web Token) wykorzystywany do autoryzacji operacji w API KSeF 2.0. Ma ograniczony czas ważności (kilkanaście minut) i może być odświeżany przy użyciu tokena odświeżającego (refreshToken).

• Token odświeżający (refreshToken) - token umożliwiający odświeżenie tokena dostępowego bez ponownego uwierzytelnienia. Ma znacznie dłuższy okres ważności (do 7 dni) i może być używany wielokrotnie.

• Certyfikat KSeF - cyfrowe poświadczenie tożsamości podmiotu, wydawane przez system KSeF na wniosek użytkownika. Dostępne są dwa typy: Authentication (do uwierzytelniania) i Offline (wyłącznie do wystawiania faktur w trybie offline). Certyfikaty KSeF są podstawową formą autoryzacji w systemie KSeF 2.0.

• Sesja interaktywna - tryb wysyłki pojedynczych faktur do KSeF, gdzie każda faktura jest przesyłana osobno w czasie rzeczywistym.

• Sesja wsadowa - tryb wysyłki wielu faktur w pojedynczym pliku ZIP, umożliwiający efektywne przetwarzanie dużej liczby dokumentów.

• UPO (Urzędowe Poświadczenie Odbioru) - formalne potwierdzenie przetworzenia faktury w KSeF, wydawane dla całej sesji.

• Limit wywołań (rate limiting) - precyzyjny mechanizm ograniczeń liczby wywołań API w zadanych przedziałach czasowych (na sekundę, minutę, godzinę, dobę). Limity są stosowane w celu zapewnienia sprawiedliwego użycia zasobów, zapobiegania nadużyciom oraz utrzymania stabilności i dostępności usługi dla wielu użytkowników. Jeśli zostanie przekroczony, to kolejne zapytania są odrzucane lub opóźnione do czasu, aż licznik wywołań zostanie zresetowany. W KSeF 2.0 limity są zróżnicowane w zależności od środowiska (testowe ma limity mniej restrykcyjne niż produkcyjne) oraz dostosowane do charakteru operacji - dla endpointów chronionych limity stosowane są per token JWT, a dla endpointów otwartych per adres IP klienta. System zwraca kod błędu HTTP 429 (Too Many Requests) wraz z informacją o czasie oczekiwania, co eliminuje konieczność odczekiwania stałego czasu znanego z wersji 1.0.

Wymagania

Przed przystąpieniem do instalacji modułu KSeF w aplikacji, konieczne jest spełnienie szeregu wymagań systemowych oraz biznesowych. Spełnienie następujących kryteriów jest niezbędne do prawidłowego korzystania z systemu:

1) Uwierzytelnienie w KSeF 2.0 - konieczne jest posiadanie certyfikatu KSeF typu Authentication do uwierzytelnienia w systemie. Proces uwierzytelniania opiera się na nowym modelu JWT z tokenami dostępowymi i odświeżającymi;

2) Zarządzanie uprawnieniami - w KSeF 2.0 wprowadzono zaawansowany mechanizm zarządzania uprawnieniami, który wymaga odpowiedniej konfiguracji dostępu dla użytkowników i podmiotów. Konieczne jest nadanie odpowiednich uprawnień (np. InvoiceWrite, InvoiceRead, CredentialsManage);

3) Szyfrowanie faktur - w KSeF 2.0 szyfrowanie wszystkich faktur (zarówno w trybie interaktywnym, jak i wsadowym) jest obowiązkowe. Każda faktura musi być zaszyfrowana lokalnie za pomocą klucza AES-256-CBC;

4) Certyfikaty KSeF - opcjonalnie można wystąpić o certyfikat KSeF, który ułatwia uwierzytelnianie i umożliwia wystawianie faktur w trybie offline;

5) Przygotowanie przestrzeni dyskowej - do której będzie miał dostęp serwer Neos. Będą tu zapisywane, przechowywane i archiwizowane wszystkie pliki, które zostaną wygenerowane w trakcie procesu (faktury XML, pliki UPO, logi operacji, itp.);

6) Przygotowanie konfiguracji dla faktur zaliczkowych i korekt faktur zaliczkowych - przy wystawianiu faktur zaliczkowych należy pamiętać o tym, że na dokumencie muszą zostać wskazane towary lub usługi, które są przedmiotem zaliczki. Pozycje zostaną automatycznie przeniesione z zamówienia na fakturę zaliczkową za pomocą funkcji fakturowania. W przypadku, gdy faktura zaliczkowa jest wystawiana ręcznie, należy również ręcznie dodać do niej fakturowane pozycje;

7) Przygotowanie konfiguracji dla niestandardowych faktur korygujących rabaty zbiorcze za obroty klienta za miniony kwartał lub półrocze. W takim przypadku należy przygotować indywidualne rozwiązanie, pozwalające na wskazanie faktur korygowanych na danej fakturze z rabatem zbiorczym, do którego klient będzie mógł dopisać swoje zmiany. Na podstawie ref faktury z rabatem zbiorczym powinny zostać zwrócone informacje o fakturach, które będą korygowane. Niniejsza konfiguracja jest wymagana tylko, w przypadku gdy dane przedsiębiorstwo obsługuje takie dokumenty;

8) Zmiana procesu obsługi sprzedaży, wynikająca z nowych przepisów prawa podatkowego (przejście z systemu wydruków faktur na system e-faktur oraz zarządzanie wysyłką e-faktur do KSeF).

Uwaga: Należy pamiętać, że aktualizacje w wykorzystywanej technologii przez KSeF mogą wymagać wprowadzenia zmian w aplikacji np. podmiany plików XSD w konfiguracji KSeF. Migracja na KSeF 2.0 wymaga dostosowania implementacji po stronie systemów zewnętrznych.

Przygotowania formalne do obsługi KSeF

Przed przystąpieniem do korzystania z systemu KSeF, niezbędne jest otrzymanie i rozdysponowanie odpowiednich uprawnień w systemie zewnętrznym. Są to potrzeby formalne wymagane przez przepisy prawa podatkowego, które mają na celu zachowanie bezpieczeństwa informacji i przyznanie uprawnień o odpowiednim zakresie dla właściwych użytkowników.

Przygotowania formalne do obsługi KSeF obejmuje następujące etapy:

• nabycie pierwotnych uprawnień właścicielskich (tylko w przypadku gdy podmiot posiada kwalifikowany podpis elektroniczny, który nie zawiera w sobie NIP i PESEL);

• przydzielenie uprawnień do wykonywania poszczególnych operacji w KSeF przez użytkownika z uprawnieniami pierwotnymi;

• uzyskanie certyfikatów KSeF przez uprawnionego użytkownika.

Pierwotne uprawnienia właścicielskie

Do obsługi systemu KSeF niezbędne jest posiadanie pierwotnych uprawnień właścicielskich, które pozwalają na pełne zarządzanie danymi i fakturami w systemie. W zależności od statusu podatnika, uprawnienia te są uzyskiwane w różny sposób, tj.:

1) w przypadku podatników, którzy są osobami fizycznymi pierwotne uprawnienie o charakterze właścicielskim jest automatycznie przypisywane do osoby będącej podatnikiem. Taka osoba nie musi zgłaszać dodatkowych wniosków do urzędu skarbowego w celu uzyskania uprawnień. Autoryzacja do KSeF przebiega z wykorzystaniem Podpisu Zaufanego (ePUAP) lub kwalifikowanego podpisu elektronicznego. W szczególnych przypadkach, gdzie przedsiębiorca nie ma możliwości autoryzacji elektronicznej, może złożyć zawiadomienie ZAW-FA do urzędu skarbowego (właściwego dla podmiotu).

2) W przypadku podatników niebędących osobami fizycznymi, którzy posiadają elektroniczną pieczęć kwalifikowaną zawierającą NIP, istnieje możliwość korzystania z KSeF na podstawie pierwotnych uprawnień właścicielskich, bez konieczności składania dodatkowych wniosków do urzędu skarbowego. W szczególnych przypadkach, gdzie przedsiębiorca nie ma możliwości autoryzacji elektronicznej, może złożyć zawiadomienie ZAW-FA do urzędu skarbowego (właściwego dla podmiotu).

3) W przypadku podatników niebędących osobami fizycznymi, którzy posiadają elektroniczną pieczęć kwalifikowaną niezawierającą NIP i PESEL konieczne jest złożenie zawiadomienia ZAW-FA (tzw. odcisk palca podpisu) do urzędu skarbowego (właściwego dla podmiotu). Zmiana czy odnowienie podpisu, na kolejny podpis niezawierający NIP i PESEL będzie wymagać złożenia nowego zawiadomienia ZAW-FA.

Dla dwóch pierwszych przypadków nie ma konieczności wykonywania dodatkowych kroków w celu uzyskania pierwotnych uprawnień właścicielskich. Po zalogowaniu się do KSeF, użytkownik z uprawnieniami właścicielskimi będzie posiadał rozszerzony widok panelu i będzie mógł rozdysponować kolejne uprawnienia dla innych użytkowników. W ostatnim przypadku konieczne jest złożenie zawiadomienia ZAW-FA do urzędu skarbowego przed przystąpieniem do obsługi KSeF.

Składanie zawiadomienia ZAW-FA

Zawiadomienie ZAW-FA służy do urzędowego uzyskania uprawnień pierwotnych, niezbędnych do korzystania z platformy KSeF. Zawiadomienie musi zostać złożone, w przypadku gdy podatnik niebędący osobą fizyczną posiada elektroniczną pieczęć kwalifikowaną niezawierającą NIP-u i PESEL-u lub gdy podatnik nie posiada możliwości uwierzytelnienia się w sposób elektroniczny.

W zawiadomieniu wskazuje się osobę, która otrzyma lub utraci uprawnienia pierwotne do obsługi KSeF. Formularz pozwala na zgłoszenie tylko jednej osoby, która otrzyma uprawnienia właścicielskie. Możliwe jest nadanie kolejnych rozszerzonych uprawnień innym użytkownikom w formie elektronicznej, bezpośrednio przez platformę KSeF. Tego typu uprawnienia może przyznawać tylko użytkownik, który posiada upoważnienie do ich nadawania.

Wypełnione zawiadomienie ZAW-FA należy przesłać do urzędu skarbowego w formie papierowej lub w formie elektronicznej. Złożenie zawiadomienia ZAW-FA w formie elektronicznej obejmuje kilka etapów:

• wypełnienie formularza ZAW-FA i wgranie skanu na dysk lub uzupełnienie go w formie elektronicznej przy pomocy komercyjnego oprogramowania;

• złożenie podpisu elektronicznego na formularzu ZAW-FA;

• wysłanie podpisanego formularza ZAW-FA do urzędu skarbowego (właściwego dla podmiotu);

• (opcjonalne) załączenie do formularza ZAW-FA odpisu z KRS (w przypadku spółek) lub CEIDG (w przypadku przedsiębiorców) - dzięki temu proces przetwarzania wniosku przez urząd skarbowy zostanie przyspieszony;

Dokładny czas przetwarzania ZAW-FA może różnić się w zależności od urzędu skarbowego, obecnej ilości złożonych wniosków i formy dostarczenia wniosku. Przetwarzanie przesłanego wniosku ZAW-FA elektronicznie jest znacząco szybsze i średnio zajmuje tydzień. Aby przyspieszyć postępowanie (do około 2 dni), zaleca się kontakt telefoniczny z właściwym urzędem skarbowym, po elektronicznym przesłaniu ZAW-FA, w celu potwierdzenia jego otrzymania. Należy skontaktować się z sekretariatem właściwego urzędu, który przekieruje interesariusza do odpowiedniego działu. Przy weryfikacji konieczne jest podanie danych identyfikacyjnych podmiotu, tj.: nazwa firmy, NIP oraz imię i nazwisko osoby wymienionej we wniosku.

Uwierzytelnianie w KSeF 2.0

W KSeF 2.0 wprowadzono nowy model uwierzytelniania, który zastąpił dotychczasowy proces logowania. Uwierzytelnianie zostało wydzielone jako osobny proces, niezależny od inicjalizacji sesji, co umożliwia wielokrotne użycie certyfikatu do tworzenia wielu sesji.

Dostępne metody uwierzytelniania:

1. Z wykorzystaniem kwalifikowanego podpisu elektronicznego - uwierzytelnianie za pomocą certyfikatu kwalifikowanego

Korzyści nowego modelu: - Możliwość wielokrotnego użycia certyfikatu do tworzenia wielu sesji - Lepsze bezpieczeństwo dzięki automatycznemu odświeżaniu tokenów JWT - Możliwość automatyzacji procesu uwierzytelniania

Uwierzytelnianie z wykorzystaniem kwalifikowanego podpisu elektronicznego

W KSeF 2.0 uwierzytelnianie z wykorzystaniem kwalifikowanego podpisu elektronicznego przebiega w uproszczony sposób:

Wymagania: - Aktywne konto na Profilu Zaufanym (ePUAP) lub konto w banku obsługującym Profil Zaufany - Certyfikat kwalifikowany osoby fizycznej (zawierający numer PESEL lub NIP) - Certyfikat kwalifikowany organizacji (pieczęć firmowa z numerem NIP)

Proces uwierzytelniania: 1. System automatycznie pobiera wyzwanie uwierzytelniające 2. Przygotowuje dokument XML z danymi uwierzytelniającymi 3. Podpisuje dokument cyfrowo za pomocą dostępnego certyfikatu 4. Przesyła podpisany dokument do systemu KSeF 5. Otrzymuje token dostępowy umożliwiający korzystanie z API

Korzyści: - Bezpieczne uwierzytelnianie zgodne z wymogami prawnymi - Możliwość wielokrotnego użycia certyfikatu - Automatyczne odświeżanie tokenów JWT

Uprawnienia systemowe

Dostęp do modułu KSeF w aplikacji wymaga posiadania odpowiednich uprawnień systemowych oraz licencji w pliku licencyjnym aplikacji.

Wymagania licencyjne

Moduł KSeF został podzielony na dwa niezależne komponenty:

• KSEFS - moduł KSeF Sprzedaż (obsługa faktur sprzedaży)
• KSEFZ - moduł KSeF Zakupy (obsługa faktur zakupu)

Ważne: Jeśli nie posiadasz odpowiedniej licencji dla danego komponentu, funkcjonalności KSeF nie będą dostępne w aplikacji. W takim przypadku skontaktuj się z administratorem systemu w celu uzyskania odpowiedniej licencji.

Sprawdzanie dostępności modułu

Jeśli masz problemy z dostępem do funkcjonalności KSeF:

1. Sprawdź czy posiadasz odpowiednie uprawnienia systemowe do modułu KSeF
2. Skontaktuj się z administratorem w celu weryfikacji licencji
3. Upewnij się, że potrzebujesz dostępu do odpowiedniego komponentu (sprzedaż lub zakupy)

Uwierzytelnianie certyfikatem KSeF

W KSeF 2.0 możliwe jest również uwierzytelnianie za pomocą certyfikatu KSeF typu Authentication, który stanowi alternatywę dla podpisu elektronicznego.

Wymagania: - Wcześniej uzyskany certyfikat KSeF typu Authentication z odpowiednimi uprawnieniami - Bezpieczne przechowywanie certyfikatu w systemie

Proces uwierzytelniania: 1. System automatycznie przygotowuje dane uwierzytelniające z certyfikatu KSeF 2. Przesyła dane wraz z certyfikatem do systemu KSeF 3. Sprawdza status operacji uwierzytelnienia 4. Otrzymuje token dostępowy umożliwiający korzystanie z API

Korzyści uwierzytelniania certyfikatem KSeF: - Uproszczony proces uwierzytelniania - Możliwość automatyzacji procesu - Brak konieczności posiadania certyfikatu kwalifikowanego dla każdej operacji - Możliwość wielokrotnego użycia certyfikatu - Łatwiejsze zarządzanie uprawnieniami

Uwaga: Certyfikat KSeF pełni rolę poufnego sekretu uwierzytelniającego i należy przechowywać go wyłącznie w zaufanym i bezpiecznym magazynie.

Zarządzanie uprawnieniami w KSeF 2.0

W KSeF 2.0 wprowadzono zaawansowany mechanizm zarządzania uprawnieniami, który stanowi fundament bezpiecznego i zgodnego z przepisami korzystania z systemu przez różne podmioty.

Cele zarządzania uprawnieniami: - Bezpieczeństwo danych – ograniczenie dostępu do informacji tylko do osób i podmiotów, które są do tego formalnie uprawnione - Zgodność z przepisami – zapewnienie, że operacje są wykonywane przez właściwe jednostki zgodnie z wymogami ustawowymi - Audytowalność – każda operacja związana z nadaniem lub odebraniem uprawnień jest rejestrowana i może być poddana analizie

Kto nadaje uprawnienia: - Właściciel podmiotu - Administrator podmiotu podrzędnego - Administrator jednostki podrzędnej - Administrator podmiotu unijnego - Administrator podmiotu (posiadający uprawnienie do zarządzania uprawnieniami)

Typy uprawnień w KSeF 2.0:

Uprawnienia fakturowe: - Wystawianie faktur - Przeglądanie faktur

Uprawnienia administracyjne: - Zarządzanie uprawnieniami - Zarządzanie jednostkami podrzędnymi - Zarządzanie podmiotami unijnymi

Uprawnienia podmiotowe: - Samofakturowanie - Samofakturowanie RR - Operacje przedstawiciela podatkowego

Certyfikaty KSeF

W KSeF 2.0 wprowadzono nowy moduł do zarządzania wewnętrznymi certyfikatami KSeF, które umożliwiają uwierzytelnienie w systemie oraz są niezbędne do wystawienia faktury w trybie offline.

Dostępne typy certyfikatów:

1. Authentication - certyfikat przeznaczony do uwierzytelniania w systemie KSeF
2. Offline - certyfikat ograniczony wyłącznie do potwierdzania autentyczności wystawcy i integralności faktury w trybie offline (KOD II)

Proces uzyskania certyfikatu:

1. Sprawdzenie limitów - weryfikacja maksymalnej liczby certyfikatów, którą można dysponować
2. Pobranie danych do wniosku - pobranie zestawu danych identyfikacyjnych z certyfikatu użytego do uwierzytelnienia
3. Przygotowanie wniosku - utworzenie żądania podpisania certyfikatu
4. Wysłanie wniosku - przesłanie wniosku certyfikacyjnego do systemu KSeF
5. Sprawdzenie statusu - monitorowanie statusu wniosku (proces asynchroniczny)
6. Pobranie certyfikatu - pobranie wystawionego certyfikatu po zakończeniu procesu

Wymagania: - Klucz prywatny: RSA (min. 2048 bitów) lub EC (min. 256 bitów) - Zalecane jest stosowanie kluczy EC - Wszystkie dane identyfikacyjne muszą być zgodne z wartościami zwróconymi przez system

Korzyści certyfikatów KSeF: - Ułatwienie procesu uwierzytelniania - Możliwość wystawiania faktur w trybie offline - Brak konieczności posiadania zewnętrznego certyfikatu kwalifikowanego - Integracja z systemem KSeF

Uwaga: Certyfikat KSeF nie jest certyfikatem kwalifikowanym, ale jest honorowany w procesie uwierzytelniania wyłącznie na potrzeby systemu KSeF.

Panel zarządzania KSeF

Wszystkie zaakceptowane faktury, które zostały skonfigurowane jako obsługiwane przez KSeF (szczegóły zostały opisane w instrukcji KSeF - instrukcja dla wdrożeniowca) będą widoczne w Panelu zarządzania KSeF. Domyślnie każda faktura, która trafi do panelu otrzyma stan Zablokowana i nie będzie widoczna do czasu zaznaczenia checkboxa Pokaż zablokowane. Faktura będzie znajdować się w tym stanie na podstawie określonego czasu wstrzymania w konfiguracji, bądź ręcznego zablokowania wysyłki do KSeF. Oprócz tego, każda faktura, która trafi do panelu otrzyma swój status początkowy, również zależny od konfiguracji (domyślnie jest to status Nowe).

Po akceptacji faktury proces wygląda następująco:

1. Faktura trafia do panelu KSeF, jeśli jej typ jest skonfigurowany jako obsługiwany w KSeF.
2. System nadaje jej status początkowy i ewentualnie blokadę czasową.
3. Faktura przechodzi przez wygenerowanie XML, walidację, wysłanie do KSeF, pobranie UPO i archiwizację.
4. Jeżeli wystąpi błąd, szczegóły należy sprawdzić w historii operacji.

Panel KSeF przedstawia podstawowe dane o fakturach (tj. symbol faktury nadany w aplikacji i symbol nadany w KSeF, daty utworzenia, wysłania oraz przetworzenia, numer referencyjny KSeF i numer referencyjny sesji oraz informacje o blokadach) oraz pozwala na wykonywanie szeregu operacji na fakturach, tj.:

• wyświetlanie faktur;

• wyświetlanie historii wykonanych operacji KSeF na fakturze;

• zakładanie i zdejmowanie blokad;

• operacje związane z ręcznym przetwarzaniem faktur.

Panel można otworzyć z listy faktur KSeF albo z kontekstu konkretnej faktury sprzedaży. Panel ogólny służy do pracy na wielu fakturach i wymaga ustawienia odpowiedniego filtra statusu. Panel otwarty z faktury pozwala szybciej przejść do operacji dotyczących tego jednego dokumentu.

Aby przejść do panelu zarządzania KSeF, należy:

1. Przejść do zakładki Sprzedaż i kliknąć na przycisk Panel zarządzania (w obszarze KSeF).

2. Wyświetli się okno Panel zarządzania KS, zawierające wszystkie funkcjonalności KSeF.

Okno zawiera następujące elementy:

• Filtry:

  • Status - filtruje wyświetlanie faktur w panelu na podstawie stanu, w jakim się znajdują. W oknie będą wyświetlać się tylko faktury o wskazanym statusie w tym polu;

  • Od daty i Do daty - filtrują wyświetlanie faktur na podstawie zakresu dat wybranych z kalendarza;

  • Pokaż zablokowane - po zaznaczeniu checkboxa, w oknie będą się wyświetlać faktury, które są w stanie Zablokowane. Domyślnie pole jest odznaczone, dlatego jeśli wszystkie faktury w wybranym statusie (w filtrze Status) będą zablokowane, to w oknie nie będą wyświetlać się żadne faktury;

  • Pokaż fakturę - funkcja wyświetla okno główne wybranej faktury. Okno ma charakter poglądowy i nie pozwala na modyfikację danych na fakturze z tego poziomu;

• Operacje - menu, gromadzące funkcje związane z przetwarzaniem faktur. W menu mogą zostać uwzględnione dodatkowe operację po zgłoszeniu zapotrzebowania do Sente. Szczegółowe informacje, dotyczące poszczególnych operacji zostały opisane w rozdziale Operacje w panelu KSeF.

• Historia - funkcja wyświetla okno z listą operacji wykonanych na wybranej fakturze;

• menu zarządzania blokadami, zawierające funkcje związane nakładaniem blokad KSeF. Szczegóły zostały opisane w rozdziale Operacje w panelu KSeF.

• OFFLINE - funkcja zmienia tryb faktury z Online na Offline. Tryb faktury ma wpływ na komunikację z KSeF oraz generowane kody QR na wydruku.

Statusy faktur

W aplikacji dostępny jest zestaw statusów, które zostaną odpowiednio przypisane do każdej faktury, trafiającej do panelu zarządzania KSeF. W zależności od statusu, w którym znajduje się faktura, dostępne operacje będą się różnić.

Nie ma możliwości wyświetlenia faktur we wszystkich statusach jednocześnie, dlatego przed wykonaniem konkretnej operacji, należy upewnić się, że w filtrze Status została ustawiona odpowiednia wartość.

Faktury mogą otrzymać następujące statusy:

• Błąd generowania - faktura otrzyma ten status, jeżeli wystąpi problem przy generowaniu pliku XML (np. w przypadku podpięcia nieprawidłowego pliku XSD w konfiguracji KSeF, czy braku danych na fakturze);

• Błąd w UPO - faktura otrzyma ten status, jeżeli wystąpi problem po stronie bramki KSeF (np. w przypadku awarii bramki KSeF);

• Błąd walidacji - faktura otrzyma ten status, jeżeli wystąpi problem w trakcie walidacji pliku (np. w przypadku nieprawidłowej wersji pliku XSD, czy niezgodności pliku XML z definicją z pliku XSD);

• Błąd wysyłania - faktura otrzyma ten status, jeżeli wystąpi problem w trakcie wysyłki faktury na bramkę KSeF (np. w przypadku awarii połączenia sieciowego, czy błędów merytorycznych w pliku);

• Nowe - ten status otrzyma każda nieprzetworzona faktura (nowa, która trafiła do panelu lub faktura, która została przywrócona ze statusu błędu);

• Wycofane - faktura otrzyma ten status, jeżeli zostanie wycofana z panelu KSeF;

• Wygenerowane - faktura otrzyma ten status, jeżeli został wygenerowany do niej plik XML;

• Wysłane do KSeF - faktura otrzyma ten status, jeżeli została wysłana na bramkę KSeF;

• Zarchiwizowane - faktura otrzyma ten status, jeżeli została poprawnie przetworzona przez system KSeF (po pobraniu UPO) i został jej nadany symbol KSeF;

• Zwalidowane - faktura otrzyma ten status, jeżeli została poprawnie zwalidowana przez system.

Proces przetwarzania faktur w KSeF 2.0

W KSeF 2.0 wprowadzono ujednolicony proces inicjalizacji dla sesji wsadowej i interaktywnej, który został uniezależniony od trybu pracy. Po uzyskaniu certyfikatu uwierzytelniającego, można otworzyć zarówno sesję interaktywną, jak i wsadową.

Tryby wysyłki faktur:

1. Sesja interaktywna - służy do przesyłania pojedynczych faktur ustrukturyzowanych do API KSeF. Każda faktura jest przesyłana osobno w czasie rzeczywistym.

2. Sesja wsadowa - umożliwia jednorazowe przesłanie wielu faktur w pojedynczym pliku ZIP, co przyspiesza i ułatwia przetwarzanie dużej liczby dokumentów.

Wymagania KSeF 2.0:

• Obowiązkowe szyfrowanie - wszystkie faktury (zarówno w trybie interaktywnym, jak i wsadowym) muszą być zaszyfrowane lokalnie
• Bezpieczne przesyłanie - każda sesja wymaga wygenerowania nowego klucza szyfrowania
• Ochrona danych - klucz szyfrowania jest dodatkowo zabezpieczony kluczem publicznym KSeF Ministerstwa Finansów

Proces otwierania sesji:

W obu trybach przekazywane są podstawowe informacje: - kod formularza - określa wersję schematu faktury (FA(2) lub FA(3)) - zaszyfrowany klucz do szyfrowania danych faktur

W przypadku wysyłki wsadowej przekazywana jest również lista plików wraz z metadanymi wchodzących w skład paczki.

Usprawnienia w sesji wsadowej:

W KSeF 2.0 wprowadzono istotne udoskonalenie w zakresie przetwarzania sesji wsadowych: - każda faktura przetwarzana jest niezależnie - ewentualne błędy wpływają wyłącznie na konkretne faktury, a nie na całość przesyłki - liczba błędnych faktur jest zwracana dla statusu sesji - dostępne są szczegółowe informacje o błędnie przetworzonych fakturach

Status poprawnie wysłanej faktury zostanie automatycznie zmieniony na Wysłane do KSeF. Należy pamiętać, że formalnym potwierdzeniem prawidłowego przetworzenia faktury jest Urzędowe Poświadczenie Odbioru (UPO). Po jego pobraniu fakturze zostanie nadana data przetworzenia oraz symbol KSeF.

Muliselekcja

Aplikacja posiada wbudowaną funkcjonalność zaznaczania wielu rekordów w tabeli i wykonywania na nich operacji zbiorczych. Takie rozwiązanie pozwala na wykonywanie wielu operacji jednocześnie i znaczne przyspieszenie pracy. Po zaznaczeniu wybranego rekordu i naciśnięciu na przyciski Insert lub Shift + strzałka w dół, zostanie zaznaczone kilka pozycji. Rekordy można oznaczyć, za pomocą przycisków:

• Insert - odznacza konkretną pozycję;

• Shift + Del - odznacza wszystkie pozycje;

• zaznaczony checkbox w polu z filtrem - odznacza wszystkie pozycje.

Multiselekcji podlegają wszystkie funkcje dostępne w menu Operacje oraz wszystkie funkcje związane z zarządzaniem blokadami.

Funkcjonalność może być wykorzystywana w trakcie procesu przetwarzania faktur. W takim przypadku operacje mogą być wykonywane zbiorczo na fakturach o jednakowym statusie. Należy jednak pamiętać, że na bramce KSeF są założone limity wywołań, dlatego zaleca się ograniczenie ręcznego wykonywanie takich operacji na bramce (tj. wysyłanie faktur i pobieranie UPO) do pojedynczych lub kilku faktur jednocześnie. Szczegółowe informacje na temat limitów zostały opisane w rozdziale Limity.

Ręczne przetwarzanie faktur

Zalecanym sposobem wysyłki faktur do KSeF jest tryb automatu, który samodzielnie przechodzi przez proces przetwarzania faktur. Jeżeli jednak ten tryb został wyłączony lub istnieje potrzeba szybszego przesyłania konkretnej faktury do KSeF, to możliwe jest ręczne przejście przez cały proces przez uprawnionego operatora. Proces musi zostać rozpoczęty na fakturze o statusie Nowe i składa się z następujących etapów:

• wygenerowanie pliku XML;

• przeprowadzenie walidacji;

• wysłanie faktury do KSeF;

• pobranie UPO;

• weryfikacja ewentualnych błędów.

W trakcie procesu należy pamiętać, że aby faktura została poprawnie przetworzona, muszą sie na niej znajdować wszystkie dane wymagane przez przepisy prawne, a numer NIP przedsiębiorstwa musi być zgodny na fakturze oraz w systemie KSeF.

Aby wysłać ręcznie fakturę do bramki KSeF, należy:

1. Przejść do zakładki Sprzedaż i kliknąć na przycisk Panel zarządzania (w obszarze KSeF).

2. Wyświetli się okno Panel zarządzania KS. Należy wybrać w filtrze Status wartość Nowe.

3. (Opcjonalne) Możliwe jest wykonanie próbnej walidacji dla faktur o statusie Nowe. W tym celu należy zaznaczyć fakturę i kliknąć na przycisk Operacje -> Waliduj testowo.

Uwaga: Po wykonaniu próbnej walidacji faktury, jej status nie zostanie zmieniony.

4. (Opcjonalne) Wynik próbnej walidacji wyświetli się w oknie komunikatu. Należy kliknąć na przycisk OK i przejść do dalszej części procesu.

Uwaga: Jeżeli próbna walidacja nie powiedzie się, to konieczna będzie weryfikacja błędu i wykonanie zalecanych kroków.

5. Należy zaznaczyć fakturę i kliknąć na przycisk Operacje -> Generuj. Zostanie wygenerowany plik XML (właściwa e-faktura), a status faktury zostanie zmieniony na Wygenerowane.

Uwaga: Jeżeli w trakcie generowania pliku wystąpi błąd, to faktura otrzyma status Błąd generowania. Konieczna będzie weryfikacja błędu i podjęcie ponownej próby generowania.

6. Należy zmienić wartość w filtrze Status na Wygenerowane, a następnie zaznaczyć fakturę i kliknąć na przycisk Operacje -> Waliduj. Plik XML zostanie zwalidowany, a status faktury zostanie zmieniony na Zwalidowane.

Uwaga: Jeżeli w trakcie walidowania pliku wystąpi błąd, to faktura otrzyma status Błąd walidacji. Konieczna będzie weryfikacja błędu i podjęcie ponownej próby walidacji.

7. Należy zmienić wartość w filtrze Status na Zwalidowane, a następnie zaznaczyć fakturę i kliknąć na przycisk Operacje -> Wyślij. Plik XML zostanie wysłany na bramkę KSeF, a status faktury zostanie zmieniony na Wysłane do KSeF.

Uwaga: Jeżeli w trakcie wysyłania pliku wystąpi błąd, to faktura otrzyma status Błąd wysyłania. Konieczna będzie weryfikacja błędu i podjęcie ponownej próby wysyłania.

8. Należy zmienić wartość w filtrze Status na Wysłane do KSeF, a następnie zaznaczyć fakturę i kliknąć na przycisk Operacje -> Pobierz UPO. UPO zostanie pobrane, w aplikacji zostanie uzupełniona Data przetworzenia, a status faktury zostanie zmieniony na Zarchiwizowane.

Uwaga: Operacja Wyślij nie pobiera UPO. Pobranie UPO jest osobnym krokiem procesu.

Uwaga: Jeżeli wystąpi błąd w UPO, to faktura otrzyma status Błąd w UPO. Konieczna będzie weryfikacja błędu i podjęcie odpowiednich kroków, w zależności od rodzaju błędu. W niektórych przypadkach, konieczne może być poprawienie danych na fakturze oraz jej ponowne przesłanie do KSeF.

9. (Opcjonalne) Jeżeli w trakcie procesu wystąpi jakiś błąd, to faktura otrzyma status błędu o danym rodzaju i będzie widoczna dopiero po wybraniu odpowiedniej wartości w filtrze Status. W takim przypadku należy zweryfikować błąd (szczegółowy opis błędu będzie widoczny w historii operacji) i postępować zgodnie z zaleceniami.

Limity wywołań API w KSeF 2.0

W KSeF 2.0 wprowadzono precyzyjny i przewidywalny mechanizm ograniczeń liczby wywołań, który zastępuje dotychczasowe, nieelastyczne rozwiązania znane z wersji 1.0.

Nowy model limitów:

Każdy endpoint w systemie objęty jest limitem liczby żądań w zadanych przedziałach czasowych: - na sekundę - podstawowy limit dla natychmiastowych operacji - na minutę - średniookresowy limit dla częstych operacji - na godzinę - długookresowy limit dla intensywnych operacji - na dobę - dzienny limit dla wszystkich operacji

Charakterystyka limitów:

• Publicznie udostępniane - zakresy i wartości limitów są dostępne w dokumentacji online
• Zróżnicowane w zależności od środowiska - środowisko testowe ma limity mniej restrykcyjne niż produkcyjne
• Dostosowane do charakteru operacji:
• dla operacji chronionych – limity stosowane są per token JWT
• dla operacji otwartych (np. uwierzytelnienie, pobranie faktury) – limity stosowane są per adres IP klienta

Korzyści nowego modelu:

• Przejrzystość - jasne określenie limitów dla każdego endpointu
• Przewidywalność - możliwość planowania operacji zgodnie z dostępnymi limitami
• Lepsze skalowanie - system zaprojektowany tak, aby nie ograniczać typowego testowania aplikacji
• Elastyczność - różne limity dla różnych typów operacji

Obsługa przekroczenia limitów:

W przypadku przekroczenia limitu wywołań, system zwraca odpowiedni kod błędu HTTP (429 Too Many Requests) wraz z informacją o czasie, po którym można ponowić żądanie. Nie ma już konieczności odczekiwania stałego czasu - system informuje o dokładnym czasie oczekiwania.

Uwaga: Nowy model limitów został zaprojektowany tak, aby nie ograniczać typowego testowania aplikacji integrujących się z systemem – co stanowi istotne usprawnienie względem dotychczasowego podejścia.

Weryfikacja duplikatów faktur w KSeF 2.0

W KSeF 2.0 zmieniono sposób wykrywania duplikatów faktur. Dotychczas sprawdzany był skrót pliku, natomiast obecnie sprawdzane są dane biznesowe faktury.

Nowe kryteria wykrywania duplikatów:

System sprawdza następujące dane biznesowe faktury: - NIP podmiotu wystawiającego fakturę - Typ faktury (FA, PEF, RR) - Numer faktury

Korzyści nowego podejścia:

• Lepsze wykrywanie duplikatów - system identyfikuje faktury o identycznych danych biznesowych, nawet jeśli zostały przesłane w różnych formatach lub z różnymi metadanymi
• Zapobieganie błędnym duplikatom - faktury o identycznych danych biznesowych, ale różniące się szczegółami technicznymi, będą prawidłowo rozpoznane jako duplikaty
• Zgodność z przepisami - nowe podejście lepiej odzwierciedla wymagania prawne dotyczące unikalności faktur

Uwaga: Zmiana ta może wpłynąć na sposób przetwarzania faktur w systemach zewnętrznych, które dotychczas polegały na sprawdzaniu skrótów plików.

Środowiska KSeF API 2.0

KSeF 2.0 udostępnia następujące środowiska:

Skrót	Środowisko	Opis	Termin udostępnienia	Formaty faktur
TE	Testowe (Release Candidate)	Środowisko RC służące wczesnej weryfikacji planowanych zmian przed wdrożeniem do produkcji	30.09.2025	FA(2), FA(3), FA_PEF (3), FA_KOR_PEF (3)
TR	Przedprodukcyjne (Demo/Preprod)	Środowisko odpowiadające konfiguracji produkcyjnej, przeznaczone do końcowej walidacji integracji	15.10.2025	FA(3), FA_PEF (3), FA_KOR_PEF (3)
PRD	Produkcyjne	Środowisko do wystawiania i odbierania faktur o pełnej mocy prawnej	01.02.2026	FA(3), FA_PEF (3), FA_KOR_PEF (3)

Dokumentacja dla każdego środowiska dostępna jest pod adresem /docs/v2.

Środowisko testowe (TE) oferuje dodatkowo: - Pomocnicze API do generowania danych testowych - Możliwość symulowania założenia nowego podmiotu gospodarczego - Symulację nadania uprawnień przez ZAW-FA - Tworzenie jednostek w ramach struktury JST - Definiowanie organów egzekucyjnych i komorników sądowych

Wycofanie akceptacji faktury

Aby mieć możliwość poprawienia danych na fakturze, niezbędne jest wycofanie akceptacji faktury. Przed wprowadzeniem obowiązku KSeF proces przebiegał jednoetapowo na poziomie okna rejestru faktur. Obecnie do wycofania akceptacji faktury konieczne jest przejście przez dwa etapy:

• wycofanie akceptacji faktury z poziomu panelu zarządzania KSeF;

• wycofanie akceptacji faktury z poziomu rejestru faktur sprzedaży;

Po wykonaniu ponownej akceptacji faktury, dokument wróci do panelu zarządzania KSeF. Faktura otrzyma status Nowe i przestanie być widoczna w filtrze Wycofane.

Aby wycofać akceptację faktury, należy:

1. Przejść do zakładki Sprzedaż i kliknąć na przycisk Panel zarządzania (w obszarze KSeF).

2. Wyświetli się okno Panel zarządzania KSeF. Należy zaznaczyć fakturę i kliknąć na przycisk Operacje -> Wycofaj.

Uwaga: Nie ma możliwości wycofania faktury, która została już wysłana do KSeF. Funkcja wycofywania będzie dostępna tylko dla faktur o statusie Nowe, Wygenerowane, Zwalidowane, Błąd generowania, Błąd walidacji i Błąd wysyłania.

3. (Opcjonalne) Możliwe jest zweryfikowanie wszystkich faktur, które zostały wycofane z panelu KSeF. W tym celu należy ustawić wartość w filtrze Status na Wycofane.

4. Należy przejść do zakładki Sprzedaż i kliknąć na przycisk Faktury sprzedaży -> wybrany typ faktury (tu: Dokumenty FAK (Faktura VAT)).

5. Wyświetli się okno wybranego rejestru faktur. Należy zaznaczyć wycofaną fakturę z panelu KSeF i kliknąć na przycisk Operacja -> Wycofanie akceptacji.

6. Wyświetli się okno komunikatu potwierdzenia operacji. Należy kliknąć na przycisk Tak.

7. Wyświetli się okno komunikatu wycofywania akceptacji dokumentu. Należy kliknąć na przycisk:

• Nie - numer wycofywanego dokumentu nie zostanie zablokowany. Kolejne akceptowane dokumenty w tym rejestrze będą mogły otrzymać zwolniony numer;

• Tak - numer wycofywanego dokumentu zostanie zablokowany. Tylko ten dokument będzie mógł ponownie otrzymać zablokowany numer;

• Z dok. mag - numer wycofywanego dokumentu oraz podpiętego dokumentu WZ zostaną zablokowane. Tylko ten dokument i dokument WZ będą mogły ponownie otrzymać zablokowane numery;

Akceptacja faktury zostanie wycofana, a zawarte na niej dane będą mogły zostać zmodyfikowane.

8. (Opcjonalne) Jeżeli z jakiegoś powodu akceptacja faktury nie została wycofana z panelu KSeF, to w oknie wyświetli się komunikat z uwagą. Należy kliknąć na przycisk Ok i powtórzyć kroki 1-5.

Operacje w panelu KSeF

W panelu zarządzania KSeF dostępny jest szereg operacji, które pozwalają na zarządzanie zgromadzonymi fakturami. Istnieje możliwość dołączenia do panelu zarządzania KSeF dodatkowych operacji, które nie są widoczne w standardowej wersji aplikacji po konsultacji z Sente.

Część operacji (dostępne w menu Operacje) będzie dostępna tylko dla faktur, które mają konkretny status:

• Generuj - funkcja generuje plik XML. Funkcja dostępna tylko dla faktur o statusie Nowe;

• Waliduj testowo - funkcja przeprowadza próbną walidację faktury na podstawie dodanego w konfiguracji schematu pliku XSD przed rozpoczęciem właściwego procesu przez automat. Plik próbnej wersji faktury z wynikiem walidacji jest zapisywany w lokalizacji tymczasowej (ustawionej w konfiguracji). Nazwy pliku faktury i wyniku walidacji otrzymają taką samą nazwę (ref_czas) i będą się różnić typem rozszerzenia, dlatego w folderze będzie tyle par plików, ile zostało wykonanych próbnych walidacji. Po wykonaniu próbnej walidacji status faktury nie zostanie zmieniony. Funkcja będzie dostępna tylko dla faktur o statusie Nowe;

• Wycofaj - funkcja pozwala na wycofanie faktury z panelu KSeF. Funkcja będzie dostępna dla faktur we wszystkich statusach przed wysyłką plików do KSeF.

• Waliduj - funkcja przeprowadza właściwą walidację wybranej faktury na podstawie dodanego w konfiguracji schematu pliku XSD. W wyniku wykonania walidacji zostanie utworzony jeden plik faktury w ostatecznej wersji. Po jej wykonaniu status faktury zostanie zmieniony. Funkcja będzie dostępna tylko dla faktur o statusie Wygenerowana;

• Wróć do nowych - funkcja przywraca fakturę do statusu Nowe. Funkcja dostępna tylko dla faktur o statusie dowolnego rodzaju błędu;

• Wyślij - funkcja pozwala na wysłanie zwalidowanej faktury z panelu KSeF. Funkcja będzie dostępna tylko dla faktur o statusie Zwalidowane.

• Pobierz UPO - funkcja pobiera Urzędowe Poświadczenie Odbioru, które jest formalnym potwierdzeniem przetworzenia faktury w KSeF. UPO jest wydawane dla całej sesji, co oznacza, że pobiera się je dla każdej faktury z tej sesji, niezależnie od ich stanu blokady. Funkcja będzie dostępna tylko dla faktur o statusie Wysłane do KSeF;

Część operacji (poza menu Operacje) będzie dostępna tylko dla wszystkich faktur, niezależnie od statusu, w jakim mają nadany:

• Pokaż fakturę - wyświetla okno główne faktury o charakterze poglądowym;

• Historia - wyświetla historię operacji wykonanych na fakturze oraz informacje o ewentualnych błędach i zalecanych krokach postępowania;

• menu zarządzania blokadami, które zawiera następujące funkcje:

  • Odblokuj - funkcja pozwala na ściągnięcie blokady z wybranej faktury, po czym faktura będzie mogła zostać wysłana na bramkę KSeF ręcznie lub przez automat. Funkcja będzie dostępna tylko dla zablokowanych faktur;

  • Zablokuj - funkcja pozwala na zablokowanie wybranej faktury, po czym faktura nie będzie mogła zostać wysłana na bramkę KSeF ani ręcznie, ani przez automat. Możliwe jest wykonanie tej operacji w różnych wariantach, tj. 15 min, 30 min, Do odwołania oraz Ustaw ręcznie. Funkcja będzie dostępna odblokowanych i zablokowanych faktur (ze względu na możliwość ustawienia blokad w różnych wariantach).

Wyświetlanie faktur

W każdym momencie pracy w panelu zarządzania KSeF istnieje możliwość wyświetlenia okna głównego wybranej faktury. Pozwala to na przeglądanie danych faktury, czy klienta i weryfikację wprowadzonych danych. W celu modyfikacji danych, należy uprzednio wycofać akceptację faktury i wrócić do rejestru faktur.

Aby wyświetlić fakturę, należy:

1. Przejść do zakładki Sprzedaż i kliknąć na przycisk Panel zarządzania (w obszarze KSeF).

2. Wyświetli się okno Panel zarządzania KS. Należy ustawić preferowaną wartość w filtrze Status.

3. Należy zaznaczyć fakturę i kliknąć na przycisk Pokaż fakturę.

4. Wyświetli się okno główne wybranej faktury. Po zakończeniu weryfikacji pożądanych informacji, należy kliknąć na przycisk Zamknij.

Kody QR na wydrukach faktur

System automatycznie dodaje kody QR do wydruków faktur KSeF, które zawierają linki do faktury w systemie KSeF. Kody QR są drukowane tylko dla faktur z wygenerowanym plikiem XML.

Zasady drukowania kodów QR:

• Brak XML - kody QR nie są drukowane
• Tryb offline - drukowane są dwa kody QR:
• QRI - kod z numerem referencyjnym lub “offline”
• QRII - kod certyfikatu
• Faktura wysłana - drukowany jest jeden kod QR:
• QRI - kod z numerem referencyjnym

Aby włączyć tryb offline:

1. Przejść do zakładki Sprzedaż i kliknąć na przycisk Panel zarządzania KSeF
2. Zaznaczyć fakturę z wygenerowanym XML
3. Kliknąć przycisk Zmień na Offline, aby oznaczyć fakturę jako offline
4. Wydrukować fakturę - będą widoczne odpowiednie kody QR

Uwagi: - Funkcja dostępna tylko dla faktur z wygenerowanym plikiem XML - Po oznaczeniu faktury jako offline nie ma możliwości cofnięcia jej do trybu online z poziomu standardowego UI. - XML i hash faktury muszą pozostać spójne z wydrukiem. - Szablon ministerstwa nie może być modyfikowany - Wizualizacja pozwala na czytelne przeglądanie zawartości XML - Przydatne do weryfikacji poprawności danych przed wysłaniem do KSeF

Historia operacji

Wszystkie wykonywane operacje w panelu KSeF są zapisywane w historii operacji KSeF. Wykonane operacje mogą być opisane danymi operatora, datą wykonania, nazwą operacji, statusem początkowym, statusem wykonania, typem oraz opisem. Ilość podanych informacji będzie zależeć od typu operacji i nie w każdym przypadku wszystkie dane będą uzupełnione. Dodatkowo, po zaznaczeniu wybranej operacji w oknie wyświetlą się szczegółowe informacje na jej temat np. opis błędu i zalecanego postępowania.

Aby wyświetlić historię operacji KSeF, należy:

1. Przejść do zakładki Sprzedaż i kliknąć na przycisk Panel zarządzania (w obszarze KSeF).

2. Wyświetli się okno Panel zarządzania KSeF. Należy ustawić preferowana wartość w fitrze Status.

3. Należy zaznaczyć fakturę i kliknąć na przycisk Historia.

4. Wyświetli się okno Historia operacji. Po zaznaczeniu operacji, w panelu Szczegóły wyświetli się dokładna informacja na temat wykonanej operacji.

Uwaga: Jeżeli jakaś operacja zakończyła się niepowodzeniem, to będzie tu przedstawiony opis błędu i zalecane kroki, pozwalające na jego rozwiązanie.

Zarządzanie blokadami

Każda faktura, która trafi do panelu zarządzania KSeF zostanie automatycznie zablokowana na wskazany czas w konfiguracji (szczegóły zostały opisane w instrukcji KSeF - instrukcja dla wdrożeniowca). Blokada wstrzymuje cały proces przetwarzania faktur przez automat. Pomimo założonej blokady, nadal możliwe będzie ręczne przejście przez proces wysyłki faktury do KSeF.

Faktura pozostanie zablokowana do czasu upłynięcia czasu wstrzymania, nadejścia godziny rozpoczęcia pracy automatu lub ręcznego odblokowania faktury. W czasie kiedy na fakturze jest założona blokada możliwe jest wykonywanie na niej operacji (np. wycofanie akceptacji i modyfikacja danych).

Jeżeli faktura jest zablokowana, to w panelu zarządzania KSeF, w kolumnie Bl? będzie widoczna ikona kłódki . W panelu będzie widoczny również czas, po którego upłynięciu blokada zostanie zdjęta. Jeśli bloda została założona bezterminowo, to w kolumnie Zablokowane do nie będzie widoczna żadna data. Jeżeli blokada została założona ręcznie przez operatora, to w kolumnie Zablokowane przez beda widoczne dane tego operatora.

Odblokowanie faktury

Aby zdjąć blokadę z faktury, należy:

1. Przejść do zakładki Sprzedaż i kliknąć na przycisk Panel zarządzania (w obszarze KSeF).

2. Wyświetli się okno Panel zarządzania KSeF. Należy ustawić preferowaną wartość w filtrze Status.

3. Należy zaznaczyć fakturę i kliknąć na przycisk zarządzania blokadami -> Odblokuj. Faktura zostanie odblokowana.

Uwaga: Jeżeli zaznaczona faktura jest odblokowana, to przycisk Odblokuj będzie nieaktywny.

Blokowanie faktury

Aby założyć blokadę na fakturze, należy:

1. Przejść do zakładki Sprzedaż i kliknąć na przycisk Panel zarządzania (w obszarze KSeF).

2. Wyświetli się okno Panel zarządzania KSeF. Należy ustawić preferowaną wartość w filtrze Status.

3. Należy zaznaczyć fakturę i kliknąć na przycisk zarządzania blokadami -> Zablokuj -> preferowana opcja blokowania (15 minut, 30 minut, Do odwołania lub Ustaw ręcznie).

Uwaga: Zakładanie blokad będzie dostępne nawet dla już zablokowanych faktur. Dzięki temu możliwe jest skrócenie lub wydłużenie czasu założonej blokady.

4. (Opcjonalne) Jeżeli została wybrana blokada o typie Ustaw ręcznie, to wyświetli się okno Wstrzymanie przetwarzania. Należy uzupełnić pole Czas wstrzymania [minuty] oraz opcjonalnie pole Przyczyna.

Okno zawiera następujące elementy:

• Czas wstrzymania [minuty] - czas podany w minutach, na jaki zostanie wstrzymany proces przetwarzania faktury (pole obowiązkowe);

• Przyczyna - powód, dla którego została założona blokada. Wprowadzony opis będzie widoczny w szczegółach historii tej operacji (pole dodatkowe).

5. Należy kliknąć na przycisk Blokuj. Blokada zostanie założona na fakturę na wskazany czas wstrzymania.

6. Wyświetli się okno komunikatu, informujące o godzinie, do której zostanie wstrzymane przetwarzanie faktury. Należy kliknąć na przycisk Ok, aby wyjść z okna.

Korekty faktur

Sposób obsługi standardowych korekt w aplikacji nie uległ zmianie. Jeżeli natomiast w przedsiębiorstwie jest wykorzystywany mechanizm faktur korygujących rabaty zbiorcze (np. za obroty klienta za miniony kwartał lub półrocze), to konieczne jest przygotowanie indywidualnego rozwiązania. Pozwoli to na wskazanie faktur korygowanych na danej fakturze z rabatem zbiorczym, do którego klient będzie mógł dopisać swoje zmiany. Na podstawie numeru ref faktury z rabatem zbiorczym powinny zostać zwrócone informacje o fakturach, które będą korygowane. W celu opracowania odpowiedniego mechanizmu, należy skontaktować się z Sente.

Szczególnym przypadkiem korekt faktury jest korekta NIP klienta. Faktura z błędnym NIP nabywcy zostanie po przetworzeniu udostępniona podmiotowi o takim numerze NIP. Właściwy nabywca nie otrzyma faktury do czasu przetworzenia nowej faktury przez KSeF. W przypadku pomyłki i wskazania nieprawidłowego NIP-u na fakturze, konieczne jest:

• przesłanie do KSeF faktury korygującej z błędnym NIP-em, gdzie wartość faktury zostanie skorygowana do zera;

• przesłanie do KSeF nowej faktury z prawidłowym NIP-em, na której zostaną wskazane wszystkie fakturowane towary / usługi.

Uwaga: Jeżeli korekta faktury została wystawiona po złożeniu deklaracji VAT-7, to konieczne będzie również złożenie korekty deklaracji.

Awarie i błędy przetwarzania faktur

W trakcie korzystania z panelu KSeF możliwe jest wystąpienie awarii zewnętrznych lub wewnętrznych powiązanych z awarią sieci oraz błędów przetwarzania.

Jeżeli wystąpiła zewnętrzna lub wewnętrzna awaria (np. połączenia sieciowego), to wysyłanie faktur lub / i pobieranie UPO zakończy się niepowodzeniem. Jeżeli w panelu będzie włączony tryb automatu, to po osiągnięciu limitu prób (ustawionego w konfiguracji KSeF), system zaprzestanie próby wysyłania faktur. W takim przypadku faktura otrzyma status Błąd wysyłania. Po naprawieniu usterki, konieczne będzie przywrócenie statusu faktury do statusu Zwalidowane. Automat ponownie podejmie próbę wysyłki faktury do KSeF.

W trakcie procesu możliwe jest wystąpienie różnych błędów przetwarzania, np. wynikających z nieprawidłowej konfiguracji KSeF, czy braku danych na fakturze. W trakcie procesu mogą wystąpić następujące błędy:

• błąd generowania - związany z brakiem danych na fakturze;

• błąd walidacji - związany z nieprawidłową konfiguracją KSeF (np. podpięty nieaktualny plik XSD) lub niezgodnymi danymi przedsiębiorstwa na poziomie KSeF - aplikacja;

• błąd wysyłania - związany z awariami sieciowymi, awariami bramki KSeF lub błędami sprawdzanymi przez bramkę KSeF, które nie są sprawdzane po stronie aplikacji (np. uprawnienia certyfikatów, zgodność NIP);

• błąd w UPO - związany z odrzuceniem faktury przez system KSeF;

W przypadku błędów w UPO, należy przeprowadzić gruntowną weryfikację błędu i wysłanej faktury. System KSeF posiada zestaw kodów błędów, które mogą zostać przypisane do faktury.

Raport z błędów będzie dostępny w oknie przeprowadzonych operacji. Szczegóły zostały opisane w rozdziale Historia operacji.

Operacje KSeF w rejestrze faktur

W ramach wprowadzonych zmian KSeF, podstawowy interfejs okna rejestru faktur nie uległ zmianie. Wprowadzono jednak nowe funkcjonalności, umożliwiające wykonanie podstawowych operacji związanych z KSeF. Będą one dostępne wyłącznie dla tych typów faktur, które podlegają KSeF i jeszcze nie zostały do niego wysłane.

W rejestrze faktur dostępne są następujące operacje KSeF:

• Wstrzymaj realizację - proces przetwarzania faktury zostanie wstrzymany i zostanie na niej założona blokada bezterminowa. Status blokady będzie widoczny w panelu zarządzania KSeF;

• Wznów realizację - proces przetwarzania faktury zostanie wznowiony i blokada zostanie z niej zniesiona. Status blokady będzie widoczny w panelu zarządzania KSeF.

• Parametry faktury - funkcja pozwala na uzupełnienie wybranych dodatkowych parametrów XML dla faktury, szczególnie dla węzła zwolnienia z podatku. Standardowo obsługiwane są parametry P_19A, P_19B i P_19C. Funkcja nie jest ogólnym mechanizmem dodawania dowolnych znaczników XML;

• Otwórz wizualizację XML - funkcja umożliwia podgląd wygenerowanego pliku XML faktury na szablonie ministerstwa. Wizualizacja pokazuje dane z XML, a nie bezpośrednio z bazy, dlatego jest najlepszym miejscem do sprawdzenia, co zostanie wysłane do KSeF. Funkcja dostępna tylko dla faktur z wygenerowanym plikiem XML;

• Panel zarządzania KSeF - funkcja umożliwia przejście do panelu zarządzania KSeF z poziomu rejestru faktur;

• Podmiot 3 - funkcja pozwala uzupełnić dane podmiotu trzeciego na fakturze. Podmiot pierwszy to sprzedawca, podmiot drugi to nabywca, a podmiot trzeci może pełnić jedną z ról przewidzianych przez strukturę KSeF, np. odbiorcy, pracownika albo faktora.

Aby wykonać operację KSeF w rejestrze faktur (tu: na przykładzie faktury VAT), należy:

1. Przejść do zakładki Sprzedaż i kliknąć na przycisk Faktury sprzedaży -> Dokumenty VAT (Faktura VAT) (w obszarze Rejestry sprzedaży).

2. Wyświetli się okno rejestru faktur sprzedaży. Należy zaznaczyć fakturę i kliknąć na przycisk Inne dane -> Funkcje KSeF, aby wyświetlić dostępne operacje KSeF.

a) Jeżeli proces przetwarzania ma zostać wstrzymany, to należy zaznaczyć fakturę i kliknąć na przycisk Inne dane -> Funkcje KSeF -> Wstrzymaj realizację. Na fakturę zostanie założona blokada bezterminowa.

b) Jeżeli proces przetwarzania ma zostać wstrzymany, to należy zaznaczyć fakturę i kliknąć na przycisk Inne dane -> Funkcje KSeF -> Wznów realizację. Z faktury zostanie zdjęta blokada.

Wizualizacja XML faktury

System umożliwia podgląd wygenerowanego pliku XML faktury w formacie HTML na szablonie ministerstwa. Funkcjonalność pozwala na czytelne wyświetlenie zawartości XML bez możliwości modyfikacji szablonu, co ułatwia weryfikację poprawności danych przed wysłaniem do KSeF.

Aby otworzyć wizualizację XML to należy zaznaczyć fakturę i kliknąć na przycisk Inne dane -> Funkcje KSeF -> Otwórz wizualizację XML

Panel zarządzania KSeF

Aby przejść do panelu zarządzania KSeF z poziomu rejestru faktur należy zaznaczyć fakturę i kliknąć na przycisk Inne dane -> Funkcje KSeF -> Panel KSeF

Parametry faktury

Aby otworzyć formę parametrów faktury z poziomu rejestru faktur należy zaznaczyć fakturę i kliknąć na przycisk Inne dane -> Funkcje KSeF -> Parametry faktury

Migracja na KSeF 2.0

Kluczowe zmiany wymagające dostosowania

Migracja na KSeF 2.0 wymaga dostosowania implementacji po stronie systemów zewnętrznych. Poniżej przedstawiono najważniejsze zmiany:

1. Nowy model uwierzytelniania: - Uwierzytelnianie oparte o tokeny JWT zamiast dotychczasowego procesu logowania - Wydzielenie uwierzytelniania jako osobnego procesu, niezależnego od inicjalizacji sesji - Wprowadzenie tokenów dostępowych i odświeżających

2. Obowiązkowe szyfrowanie: - Wszystkie faktury muszą być zaszyfrowane lokalnie - Klucz szyfrowania musi być dodatkowo zabezpieczony kluczem publicznym KSeF

3. Ujednolicony proces inicjalizacji sesji: - Proces otwierania sesji został ujednolicony dla trybu interaktywnego i wsadowego - Możliwość wielokrotnego użycia certyfikatu do tworzenia wielu sesji

4. Nowy mechanizm zarządzania uprawnieniami: - Zaawansowany system uprawnień z możliwością nadawania uprawnień bezpośrednich i pośrednich - Nowe typy uprawnień (wystawianie faktur, przeglądanie faktur, zarządzanie uprawnieniami, itp.) - Mechanizm delegowania uprawnień dla podmiotów pośredniczących

5. Nowe funkcjonalności: - Certyfikaty KSeF - wewnętrzne certyfikaty systemu jako podstawowa metoda uwierzytelniania - Usprawniony proces wysyłki wsadowej z niezależnym przetwarzaniem faktur

6. Zmiany techniczne: - Nowy mechanizm rate limiting z precyzyjnymi limitami dla każdego endpointu - Zmiana sposobu wykrywania duplikatów faktur (dane biznesowe zamiast skrótu pliku) - Nowe środowiska testowe z pomocniczym API do generowania danych testowych

Zalecenia dotyczące migracji

1. Wykorzystanie oficjalnych bibliotek - zalecane jest wykorzystanie oficjalnej biblioteki integracyjnej KSeF 2.0 Client, która implementuje wszystkie dostępne endpointy i modele danych

2. Testowanie w środowisku testowym - przed migracją na produkcję należy przeprowadzić pełne testy w środowisku testowym (TE)

3. Aktualizacja procesów biznesowych - może być konieczna aktualizacja procesów biznesowych związanych z zarządzaniem uprawnieniami i uwierzytelnianiem

4. Monitorowanie limitów - nowy mechanizm rate limiting wymaga implementacji odpowiedniej logiki obsługi przekroczenia limitów

5. Zarządzanie certyfikatami - implementacja mechanizmu zarządzania certyfikatami KSeF dla utrzymania ciągłego dostępu

Harmonogram wdrożenia

• 30.09.2025 - udostępnienie środowiska testowego (TE)
• 15.10.2025 - udostępnienie środowiska przedprodukcyjnego (TR)
• 01.02.2026 - uruchomienie środowiska produkcyjnego (PRD)

Uwaga: Migracja na KSeF 2.0 powinna być traktowana jako zmiana kontraktu integracyjnego i wymaga odpowiedniego planowania oraz testowania.