Masowa wysyłka faktur - wydajność i limity API KSeF

Limity API KSeF - co dokładnie blokuje masową wysyłkę?

AITekst opracowany z wykorzystaniem sztucznej inteligencji. Zasady i ograniczenia

Interfejs programistyczny API KSeF 2.0 nakłada rygorystyczne ograniczenia na liczbę operacji wykonywanych w jednostce czasu, co ma na celu zapewnienie stabilności infrastruktury centralnej Ministerstwa Finansów. Najważniejszym parametrem dla systemów ERP oraz platform e-fakturowania jest wydajność endpointu GET /limits/subject, który definiuje bieżące uprawnienia dla danego podmiotu. Standardowy limit dla pobierania listy metadanych faktur wynosi 8 żądań na sekundę, natomiast dla kluczowej operacji eksportu paczki faktur limit ten został ustalony na poziomie 4 żądań na sekundę.

Mechanizm sliding window (okno przesuwne) działa w cyklu jednosekundowym i resetuje się po upływie każdej sekundy od ostatniego przesłanego żądania. W praktyce oznacza to, że przesłanie 4 żądań w ciągu 1 s jest procesowane prawidłowo, jednak wysłanie 5 żądania w tym samym interwale natychmiast wywołuje odpowiedź serwera o kodzie HTTP 429. System informatyczny po stronie podatnika otrzymuje wówczas informację o czasowej blokadzie dostępu do zasobu.

Warto podkreślić, że limitowanie zapytań jest przypisane do konkretnego certyfikatu kwalifikowanego lub pieczęci elektronicznej, a nie zbiorczo do całego numeru NIP firmy. W związku z tym, wykorzystanie wielu certyfikatów dla różnych jednostek organizacyjnych może teoretycznie zwielokrotnić przepustowość, o ile architektura systemu podatnika na to pozwala. Serwer w odpowiedzi HTTP 429 przesyła nagłówek Retry-After, który precyzyjnie określa czas blokady w sekundach, po którym można ponowić próbę komunikacji.

Błąd HTTP 429 oznacza przekroczenie limitu rate limiting. Poczekaj kilka sekund przed kolejnym żądaniem.

Ministerstwo Finansów zapewnia, że infrastruktura serwerowa zlokalizowana w Polsce jest gotowa do obsługi dużego natężenia ruchu, a system został zaprojektowany w oparciu o niezależne lokalizacje. Niemniej jednak, monitorowanie odpowiedzi API pod kątem limitów jest niezbędne dla zachowania ciągłości procesów biznesowych. W przypadku wystąpienia błędu 429, system wysyłający powinien zapisać wartość Retry-After i wstrzymać kolejne zapytania dokładnie na wskazaną liczbę sekund.

Wniosek o wyższe limity - kiedy i jak to zrobić poprawnie?

Przedsiębiorstwa realizujące operacje gospodarcze na dużą skalę mogą ubiegać się o indywidualne zwiększenie przepustowości interfejsu API KSeF. Istnieją trzy twarde przesłanki uzasadniające taką prośbę: średnia dzienna liczba wystawianych faktur ustrukturyzowanych przekracza 10 tys. sztuk, występuje konieczność masowego eksportu paczek w szczytach rozliczeniowych (np. między 1 a 10 dniem miesiąca), lub specyfika branży uniemożliwia rozłożenie wysyłki w czasie, co dotyczy głównie faktur korygujących in minus generowanych automatycznie przez systemy bilingowe.

Wniosek o podwyższenie limitów składa się wyłącznie drogą elektroniczną przez formularz kontaktowy dostępny na portalu ksef.podatki.gov.pl. Należy pamiętać, że decyzja o zwiększeniu parametrów dotyczy tylko środowiska produkcyjnego, a czas rozpatrzenia dokumentacji przez służby techniczne Ministerstwa Finansów wynosi do 14 dni roboczych. Rekomenduje się dołączenie wykresu obciążenia systemu z ostatnich 30 dni, co znacząco przyspiesza proces weryfikacji zasadności wniosku.

Prawidłowo sformułowane uzasadnienie powinno zawierać konkretne dane techniczne i operacyjne. Przykładowy fragment uzasadnienia może brzmieć: „Wnioskuję o limit 20 req/s dla endpointu /invoice/batch/export. W szczycie miesiąca wystawiamy 35 tys. faktur w 2 h, co przy obecnym limicie 4 req/s wymagałoby 146 minut zamiast planowanych 10 minut”. Precyzyjne wskazanie punktu styku oraz spodziewanego wolumenu danych ułatwia administratorom KSeF dostosowanie parametrów rate limitingu do potrzeb podatnika.

Optymalizacja kodu - 5 trików, które faktycznie zmniejszają liczbę zapytań

Redukcja liczby zapytań do API KSeF jest możliwa poprzez wdrożenie zaawansowanych mechanizmów paczkowania oraz cache'owania danych po stronie klienta. Zamiast wysyłania 100 pojedynczych żądań metodą POST /invoice, należy wykorzystać pojedyncze żądanie /invoice/batch, które pozwala na przesłanie tablicy zawierającej do 100 elementów XML w jednej sesji komunikacyjnej. Zastosowanie tej metody pozwala na skrócenie łącznego czasu komunikacji z serwerem z około 25 s do zaledwie 1 s, przy zachowaniu limitów wagowych paczki do 10 MB.

Kolejnym skutecznym rozwiązaniem jest implementacja lokalnego bufora metadanych. Pobieranie listy metadanych raz na 5 minut i przechowywanie ich w pamięci operacyjnej systemu (np. Redis lub Memcached) pozwala na wyeliminowanie około 80 % powtórnych zapytań GET /invoice/metadata. Dzięki temu system operuje na danych lokalnych, odciążając łącze do serwerów Ministerstwa Finansów i minimalizując ryzyko otrzymania błędu 429.

W przypadku wystąpienia limitów rate limiting, kluczowe jest zastosowanie algorytmu wykładniczego wstrzymania (exponential backoff). Przykładowa implementacja w logice aplikacji powinna zakładać progresywne wydłużanie czasu oczekiwania po każdym błędzie 429:

if (response.status == 429) {

  wait_time = Math.pow(2, attempt) * 1000;

  sleep(wait_time);

}

Testy przeprowadzone przez operatorów EDI wskazują, że zastosowanie backoffu 2^x redukuje liczbę błędów typu 429 o 70 % w warunkach wysokiego obciążenia. Dodatkowo, należy ustawić timeout dla połączeń na poziomie 30 s, ponieważ procesowanie bardzo dużych paczek (bliskich limitowi 10 MB) może trwać dłużej niż standardowe zapytania synchroniczne. Przekroczenie maksymalnego rozmiaru paczki skutkuje zwróceniem błędu HTTP 413 (Payload Too Large).