KSeF błędy API
Co musisz wiedzieć
Krajowy System e-Faktur (KSeF) jest centralnym systemem administracji skarbowej do wystawiania i otrzymywania faktur ustrukturyzowanych w formacie XML.
Na tej stronie znajdziesz uporządkowane informacje dotyczące tematu: KSeF błędy API. Opis koncentruje się na aktualnych przepisach oraz komunikatach Ministerstwa Finansów.
Instrukcja krok po kroku
1. Zidentyfikuj kod błędu
API KSeF zwraca kod błędu w odpowiedzi HTTP i w treści JSON. Zanotuj kod statusu HTTP (400, 401, 403, 500) oraz szczegółowy kod błędu z pola exceptionCode (np. 21405, 30001).
2. Sprawdź dokumentację błędów
Odszukaj kod błędu w dokumentacji API KSeF 2.0 na stronie Ministerstwa Finansów. Dokumentacja OpenAPI zawiera opisy wszystkich kodów z zalecanymi działaniami naprawczymi.
3. Przeanalizuj treść błędu
W odpowiedzi API pole Details/exceptionDetailList zawiera szczegółowy opis przyczyny błędu. Przeczytaj komunikat, aby zrozumieć, co wymaga poprawki.
4. Napraw przyczynę błędu
Postępuj zgodnie z zaleceniami dla danego kodu: popraw strukturę XML, odśwież token, sprawdź uprawnienia, poczekaj przy błędach serwera. Po naprawie ponów operację.
5. Zaimplementuj obsługę błędów
W kodzie integracyjnym zaimplementuj: logowanie błędów, retry z backoffem dla błędów przejściowych (5xx), powiadomienia dla użytkowników o odrzuconych fakturach.
Najczęstsze problemy i rozwiązania
API zwraca błąd 401 - brak autoryzacji
Sprawdź, czy accessToken nie wygasł (pole exp w JWT). Odśwież token za pomocą POST /api/v2/auth/token/refresh. Upewnij się, że masz odpowiednie uprawnienia (InvoiceWrite, InvoiceRead).
Błąd walidacji 21405 - nieprawidłowy payload
Struktura lub dane w żądaniu są nieprawidłowe. Sprawdź pole Details, które wskazuje konkretny element niezgodny z wymaganiami. Popraw dane i ponów żądanie.
Błąd 500 - serwer nie odpowiada
Błąd 500 oznacza problem po stronie KSeF. Poczekaj kilka minut i ponów próbę. Sprawdź status systemu na ksef.podatki.gov.pl. Przy częstych błędach zgłoś problem do MF.
Kategorie błędów API
| Kategoria | Kody | Opis |
|---|---|---|
| Walidacja | 21xxx | Błędy struktury lub formatu danych |
| Duplikaty | 30xxx | Konflikt z istniejącymi danymi |
| Certyfikaty | 25xxx | Problemy z certyfikatami KSeF |
| HTTP 4xx | 400, 401, 403, 404 | Błędy klienta (dane, autoryzacja) |
| HTTP 5xx | 500, 502, 503 | Błędy serwera (przejściowe) |
Obsługa błędów w kodzie
Zaimplementuj strategię obsługi błędów: 1) Loguj wszystkie odpowiedzi błędów z timestampem i kodem. 2) Dla błędów 5xx stosuj retry z wykładniczym backoffem. 3) Dla błędów 4xx wyświetl użytkownikowi czytelny komunikat. 4) Dla błędów walidacji zwróć szczegóły do poprawy.
Najczęstsze przyczyny błędów
Typowe przyczyny: wygasły accessToken (odśwież przez refresh), niezgodność struktury XML ze schematem (zwaliduj lokalnie przed wysyłką), brak uprawnień (sprawdź uprawnienia użytkownika), duplikat danych (sprawdź istniejące zasoby przed utworzeniem).
Dokumentacja i zasoby
Pełna dokumentacja błędów: specyfikacja OpenAPI na ksef.podatki.gov.pl, repozytorium GitHub CIRFMF/ksef-docs, podręcznik integratora. Wsparcie: formularz kontaktowy MF, producent oprogramowania, fora branżowe.
FAQ
Jakie są najczęstsze błędy API KSeF?
Najczęstsze błędy to: błędy walidacji struktury pliku XML, błędy autoryzacyjne (nieprawidłowy token, brak uprawnień), błędy logiczne (powiązania między dokumentami) oraz błędy systemowe (niedostępność serwera).
Jak interpretować kody błędów API KSeF?
Każdy błąd ma unikalny kod i opis. Kody 2xx dotyczą walidacji, 3xx autoryzacji, 4xx nieprawidłowych dokumentów, 5xx błędów systemowych. Szczegółowa dokumentacja kodów jest dostępna w dokumentacji API.
Co zrobić, gdy API zwraca błąd walidacji?
Sprawdź strukturę pliku XML pod kątem zgodności ze schematem XSD. Upewnij się, że wszystkie wymagane pola są wypełnione, formaty dat są poprawne i struktura odpowiada aktualnemu schematowi FA(2) lub FA(3).
Jak logować błędy API KSeF?
Zaleca się logowanie wszystkich odpowiedzi API wraz z kodem błędu i opisem. Wdróż system powiadomień dla użytkownika końcowego informujący o odrzuconych fakturach lub żądaniach.