KSeF API eksport timeout – obsługa zawieszonych eksportów
Timeout eksportów w KSeF API
Eksporty faktur w KSeF API 2.0 mają ograniczony czas ważności. Po przekroczeniu czasu eksport otrzymuje status 210 (wygasł) i nie może być już pobrany. Eksporty mogą również wisieć na statusie 100 (w trakcie przetwarzania) przez długi czas.
Timeout eksportów zależy od liczby faktur, obciążenia systemu i innych czynników. Niektóre eksporty mogą wisieć na statusie 100 przez kilka godzin lub nawet dni, szczególnie w środowisku testowym.
Strategie obsługi timeout obejmują: monitorowanie statusu eksportu, ustawienie timeout po stronie klienta, ponowienie eksportu z mniejszymi zakresami dat, optymalizację kryteriów filtrowania oraz obsługę błędów limitów eksportów.
Instrukcja krok po kroku
1. Monitoruj status eksportu
Regularnie sprawdzaj status eksportu używając GET /api/v2/invoices/export/{referenceNumber}. Status może być: 100 (w trakcie przetwarzania), 200 (zakończony pomyślnie), 210 (wygasł), błędy. Eksporty mogą trwać długo, więc ustaw odpowiedni interwał sprawdzania (np. co 5-15 minut).
2. Ustaw timeout po stronie klienta
Ustaw timeout po stronie klienta (np. 15-30 minut) dla eksportów. Jeśli eksport nie zakończył się w określonym czasie, rozważ ponowienie eksportu z mniejszymi zakresami dat lub innymi kryteriami filtrowania. Timeout po stronie klienta nie anuluje eksportu w KSeF, ale pozwala na wcześniejsze podjęcie działań.
3. Obsłuż status 210 (wygasł)
Gdy eksport otrzyma status 210 (wygasł), utwórz nowe żądanie eksportu. Rozważ użycie mniejszych zakresów dat lub innych kryteriów filtrowania, aby przyspieszyć eksport i uniknąć timeout. Sprawdź limity eksportów przed utworzeniem nowego eksportu.
4. Optymalizuj zakresy dat
Optymalizuj zakresy dat eksportu, aby uniknąć timeout: używaj mniejszych zakresów dat (np. miesiąc zamiast roku), dziel większe eksporty na mniejsze części, rozważ eksporty przyrostowe (tylko nowe faktury od ostatniego eksportu). Mniejsze eksporty są szybsze i mniej podatne na timeout.
Najczęstsze problemy i rozwiązania
Eksport wygasł (status 210)
Status 210 oznacza, że eksport wygasł (timeout). Eksporty mają ograniczony czas ważności. Jeśli eksport wygasł, utwórz nowe żądanie eksportu. Rozważ użycie mniejszych zakresów dat lub innych kryteriów filtrowania, aby przyspieszyć eksport i uniknąć timeout. Sprawdź limity eksportów przed utworzeniem nowego eksportu.
Eksport wisi na statusie 100 przez długi czas
Status 100 oznacza, że eksport jest w trakcie przetwarzania. Eksporty mogą trwać długo, w zależności od liczby faktur i obciążenia systemu. Jeśli eksport wisi zbyt długo (np. kilka godzin lub dni), rozważ: ustawienie timeout po stronie klienta, ponowienie eksportu z mniejszymi zakresami dat, skontaktowanie się z supportem KSeF. Niektóre eksporty mogą wisieć na statusie 100 przez długi czas, szczególnie w środowisku testowym.
Jak uniknąć timeout eksportów?
Używaj mniejszych zakresów dat (np. miesiąc zamiast roku), dziel większe eksporty na mniejsze części, rozważ eksporty przyrostowe (tylko nowe faktury od ostatniego eksportu), optymalizuj kryteria filtrowania, monitoruj status eksportu i ustaw timeout po stronie klienta. Mniejsze eksporty są szybsze i mniej podatne na timeout.
Różnice między środowiskami
Timeout eksportów może się różnić między środowiskami: środowisko testowe może mieć dłuższe czasy przetwarzania i częstsze timeout, środowisko demo ma limity pośrednie, środowisko produkcja ma zoptymalizowane czasy przetwarzania. Przetestuj eksporty w środowisku testowym, aby zrozumieć zachowanie przed produkcją.
Status 210 - eksport wygasł
Status 210 oznacza, że eksport wygasł (timeout). Eksporty mają ograniczony czas ważności, który zależy od liczby faktur, obciążenia systemu i innych czynników. Po wygaśnięciu eksport nie może być już pobrany. Jeśli eksport wygasł, utwórz nowe żądanie eksportu. Rozważ użycie mniejszych zakresów dat lub innych kryteriów filtrowania, aby przyspieszyć eksport i uniknąć timeout.
Zawieszone eksporty (status 100)
Status 100 oznacza, że eksport jest w trakcie przetwarzania. Eksporty mogą trwać długo, w zależności od liczby faktur i obciążenia systemu. Niektóre eksporty mogą wisieć na statusie 100 przez kilka godzin lub nawet dni, szczególnie w środowisku testowym. Jeśli eksport wisi zbyt długo, rozważ: ustawienie timeout po stronie klienta, ponowienie eksportu z mniejszymi zakresami dat, skontaktowanie się z supportem KSeF.
Strategie obsługi timeout
Strategie obsługi: monitorowanie statusu eksportu (regularne sprawdzanie statusu, np. co 5-15 minut), ustawienie timeout po stronie klienta (np. 15-30 minut), ponowienie eksportu z mniejszymi zakresami dat, optymalizacja kryteriów filtrowania, eksporty przyrostowe (tylko nowe faktury), obsługa błędów limitów eksportów. Mniejsze eksporty są szybsze i mniej podatne na timeout.
Optymalizacja eksportów
Optymalizuj eksporty, aby uniknąć timeout: używaj mniejszych zakresów dat (np. miesiąc zamiast roku), dziel większe eksporty na mniejsze części, rozważ eksporty przyrostowe (tylko nowe faktury od ostatniego eksportu), optymalizuj kryteria filtrowania (mniej faktur = szybszy eksport), monitoruj limity eksportów. Mniejsze eksporty są szybsze i mniej podatne na timeout, ale wymagają więcej żądań.
FAQ
Co oznacza status 210 w eksporcie?
Status 210 oznacza, że eksport wygasł (timeout). Eksporty mają ograniczony czas ważności. Jeśli eksport wygasł, utwórz nowe żądanie eksportu. Rozważ użycie mniejszych zakresów dat lub innych kryteriów filtrowania, aby przyspieszyć eksport i uniknąć timeout.
Dlaczego eksport wisi na statusie 100?
Status 100 oznacza, że eksport jest w trakcie przetwarzania. Eksporty mogą trwać długo, w zależności od liczby faktur i obciążenia systemu. Niektóre eksporty mogą wisieć na statusie 100 przez kilka godzin lub nawet dni, szczególnie w środowisku testowym. Jeśli eksport wisi zbyt długo, rozważ ponowienie eksportu z mniejszymi zakresami dat.
Jak uniknąć timeout eksportów?
Używaj mniejszych zakresów dat (np. miesiąc zamiast roku), dziel większe eksporty na mniejsze części, rozważ eksporty przyrostowe (tylko nowe faktury od ostatniego eksportu), optymalizuj kryteria filtrowania, monitoruj status eksportu i ustaw timeout po stronie klienta. Mniejsze eksporty są szybsze i mniej podatne na timeout.
Jak obsłużyć wygasły eksport?
Gdy eksport otrzyma status 210 (wygasł), utwórz nowe żądanie eksportu. Rozważ użycie mniejszych zakresów dat lub innych kryteriów filtrowania, aby przyspieszyć eksport i uniknąć timeout. Sprawdź limity eksportów przed utworzeniem nowego eksportu. Monitoruj status nowego eksportu, aby uniknąć kolejnego timeout.
Czy mogę anulować zawieszony eksport?
Obecnie nie ma endpointu do anulowania eksportu. Jeśli eksport wisi na statusie 100 przez zbyt długi czas, możesz utworzyć nowe żądanie eksportu, ale pamiętaj o limitach eksportów (np. 10 aktywnych eksportów). Stary eksport może nadal być przetwarzany w tle, ale możesz go zignorować, jeśli utworzysz nowy eksport.