Dokumentacja API KSeF 2.0 – co warto wiedzieć?
W środę, 9 lipca 2025 r., odbyło się pierwsze czytanie projektu ustawy wprowadzającej Krajowy System e-Faktur (KSeF), którego obowiązkowe stosowanie planowane jest od 2026 r. Sejm skierował projekt do Komisji Finansów Publicznych. Choć kluby i koła poselskie zapowiedziały dalsze prace legislacyjne, wśród parlamentarzystów panuje jednomyślność co do konieczności wdrożenia systemu.
W związku z tym warto uważnie śledzić wszelkie informacje dotyczące KSeF. Jedną z kluczowych publikacji w tym zakresie jest opublikowana 30 czerwca 2025 r. dokumentacja API KSeF 2.0, której poświęcamy trzecią odsłonę KSeF Lettera.
Dla przypomnienia – API KSeF 2.0 to interfejs integracyjny w formie interaktywnego portalu, służący do połączenia systemów finansowo-księgowych z KSeF. Zawiera zestaw reguł i specyfikacji technicznych, określających sposób wymiany danych oraz współpracy KSeF z zewnętrznymi systemami informatycznymi.
Dokumentacja została przygotowana z myślą o integratorach, dostawcach oprogramowania oraz zespołach IT odpowiedzialnych za wdrożenie KSeF w organizacjach. W poprzedniej publikacji opisaliśmy strukturę dokumentacji [link do wpisu], natomiast w niniejszym artykule skupimy się na kluczowych funkcjonalnościach nowego API.
Uwierzytelnianie
Nowa wersja API wprowadza rozbudowany mechanizm uwierzytelniania, oparty na tokenach JWT oraz podpisach elektronicznych XAdES. Aby uzyskać dostęp do chronionych zasobów systemu, należy najpierw przeprowadzić proces uwierzytelnienia – w jego wyniku użytkownik otrzymuje token dostępu, wykorzystywany następnie do autoryzacji operacji.
W przeciwieństwie do wersji API 1.0, w której wymagane było rozpoczęcie sesji, API 2.0 oddziela proces uwierzytelniania od sesji, co upraszcza komunikację z systemem.
Uwierzytelnienie opiera się na dwóch elementach:
- wskazaniu podmiotu, w imieniu którego wykonywane będą operacje;
- określeniu podmiotu uwierzytelniającego, czyli tego, kto faktycznie dokonuje uwierzytelnienia.
Podmiot uwierzytelniający może zostać wskazany na dwa sposoby – za pomocą podpisu XAdES lub tokena KSeF.
Uprawnienia
Skuteczne zarządzanie uprawnieniami jest kluczowe dla bezpiecznego i zgodnego z przepisami korzystania z KSeF. Zakres nadanych uprawnień determinuje możliwość wykonywania konkretnych operacji w systemie – np. wystawiania faktur, przeglądania dokumentów czy przekazywania dalszych uprawnień.
System przewiduje liczne ograniczenia:
- nie można nadać tego samego uprawnienia dwukrotnie,
- nadanie uprawnienia nie powoduje natychmiastowego dostępu – operacja musi zostać przetworzona przez system.
Uprawnienia pozostają aktywne do czasu ich odebrania. Cofnięcie uprawnienia nie wpływa jednak na ważność operacji dokonanych przed jego odebraniem – np. wystawione wcześniej faktury pozostaną w systemie.
Szyfrowanie faktur
API KSeF 2.0 wprowadza obowiązkowe szyfrowanie wszystkich faktur, niezależnie od trybu ich przesyłania. W poprzedniej wersji szyfrowanie było wymagane jedynie w trybie wsadowym, a w przypadku faktur pojedynczych miało charakter fakultatywny.
Wysyłka wsadowa
Nowa wersja API usprawnia również mechanizm wysyłki wsadowej. Dotychczas błąd w jednej fakturze skutkował odrzuceniem całej paczki. Obecnie każda faktura jest przetwarzana indywidualnie, a system zwraca informację o błędach jedynie w odniesieniu do dokumentów, w których je wykryto.
Pomocnicze API
Jedną z najważniejszych nowości jest pomocnicze API do generowania danych testowych. W środowisku testowym udostępnione zostanie dedykowane narzędzie do symulacji procesów takich jak:
- założenie nowego podmiotu gospodarczego,
- nadanie uprawnień,
- tworzenie struktur organizacyjnych przedsiębiorstw powiązanych.
Rozwiązanie to umożliwi szybkie przygotowanie danych potrzebnych do testowania systemu przed jego pełnym wdrożeniem.
Pełną dokumentację API KSeF 2.0 znajdą Państwo na oficjalnym portalu Ministerstwa Finansów:
KSeF API – środowisko testowe
AUTORZY WPISU
E: kinga.tarnawa-macek@pl.andersen.com
T: +32 731 68 77
E: tomasz.dereszewski@pl.Andersen.com
T: +48 22 690 08 88