Jak sprawdzić poprawność pliku XML przed wysyłką do KSeF - instrukcja krok po kroku

Co się dzieje z plikiem po przekroczeniu 60 MB i jak tego uniknąć

AITekst opracowany z wykorzystaniem sztucznej inteligencji. Zasady i ograniczenia

Limit wielkości pojedynczego dokumentu w formacie XML został sztywno określony na poziomie 60 MB dla plików niekompresowanych. W obrocie gospodarczym powszechne jest przekonanie, że nowoczesna infrastruktura serwerowa Ministerstwa Finansów przyjmie dowolną objętość danych, jednakże specyfikacja techniczna KSeF 2.0 jednoznacznie odrzuca jednostki przekraczające ten parametr. Logika systemu opiera się na trójce: firma wysyła plik o rozmiarze 65 MB, Centralny Rejestr Faktur (KSeF) dzieli taką paczkę na mniejsze fragmenty, co skutkuje gwałtownym wzrostem liczby generowanych Urzędowych Poświadczeń Odbioru (UPO), a w konsekwencji księgowa musi później scalać te dane w systemach finansowo-księgowych. Przekroczenie limitu 60 MB dla niekompresowanego XML jest jednoznaczne z ryzykiem błędu o kodzie 100 (Niepoprawny XML) lub problemami z integralnością dokumentu.

Zastosowanie kompresji w formacie ZIP pozwala na znaczną optymalizację przesyłu danych, jednakże należy pamiętać, że KSeF automatycznie dzieli pliki ZIP o rozmiarze powyżej 60 MB. Przykładowo, plik XML o objętości 63 MB po przetworzeniu do formatu ZIP może osiągnąć rozmiar 49 MB, co mieści się w dopuszczalnej normie przesyłu bez podziału na pakiety. Należy jednak monitorować strukturę danych, ponieważ każda wydzielona przez system paczka otrzymuje osobne UPO, co komplikuje proces archiwizacji i późniejszej kontroli skarbowej. Podstawowe elementy faktury nie zmienią się po 1 lutego 2026 r., jednakże zarządzanie ich objętością cyfrową staje się nowym obowiązkiem działów IT.

Procedura kontroli objętości dokumentu przed wysyłką powinna stać się standardowym elementem procesu fakturowania. W pierwszej kolejności należy zweryfikować właściwości pliku w systemie operacyjnym, a następnie dokonać testowej kompresji w celu sprawdzenia uzyskanego stopnia redukcji danych. Jeśli po kompresji plik nadal przekracza 60 MB, jedynym skutecznym rozwiązaniem jest podział zbioru faktur na mniejsze paczki, co zapewnia stabilność komunikacji z interfejsem API Ministerstwa Finansów.

1. Pobierz plik XML wygenerowany przez system SAP lub inny program finansowo-księgowy i sprawdź jego rozmiar we właściwościach systemu.
2. Przeprowadź testową kompresję do formatu ZIP i porównaj wynik z dopuszczalnym limitem 60 MB.
3. W przypadku wątpliwości co do precyzyjnego rozmiaru, użyj polecenia w konsoli systemowej: powershell (Get-Item 'faktury.xml').Length /1MB.

Validator XSD online i lokalnie - gdzie sprawdzić strukturę FA(3)

Walidacja struktury XML względem schematu XSD (XML Schema Definition) pozwala szybciej wychwycić błędy strukturalne przed próbą uwierzytelnienia dokumentu. Oficjalnym narzędziem udostępnionym przez administrację skarbową jest Aplikacja Podatnika KSeF w wersji 2.0.3, dostępna pod adresem URL: . Istotną cechą tego rozwiązania jest fakt, iż validator działa w trybie offline, co oznacza, że przesyłany plik nie trafia do produkcyjnego systemu KSeF i nie wywołuje skutków prawno-podatkowych. Narzędzie to pozwala na pełne i elastyczne dostosowanie się do zmian w strukturze logicznej FA(3), która staje się obowiązująca od 1 lutego 2026 r.

Dla podmiotów preferujących automatyzację procesów wewnątrz własnej infrastruktury IT, optymalnym rozwiązaniem jest walidacja lokalna z wykorzystaniem języka Python. Wykorzystując bibliotekę xmlschema, można zweryfikować dokument w czasie poniżej 30 sekund za pomocą skryptu: import xmlschema; xmlschema.validate('faktura.xml', 'FA(3)_v1.xsd'). Należy przy tym pamiętać, aby schematy XSD pobierać do lokalnego repozytorium (cache) bezpośrednio z zasobów CRWDE. Walidacja XSD nie weryfikuje kryptograficznie podpisu XAdES, ale skutecznie identyfikuje braki w polach obligatoryjnych lub błędne formaty danych, takie jak kod błędu "cvc-complex-type" oznaczający brak wymaganego elementu struktury.

Zaleca się, aby schematy XSD pobierać do lokalnego cache i pinować wersje schematów w projekcie, co zapobiega błędom w przypadku nagłych aktualizacji na serwerach rządowych. Skonfigurowanie resolvera dla importów i include jest niezbędne dla poprawnego działania walidacji w środowiskach odizolowanych od internetu. Zapisywanie logów walidacji po każdej zmianie szablonu w systemie ERP stanowi istotny element budowania ścieżki audytu (audit trail) wewnątrz organizacji.

Najczęstsze błędy XML i jak je czytać bez zgadywania

Analiza komunikatów błędów w systemie KSeF wymaga znajomości precyzyjnej terminologii informatycznej oraz struktury logicznej FA(3). Cytat: "[P_1]: niepoprawna wartość pola" odnosi się bezpośrednio do daty wystawienia dokumentu, co według statystyk stanowi 34% wszystkich przyczyn odrzucenia faktur. W takim przypadku należy zweryfikować "co" jest błędem (wartość daty), "gdzie" występuje (pole P_1) oraz "jak naprawić" (zmiana formatu na ISO 8601). Należy pamiętać, że dodanie pozycji do pliku jest jednoznaczne z deklaracją jej uzupełnienia, a nieuzupełnione pola obligatoryjne generują błędy krytyczne uniemożliwiające nadanie numeru KSeF.

Przykładem często spotykanym w praktyce gospodarczej jest błąd przy fakturze o wartości 7 500,00 zł brutto. Jeśli system ERP wygeneruje XML zawierający przecinek zamiast kropki jako separatora dziesiętnego, KSeF zwróci błąd "cvc-fraction-digits". Prawidłowy zapis w polu P_15 powinien wyglądać następująco:

<P_15>7500.00</P_15>

W przypadku błędu w zapisie, podatnik może zostać ukarany za nieprawidłowość karą do 100% kwoty podatku wykazanego na fakturze. Warto również zweryfikować kody walut, gdyż system akceptuje wyłącznie format ISO-4217 (np. PLN, EUR). Brak numeru NIP nabywcy, jeśli nie jest on osobą fizyczną, powinien być weryfikowany poprzez API białej listy przed ostatecznym wygenerowaniem pliku XML, co eliminuje ryzyko odrzucenia dokumentu na etapie walidacji merytorycznej.

Checklista przed wysyłką - 30-sekundowe API call

Automatyzacja weryfikacji statusu faktury pozwala na uniknięcie czasochłonnego korzystania z interfejsu graficznego (GUI). Jedno polecenie w środowisku PowerShell umożliwia pobranie Urzędowego Poświadczenia Odbioru (UPO) w ciągu kilku sekund od wysyłki. Kluczowe jest wykorzystanie nagłówka X-Reference-Number otrzymanego po wysłaniu dokumentu. Należy pamiętać, że token sesyjny JWT (JSON Web Token) jest ważny przez 55 minut od momentu uwierzytelnienia przez endpoint /auth/challenge.

Przykładowe polecenie pobierające status sesji i dokumentu:

Invoke-RestMethod -Uri '' -Headers @{Authorization='Bearer $token'}

# reference = wartość z nagłówka X-Reference-Number

W sytuacji otrzymania statusu HTTP 400 (Bad Request), najczęstszymi przyczynami są: niepoprawna struktura Bearer tokena, przeterminowany token JWT lub błędny numer referencyjny. W środowiskach Linux analogiczną operację można wykonać za pomocą narzędzia curl:

curl -H 'Authorization: Bearer $token' -X GET ''

• Status 200 przy jednoczesnym braku UPO oznacza, że faktura znajduje się w kolejce przetwarzania systemu centralnego.
• Jeśli system zwraca błąd 400 - należy powtórzyć walidację XML względem schematu FA(3) i wysłać dokument ponownie.
• Zapisuj UPO w formacie PDF lub XML jako kopię bezpieczeństwa, ponieważ organ podatkowy może żądać dowodu wystawienia faktury w KSeF podczas kontroli skarbowej.

Status 301 w systemie e-Deklaracje sugeruje, że należy zaczekać i sprawdzić status deklaracji ponownie w programie za kilka minut. W przypadku KSeF procesowanie odbywa się zazwyczaj w czasie od 3 do 7 sekund, jednakże w okresach szczytowego obciążenia (np. 20. dzień miesiąca) czas ten może ulec wydłużeniu. Dokumentem podstawowym w obrocie gospodarczym staje się docelowo zapis w Krajowym Systemie e-Faktur, co sprawia, że poprawność pliku XML jest warunkiem niezbędnym do uznania transakcji za udokumentowaną zgodnie z prawem.