KSeF API limity zapytań i wydajność

Co musisz wiedzieć

Krajowy System e-Faktur (KSeF) udostępnia API do wysyłki i pobierania faktur. Każde wywołanie chronionego endpointu jest liczone w ramach limitów. Limity zależą od pary: kontekst (NIP lub inny identyfikator z uwierzytelnienia) oraz adres IP, z którego łączysz się z systemem.

Po przekroczeniu limitu API zwraca błąd 429 (Too Many Requests) i tymczasowo blokuje kolejne żądania. Czas blokady jest dynamiczny; w odpowiedzi można znaleźć nagłówek Retry-After z sugestią, ile sekund odczekać.

Najczęstsze problemy i rozwiązania

Otrzymuję błąd 429 – przekroczony limit zapytań

Błąd HTTP 429 oznacza przekroczenie limitu rate limiting. Poczekaj kilka sekund przed kolejnym żądaniem. Rozważ optymalizację zapytań lub wniosek o zwiększenie limitów dla środowiska produkcyjnego.

Jak uniknąć przekroczenia limitów przy masowej wysyłce?

Rozłóż wysyłkę w czasie, stosując opóźnienia między zapytaniami. Używaj trybu wsadowego do wysyłki wielu faktur jednocześnie. Monitoruj odpowiedzi API pod kątem limitów.

Czy mogę wnioskować o wyższe limity?

Tak, na środowisku produkcyjnym podmioty wymagające większej intensywności operacji mogą wnioskować o podwyższenie limitów przez formularz kontaktowy Ministerstwa Finansów.

Jak naliczane są limity

Limity dotyczą każdego żądania do chronionego endpointu. Ruch jest grupowany według pary: kontekst (określony przez ContextIdentifier: NIP, InternalId lub NipVatUe przy uwierzytelnianiu) oraz adres IP. Ten sam kontekst z różnych adresów IP jest rozliczany osobno. Stosowane są trzy progi: żądania na sekundę (req/s), na minutę (req/min) i na godzinę (req/h). Obliczenia prowadzone są w modelu przesuwającego się okna czasowego: dla req/h liczone są żądania z ostatnich 60 minut, dla req/min z ostatnich 60 sekund, dla req/s z ostatniej sekundy. Okna nie zerują się o pełnej godzinie czy minucie. Wszystkie progi obowiązują równolegle – blokada następuje przy pierwszym przekroczeniu któregokolwiek z nich.

Przekroczenie limitu i odpowiedź 429

Gdy limit zostanie przekroczony, API zwraca kod HTTP 429 Too Many Requests. Kolejne żądania są wtedy tymczasowo blokowane. Czas blokady jest dynamiczny i zależy od skali oraz częstotliwości przekroczeń. W nagłówku odpowiedzi Retry-After podawany jest sugerowany czas oczekiwania w sekundach przed ponowną próbą. Wielokrotne przekroczenia mogą wydłużyć blokadę.

Rejestrowanie przekroczeń

Wszystkie przekroczenia limitów są rejestrowane i analizowane przez mechanizmy bezpieczeństwa. System zwraca uwagę na wzorce sugerujące obchodzenie limitów, np. równoległe używanie wielu adresów IP w jednym kontekście. W przypadku powtarzających się naruszeń lub skrajnego obciążenia system może zastosować działania ochronne, np. blokadę dostępu do API dla danego podmiotu lub zakresu adresów IP.

Limity na środowiskach TE, DEMO i PRD

Na środowisku testowym (TE) domyślne limity są około dziesięciokrotnie wyższe niż na produkcji, co ułatwia testowanie. Dostępne są endpointy do symulacji: ustawienie limitów jak na produkcji, ustawienie własnych wartości lub przywrócenie domyślnych limitów TE. Na środowisku DEMO obowiązują takie same limity jak na produkcji (PRD). Na PRD stosowane są domyślne limity z dokumentacji; w uzasadnionych przypadkach (np. duża skala przetwarzania) można złożyć wniosek o podniesienie limitów przez dedykowany formularz Ministerstwa Finansów. W godzinach nocnych (20:00–06:00) mogą obowiązywać wyższe limity pobierania – szczegóły są ustalane w trakcie działania systemu.

Pobieranie faktur – założenia i limity

API pobierania faktur jest zaprojektowane jako mechanizm synchronizacji z lokalną bazą; operacje użytkownika (wyszukiwanie, raporty) powinny być wykonywane na danych już zsynchronizowanych. Do synchronizacji przyrostowej służy endpoint POST /invoices/query/metadata. Przy dużym wolumenie zaleca się mechanizm eksportu (POST /invoices/exports) zamiast pobierania pojedynczych faktur. Interwał cykliczny w produkcji nie powinien być krótszy niż 15 minut na podmiot. Limity: pobranie listy metadanych (POST /invoices/query/metadata) – 8 req/s, 16 req/min, 20 req/h; eksport paczki (POST /invoices/exports) – 4 req/s, 8 req/min, 20 req/h; status eksportu (GET /invoices/exports/{referenceNumber}) – 10 req/s, 60 req/min, 600 req/h; pobranie faktury po numerze KSeF (GET /invoices/ksef/{ksefNumber}) – 8 req/s, 16 req/min, 64 req/h.

Wysyłka faktur – sesja wsadowa i interaktywna

Otwarcie i zamknięcie sesji wsadowej (POST /sessions/batch, POST .../close): 10 req/s, 20 req/min, 60 req/h. Wysyłka części paczki w ramach jednej sesji wsadowej nie jest objęta limitami. Otwarcie sesji interaktywnej (POST /sessions/online): 10 req/s, 30 req/min, 120 req/h. Wysłanie faktury w sesji interaktywnej (POST .../invoices): 10 req/s, 30 req/min, 180 req/h. Zamknięcie sesji interaktywnej: 10 req/s, 30 req/min, 120 req/h. Przy regularnym osiąganiu limitów w trybie interaktywnym zaleca się rozważenie trybu wsadowego.

Status sesji i faktur

Pobranie statusu faktury z sesji: 30 req/s, 120 req/min, 1200 req/h. Lista sesji (GET /sessions): 5 req/s, 10 req/min, 60 req/h. Lista faktur sesji oraz niepoprawnie przetworzonych: po 10 req/s, 20 req/min, 200 req/h. Pozostałe GET /sessions/*: 10 req/s, 120 req/min, 1200 req/h.

Pozostałe endpointy i zasoby publiczne

Dla endpointów bez osobno określonych limitów obowiązuje limit domyślny: 10 req/s, 30 req/min, 120 req/h. Dotyczy to tylko zasobów chronionych. Zasoby publiczne, np. /auth/challenge (bez uwierzytelnienia), mają osobne mechanizmy – limit 60 żądań na sekundę na jeden adres IP.

FAQ

Powiązane tematy

• KSeF API 2.0 – dokumentacja i integracja
• KSeF API autoryzacja i tokeny