Limity techniczne KSeF - wielkość plików i ilość zapytań: co już teraz musisz wiedzieć, żeby nie wylądować w ścianie

Rozmiar pliku: 1 MB vs 3 MB - gdzie leży pułapka

AITekst opracowany z wykorzystaniem sztucznej inteligencji. Zasady i ograniczenia

Limit wielkości pliku w KSeF jest parametrem binarnym, którego przekroczenie skutkuje natychmiastowym odrzuceniem dokumentu przez bramkę API. Ministerstwo Finansów precyzyjnie określiło, że faktura ustrukturyzowana bez dodatkowych danych binarnych nie może przekraczać 1 MB (ok. 1 024 kB). W przypadku implementacji załączników, dopuszczalna masa komunikatu XML wzrasta do 3 MB (ok. 3 072 kB), co ma umożliwić przesyłanie specyfikacji technicznych lub zestawień towarowych bezpośrednio wewnątrz struktury logicznej.

Należy pamiętać, że faktura z załącznikiem 3 MB musi uwzględniać narzut technologiczny wynikający z kodowania Base64. Zgodnie ze specyfikacją techniczną, osadzenie pliku binarnego wewnątrz dokumentu XML zwiększa jego objętość o około 33% w stosunku do pierwotnego rozmiaru pliku. Przykładowo, dokumentacja techniczna w formacie JPEG o rozmiarze 2,5 MB po zakodowaniu do formatu tekstowego przekroczy dopuszczalny limit 3 MB, uniemożliwiając skuteczną wysyłkę do systemu Ministerstwa Finansów.

W przypadku przekroczenia zdefiniowanych progów, system zwraca błąd HTTP 413 "Payload Too Large" wraz z Urzędowym Poświadczeniem Odbioru (UPO) zawierającym komunikat "Przekroczono dopuszczalny rozmiar pliku". W takiej sytuacji faktura nie zostaje utrwalona w repozytorium KSeF i traktowana jest jako niewystawiona. Podatnik musi dokonać agresywnej kompresji danych lub usunąć zbędne elementy graficzne, aby zmieścić się w limicie, a następnie ponowić próbę wysyłki w trybie offline w ciągu 7 dni od wykrycia nieprawidłowości.

Limit wielkości pliku ma charakter twardy (hard limit) i nie podlega negocjacjom ani indywidualnym rozszerzeniom dla poszczególnych podmiotów gospodarczych. Dokumentacja API KSeF 2.0 udostępniona w czerwcu 2025 r. jednoznacznie wskazuje, że błąd 413 jest ostateczny. Aby zoptymalizować wielkość wysyłanych danych, eksperci zalecają stosowanie formatu PDF/A-2b, który oferuje wysoką kompresję przy zachowaniu czytelności, oraz unikanie formatów bezstratnych takich jak PNG na rzecz formatu JPEG z jakością ustawioną na poziomie 85%.

Liczba zapytań API - czy KSeF wytrzyma twój sklep internetowy

Częstotliwość wywołań interfejsu programistycznego (API) została ograniczona w celu zapewnienia stabilności infrastruktury krytycznej państwa. Oficjalny parametr przepustowości wynosi 60 requestów na minutę dla jednego certyfikatu uwierzytelniającego, co w praktyce oznacza jedno zapytanie na sekundę na poziomie pojedynczego numeru NIP. Jest to limit znacznie niższy niż w komercyjnych systemach bankowych, które standardowo obsługują od 300 do 500 zapytań na sekundę (rps), co wymusza na programistach stosowanie zaawansowanych mechanizmów kolejkowania.

Do limitu wliczane są wszystkie operacje wykonywane w ramach sesji interaktywnej lub nieinteraktywnej. Każde wywołanie metody wchodzącej w skład cyklu życia faktury jest traktowane jako oddzielne zdarzenie obciążające licznik systemowy:

• GET /invoice - operacja pobrania szczegółowych danych faktury
• POST /invoice - operacja wysyłki i rejestracji nowej e-faktury
• GET /status - weryfikacja postępu przetwarzania dokumentu w systemie

Przekroczenie dopuszczalnego licznika skutkuje zwróceniem kodu błędu HTTP 429 "Too Many Requests" o sygnaturze "KSeF-429-02". System przesyła wówczas nagłówek Retry-After, wskazujący precyzyjną liczbę sekund pozostałą do odblokowania możliwości wysyłania kolejnych żądań. Należy podkreślić, że 5-krotne nadużycie limitów w ciągu jednej godziny skutkuje automatyczną, 15-minutową blokadą dostępu do modułu API dla danego certyfikatu, co może paraliżować procesy sprzedażowe w dużych sklepach internetowych.

W celu uniknięcia blokad technicznych, rekomenduje się wdrożenie algorytmu Backoff Exponential, który automatycznie wydłuża czas oczekiwania między kolejnymi próbami wysyłki w przypadku otrzymania odpowiedzi o przeciążeniu. Systemy klasy mission-critical, takie jak Comarch EDI, który posiada 25-letnie doświadczenie w obsłudze milionów dokumentów, natywnie implementują mechanizmy cache dla statusów faktur, co ogranicza liczbę zbędnych odpytań bramki MF. Przekroczenie limitów zapytań nie wpływa na moc prawną faktur już wystawionych i poprawnie zarejestrowanych w repozytorium.

20 kolumn w załączniku - jak nie przekroczyć ściany struktury

Struktura logiczna FA(3) wprowadza rygorystyczne ograniczenie liczby pól w sekcji tabelarycznej załączników. Zgodnie z wytycznymi Ministerstwa Finansów, limit wynosi 20 elementów w obrębie węzła AttachedTable. Do tego limitu wliczane są wszystkie zdefiniowane kolumny (TableColumn), takie jak numer porządkowy, nazwa towaru, ilość czy cena jednostkowa. Jest to struktura płaska, co oznacza, że każde zdefiniowane pole bezpośrednio konsumuje dostępną pulę dwudziestu slotów danych.

Przekroczenie tego limitu skutkuje błędem walidacji schematu XSD o kodzie "cvc-complex-type.2.4.d", co oznacza, że dokument jest niezgodny z oficjalnym wzorcem XML. System nie dopuszcza możliwości zagnieżdżania wielu tabel w ramach jednego dokumentu ani dodawania kolejnych kolumn ponad limit. Przykładem wyczerpania limitu jest faktura za usługi logistyczne, gdzie zdefiniowano 5 wierszy opisu i 4 kolumny techniczne - w takim układzie struktura osiąga swoją maksymalną dopuszczalną złożoność.

<AttachedTable>
<TableColumn>
<Name>Lp.</Name>
</TableColumn>
<TableColumn>
<Name>Nazwa usługi</Name>
</TableColumn>
<TableColumn>
<Name>Ilość</Name>
</TableColumn>
</AttachedTable>

W sytuacjach wymagających przesłania bardziej rozbudowanych zestawień, podatnicy powinni stosować rozwiązania hybrydowe. Możliwe jest scalanie kolumn o zbliżonym charakterze (np. połączenie pola "Ilość" i "Jednostka" w jedną kolumnę tekstową) lub przeniesienie szczegółowych danych do załącznika w formacie PDF, który jest integralną częścią pliku XML. Należy jednak pamiętać, że Ministerstwo Finansów nie dopuszcza przesyłania załączników w formie nieustrukturyzowanej jako odrębnych plików poza kontenerem XML faktury.

Zastosowanie odpowiednich skrótów jednostkowych zgodnych z klasyfikacją PKWiU pozwala zaoszczędzić miejsce w strukturze logicznej. Przed wysyłką dokumentów zawierających rozbudowane specyfikacje, warto przygotować prototabelę w arkuszu kalkulacyjnym w celu weryfikacji liczby kolumn. W przypadku faktur o wyjątkowej złożoności, których nie da się przedstawić w formie 20-kolumnowej tabeli, konieczne jest przekazanie szczegółowych specyfikacji kanałami zewnętrznymi, np. poprzez bezpieczne systemy EDI lub pocztę elektroniczną, przy jednoczesnym zachowaniu głównej faktury w systemie KSeF.

10 000 zł miesięcznie - próg bezpieczeństwa dla mikrofaktur

Zwolnienie z obowiązku korzystania z Krajowego Systemu e-Faktur do końca 2026 r. opiera się na kryterium wartości sprzedaży. Zgodnie z art. 106e ust. 2 ustawy o podatku od towarów i usług, podatnicy, u których miesięczna suma sprzedaży fakturowanej nie przekracza 10 000 zł brutto, mogą kontynuować wystawianie faktur w formie papierowej lub elektronicznej poza systemem centralnym. Limit ten jest liczony dla każdego miesiąca kalendarzowego niezależnie, a jego przekroczenie w dowolnym momencie roku podatkowego skutkuje powstaniem obowiązku stosowania KSeF od pierwszego dnia miesiąca następującego po przekroczeniu.

Do limitu 10 000 zł wlicza się suma wszystkich faktur VAT, faktur VAT RR oraz faktur korygujących zwiększających podstawę opodatkowania. Co istotne, do końca 31 grudnia 2026 r. do tego progu wliczane są również paragony z NIP nabywcy (do kwoty 450 zł), które są uznawane za faktury uproszczone. Przykładowo, jeśli podatnik w styczniu 2026 r. wystawi 9 faktur o wartości 1 200 zł brutto każda, łączna suma sprzedaży wyniesie 10 800 zł, co obliguje go do wdrożenia KSeF od 1 lutego 2026 r.

• Faktury dokumentujące sprzedaż towarów i świadczenie usług na terytorium kraju
• Faktury dokumentujące eksport towarów i wewnątrzwspólnotową dostawę towarów (WDT)
• Faktury korygujące in plus wystawiane w danym okresie rozliczeniowym
• Paragony fiskalne z NIP nabywcy uznawane za faktury uproszczone
• Faktury wystawione dobrowolnie w systemie KSeF w danym miesiącu

Do limitu nie należy wliczać dokumentów o charakterze niepodatkowym, takich jak faktury proforma, noty księgowe, noty obciążeniowe czy faktury wewnętrzne dokumentujące wewnątrzwspólnotowe nabycie towarów (WNT). Systemy analityczne Ministerstwa Finansów będą weryfikować przestrzeganie tego limitu poprzez analizę plików JPK_FA. Podatnicy zbliżający się do progu 10 000 zł powinni rygorystycznie monitorować sumę brutto sprzedaży i w razie potrzeby rozważyć przesunięcie terminu wystawienia faktury na kolejny okres rozliczeniowy, aby uniknąć przedwczesnego wejścia w reżim obligatoryjnego KSeF.

Bezpieczny podpis elektroniczny zgodnie z przepisami ma taką samą moc prawną, jak każdy dokument podpisany własnoręcznie. O wiele łatwiej jest podrobić podpis składany ręcznie niż certyfikat uwierzygadniający dokument w wersji elektronicznej. - Piotr Kułagowski, Dyrektor Departamentu Operacji, Warta