KSeF API eksport paczek faktur
Eksport paczek faktur w KSeF API
KSeF API 2.0 umożliwia eksport paczek faktur w formacie ZIP zaszyfrowanym algorytmem AES-256-CBC. Eksporty są asynchroniczne i mogą trwać długo, w zależności od liczby faktur i obciążenia systemu.
System stosuje limity eksportów: maksymalna liczba aktywnych eksportów (np. 10), limit wywołań eksportu (np. 4 na godzinę). Przekroczenie limitów powoduje błędy (np. 21182 - Osiągnięto limit trwających eksportów).
Eksporty wymagają monitorowania statusu i obsługi timeout. Niektóre eksporty mogą wisieć na statusie 100 (w trakcie przetwarzania) przez długi czas, wymagając cierpliwości lub ponowienia eksportu.
Instrukcja krok po kroku
1. Utwórz żądanie eksportu
Wywołaj endpoint POST /api/v2/invoices/export z parametrami określającymi zakres dat, kryteria filtrowania i format eksportu. W odpowiedzi otrzymasz referenceNumber eksportu, który służy do monitorowania statusu.
2. Monitoruj status eksportu
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 regularnie sprawdzaj status.
3. Pobierz paczkę po zakończeniu
Gdy status eksportu to 200 (zakończony pomyślnie), pobierz paczkę faktur używając odpowiedniego endpointu. Paczka jest w formacie ZIP zaszyfrowanym algorytmem AES-256-CBC. Odszyfruj paczkę i wyciągnij faktury.
4. Obsłuż timeout i błędy
Obsłuż timeout eksportu (status 210) i błędy limitów (np. 21182). Jeśli eksport wygasł lub osiągnięto limit, rozważ ponowienie eksportu z innymi parametrami lub poczekaj na zwolnienie limitów. Monitoruj limity eksportów, aby uniknąć przekroczenia.
Najczęstsze problemy i rozwiązania
Błąd 21182 - Osiągnięto limit trwających eksportów
Błąd oznacza, że osiągnięto maksymalną liczbę aktywnych eksportów (np. 10). Poczekaj na zakończenie niektórych eksportów lub anuluj niepotrzebne eksporty. Sprawdź status wszystkich aktywnych eksportów i zamknij te, które nie są już potrzebne. Monitoruj limity eksportów, aby uniknąć przekroczenia.
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. Regularnie sprawdzaj status eksportu. Jeśli eksport wisi zbyt długo (np. kilka dni), rozważ ponowienie eksportu lub skontaktowanie się z supportem KSeF.
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.
Jak sprawdzić status eksportu bez numeru referencyjnego?
Obecnie nie ma endpointu do listowania eksportów bez numeru referencyjnego. Zaleca się zapisywanie numerów referencyjnych eksportów w lokalnej bazie danych. Jeśli numer referencyjny został utracony, możesz utworzyć nowe żądanie eksportu, ale pamiętaj o limitach eksportów.
Limity eksportów
System stosuje limity eksportów: maksymalna liczba aktywnych eksportów (np. 10), limit wywołań eksportu (np. 4 na godzinę). Przekroczenie limitów powoduje błędy (np. 21182 - Osiągnięto limit trwających eksportów). Monitoruj limity eksportów, aby uniknąć przekroczenia. Sprawdź status wszystkich aktywnych eksportów i zamknij te, które nie są już potrzebne.
Status eksportu
Status eksportu może być: 100 (w trakcie przetwarzania - eksport jest przetwarzany przez system), 200 (zakończony pomyślnie - paczka jest gotowa do pobrania), 210 (wygasł - eksport przekroczył czas ważności), błędy (różne kody błędów). Eksporty mogą trwać długo, więc regularnie sprawdzaj status. Niektóre eksporty mogą wisieć na statusie 100 przez długi czas.
Format paczki eksportu
Paczka eksportu jest w formacie ZIP zaszyfrowanym algorytmem AES-256-CBC. Paczka zawiera faktury w formacie XML zgodnym ze schematem XSD. Po pobraniu paczki odszyfruj ją używając klucza szyfrowania i wyciągnij faktury. Format paczki jest zgodny z wymaganiami KSeF API 2.0.
Obsługa timeout i błędów
Obsłuż timeout eksportu (status 210) i błędy limitów (np. 21182). Jeśli eksport wygasł, utwórz nowe żądanie eksportu. Jeśli osiągnięto limit, poczekaj na zakończenie niektórych eksportów lub anuluj niepotrzebne. Rozważ użycie mniejszych zakresów dat lub innych kryteriów filtrowania, aby przyspieszyć eksport i uniknąć timeout. Monitoruj limity eksportów.
FAQ
Jak utworzyć eksport paczek faktur?
Wywołaj endpoint POST /api/v2/invoices/export z parametrami określającymi zakres dat, kryteria filtrowania i format eksportu. W odpowiedzi otrzymasz referenceNumber eksportu, który służy do monitorowania statusu. Eksporty są asynchroniczne i mogą trwać długo.
Jak sprawdzić status eksportu?
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 regularnie sprawdzaj status.
Co oznacza błąd 21182?
Błąd 21182 oznacza, że osiągnięto maksymalną liczbę aktywnych eksportów (np. 10). Poczekaj na zakończenie niektórych eksportów lub anuluj niepotrzebne eksporty. Sprawdź status wszystkich aktywnych eksportów i zamknij te, które nie są już potrzebne.
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. Regularnie sprawdzaj status eksportu. Jeśli eksport wisi zbyt długo (np. kilka dni), rozważ ponowienie eksportu lub skontaktowanie się z supportem KSeF.
Co zrobić, gdy eksport wygasł?
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.