Struktura FA(3) i nowe wymagania techniczne

AITekst opracowany z wykorzystaniem sztucznej inteligencji. Zasady i ograniczenia

Nowa struktura logiczna FA(3) zastąpi dotychczasową wersję FA(2) i stanowi fundament integracji z Krajowym Systemem e-Faktur od 1 lutego 2026 r. Powszechnym błędem interpretacyjnym wśród integratorów oprogramowania jest założenie, iż migracja ogranicza się do modyfikacji wersji schematu w nagłówku pliku XML. W rzeczywistości dokumentacja API KSeF 2.0 opublikowana 30 czerwca 2025 r. wprowadza głębokie zmiany w logice biznesowej i technicznej dokumentu, które wymagają pełnej analizy XSD.

Kluczową zmianą merytoryczną jest wprowadzenie nowego obowiązkowego tagu "KSeF-ID-Nabywcy" dla transakcji krajowych, co ma na celu uszczelnienie obiegu dokumentów ustrukturyzowanych. Kolejną modyfikację stanowi standaryzacja zapisu walut zgodnie z normą ISO-4217 oraz zmiana formatu daty na ISO-8601 z uwzględnieniem czasu strefy UTC, co eliminuje nieścisłości przy fakturach wystawianych na przełomie dób. Ponadto, Załącznik nr 1 do rozporządzenia Ministra Finansów z dnia 28 stycznia 2026 r. nakłada bezwzględny wymóg szyfrowania kluczem AES-256 dla sesji interaktywnych.

Wdrożenie struktury FA(3) powstało w wyniku szerokich konsultacji z ekspertami branżowymi, co zaowocowało doprecyzowaniem pól opcjonalnych. Faktura ustrukturyzowana w nowym formacie wymaga od programistów mapowania danych zgodnie z poniższą specyfikacją techniczną:

Dostawcy oprogramowania powinni pobrać aktualny schemat XSD ze strony Ministerstwa Finansów, aby uniknąć błędów walidacji semantycznej. Należy pamiętać, że integracja KSeF pozwala nie tylko na wystawianie, ale i automatyczne odbieranie faktur z platformy centralnej, co znacząco przyspiesza procesy księgowe wewnątrz przedsiębiorstwa.

Środowiska testowe i produkcyjne - jak nie wprowadzić fikcyjnej faktury do obrotu prawnego

W architekturze Krajowego Systemu e-Faktur funkcjonują trzy całkowicie oddzielne środowiska: testowe, przedprodukcyjne oraz produkcyjne. Zgodnie z art. 106na § 4 ustawy Ordynacja podatkowa, faktury wystawione w środowisku integracyjnym (testowym) nie wywierają żadnych skutków prawnych ani podatkowych. Środowisko to służy wyłącznie do weryfikacji poprawności technicznej komunikacji API oraz sprawdzania zgodności plików XML ze strukturą logiczną FA(3).

Środowisko produkcyjne przeznaczone jest dla rzeczywistych faktur, a każda operacja zakończona nadaniem numeru KSeF ID oraz wygenerowaniem Urzędowego Potwierdzenia Odbioru (UPO) skutkuje wprowadzeniem dokumentu do obrotu prawnego. Ministerstwo Finansów udostępniło adresy stron internetowych dedykowane poszczególnym instancjom, podkreślając, że środowiska są od siebie logicznie i technicznie odseparowane. Wykorzystywanie elementów konfiguracji (np. tokenów) ze środowisk testowych w systemach produkcyjnych będzie skutkować błędami technicznymi i odrzuceniem żądania.

Podczas konfiguracji oprogramowania kluczowe jest rozdzielenie metod szyfrowania danych. Poniższy fragment implementacji w języku Java 17 obrazuje inicjalizację mechanizmu szyfrującego z wyraźnym rozgraniczeniem środowiskowym:

// Inicjalizacja szyfrowania AES dla środowiska testowego KSeF

// Uwaga: Ten klucz działa tylko na ksef-test; na produkcji pobierz certyfikat z MCU

Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");

SecretKeySpec keySpec = new SecretKeySpec(testEncryptionKey, "AES");

cipher.init(Cipher.ENCRYPT_MODE, keySpec);

W przypadku problemów z połączeniem, w 90% przypadków przyczyną jest sprawdzanie niewłaściwego środowiska. Dlatego przy pracy z Krajowym Systemem e-Faktur zawsze należy upewnić się, czy operujemy na instancji TE (test), TR (trening/demo) czy PRD (produkcja).

JWT, AES i RSA - nowe mechanizmy bezpieczeństwa w API KSeF 2.0

Bezpieczeństwo wymiany danych w API KSeF 2.0 opiera się na zaawansowanych algorytmach kryptograficznych, które gwarantują integralność i poufność przesyłanych faktur ustrukturyzowanych. Każda sesja komunikacyjna wymaga zainicjowania procesu autoryzacji, w którym wykorzystywany jest token JWT (JSON Web Token). System wymusza stosowanie szyfrowania hybrydowego: każda paczka dokumentów jest szyfrowana losowo wygenerowanym kluczem AES o długości 256 bitów, a następnie ten klucz jest szyfrowany kluczem publicznym RSA udostępnionym przez Ministerstwo Finansów.

Podstawą zabezpieczenia transmisji jest algorytm podpisu RSASSA-PSS z wykorzystaniem funkcji skrótu MGF1-SHA256. W celu wygenerowania bezpiecznego klucza symetrycznego, programiści powinni korzystać z narzędzi systemowych zapewniających wysoką entropię. Przykładowo, w systemach Linux klucz można wygenerować poleceniem: openssl rand -hex 32. Zgodnie z dobrymi praktykami bezpieczeństwa, wygenerowany klucz należy zapisać w zmiennej środowiskowej serwera aplikacyjnego, a nie bezpośrednio w repozytorium kodu źródłowego.

Implementacja żądania uwierzytelniającego w języku Python 3.11 z wykorzystaniem biblioteki cryptography wymaga precyzyjnego sformatowania nagłówków i ładunku (payload). Poniższy schemat obrazuje strukturę takiego zapytania:

headers = {"Content-Type": "application/octet-stream", "X-KSeF-Signature": signature}

payload = {"encryptionKey": encrypted_aes_key, "context": auth_context}

Podpis generowany z użyciem klucza prywatnego użytkownika i algorytmu RSA-SHA256

Ministerstwo Finansów udostępniło objaśnienia podatkowe z 28 stycznia 2026 r., w których podkreśla znaczenie zarządzania certyfikatami. Przed każdą wysyłką na produkcję sugerowane jest sprawdzenie aktualności certyfikatu RSA na oficjalnej stronie resortu, gdyż wykorzystanie nieaktualnych kluczy publicznych uniemożliwi poprawne deszyfrowanie danych przez bramkę KSeF.

Harmonogram wdrożenia i co zrobić do 1 lutego 2026

Obowiązkowe wdrożenie systemu KSeF 2.0 z dniem 1 lutego 2026 r. oznacza, że poprzednia wersja interfejsu (KSeF 1.0) zostanie całkowicie wyłączona, a system nie będzie oferował trybu awaryjnego dla starych struktur. Firmy oraz dostawcy oprogramowania muszą wykorzystać pozostały czas na pełną integrację i certyfikację swoich rozwiązań. Harmonogram prac powinien uwzględniać następujące kamienie milowe:

1. Lipiec 2025 - Dokładna analiza dokumentacji technicznej API KSeF 2.0 oraz nowej struktury logicznej FA(3).
2. Sierpień 2025 - Rozpoczęcie prac programistycznych w środowisku sandbox i implementacja mechanizmów szyfrowania AES/RSA.
3. Wrzesień 2025 - Przeprowadzenie testów obciążeniowych na udostępnionym 30 września środowisku integracyjnym.
4. Październik 2025 - Uzyskanie niezbędnych certyfikatów z Modułu Certyfikatów i Uprawnień (MCU) oraz konfiguracja uprawnień.
5. Styczeń 2026 - Finalne testy regresyjne i przygotowanie przełącznika produkcyjnego (production toggle) na dzień 1 lutego.

W procesie przygotowań warto skorzystać z gotowych bibliotek open-source, które znacząco skracają czas implementacji i są na bieżąco aktualizowane przez społeczność programistyczną. Do najbardziej rekomendowanych rozwiązań należą: ksef-java-sdk (licencja MIT), ksef-dotnet-core (licencja Apache-2.0) oraz ksef-python (licencja GPL-3). Wszystkie te narzędzia są dostępne w serwisie GitHub i wspierają obsługę faktur ustrukturyzowanych.

Ministerstwo Finansów regularnie publikuje cztery części podręcznika KSeF 2.0 o łącznym rozmiarze przekraczającym 4 MB, które szczegółowo opisują każdy aspekt techniczny systemu. Dokumentacja ta jest niezbędna dla zapewnienia pełnej kontroli nad fakturami w jednym miejscu i minimalizacji liczby pomyłek dzięki wbudowanym regułom walidującym. Należy pamiętać, że limit 10 000 zł na fakturę w określonych procedurach uproszczonych nadal obowiązuje, co musi zostać uwzględnione w logice biznesowej systemów ERP.

• Logowanie do aplikacji przy pomocy Profilu Zaufanego
• Składanie wniosku o certyfikat i zarządzanie certyfikatami w MCU
• Pobranie aktualnego XSD ze strony
• Prowadzenie testów integracyjnych wyłącznie na środowisku integracyjnym
• Sprawdzenie współpracy oprogramowania z systemem przed końcem 2025 roku