Jak sprawdzić status faktury w KSeF po wysyłce?

Status faktury w KSeF pokazuje, czy dokument jest jeszcze w przetwarzaniu, zakończył się sukcesem, czy wymaga diagnostyki błędu. Sama informacja, że faktura została wysłana, nie wystarcza do uznania jej za przyjętą.

Statusy 100 i 150 to stany przejściowe, 200 oznacza sukces faktury, a statusy błędów wymagają odczytania szczegółów przed jakąkolwiek ponowną wysyłką. Nie myl technicznej odpowiedzi HTTP 200 OK ze statusem faktury zapisanym w polu statusu dokumentu.

Status sesji, numer referencyjny faktury, numer KSeF i UPO to różne elementy tego samego procesu. Dopiero ich połączenie mówi, czy czekać, pobrać potwierdzenie, czy diagnozować odrzucenie.

Po wysłaniu XML sprawdź status tej samej faktury lub sesji, nie wysyłaj automatycznie drugiej wersji, przy statusie 200 zapisz numer KSeF i UPO, a przy błędzie odczytaj kod, opis i szczegóły odpowiedzi przed kolejną decyzją.

Faktura została wysłana do KSeF, ale nie wiesz, czy jest już przyjęta, nadal się przetwarza, czy została odrzucona. Ten poradnik prowadzi przez decyzje po wysyłce, od statusu przejściowego po numer KSeF, UPO albo diagnostykę błędu.

Po wysyłce powinien zostać ślad techniczny i biznesowy. Jeżeli masz tylko ogólny komunikat o wysłaniu, nie masz jeszcze pełnej kontroli nad procesem.

Minimalny zestaw danych to numer referencyjny sesji, numer referencyjny faktury, numer własny faktury z pola P_2, NIP sprzedawcy, data wysyłki, status, ewentualny numer KSeF i informacja o UPO. Te elementy pozwalają wrócić do tej samej operacji, zamiast zgadywać, czy trzeba wysłać dokument ponownie.

Status sesji mówi o stanie kontenera wysyłki. Status faktury mówi o konkretnym dokumencie w tej sesji. Numer referencyjny pozwala wrócić do operacji technicznej, ale nie jest numerem KSeF.

W sesji interaktywnej możesz śledzić pojedynczy dokument przesłany w ramach sesji. W sesji wsadowej albo przy wielu fakturach trzeba dodatkowo sprawdzić, ile dokumentów przeszło poprawnie, ile zostało odrzuconych i jakie statusy mają poszczególne faktury.

Numer KSeF pojawia się dopiero po przyjęciu faktury. Jeżeli widzisz tylko numer referencyjny, jesteś na etapie śledzenia operacji, a nie na etapie potwierdzonego przyjęcia dokumentu.

Najważniejsza zasada po wysyłce brzmi: status przejściowy monitorujesz, sukces archiwizujesz, błąd diagnozujesz. Nie ma jednego przycisku ani jednego kodu, który zastępuje sprawdzenie statusu faktury.

Poniższa tabela jest praktyczną mapą decyzji. Nie zastępuje pełnej dokumentacji API, ale pomaga uniknąć najczęstszych pomyłek po wysyłce XML.

Jeżeli status faktury to 100 albo 150, podstawową reakcją jest dalsze monitorowanie tej samej wysyłki. Nie publikuj wewnętrznie informacji, że faktura jest już przyjęta, ale też nie traktuj jej automatycznie jako odrzuconej.

Jeżeli status faktury to 200, przejdź do numeru KSeF, daty przyjęcia i UPO. To etap porządkowania potwierdzeń, a nie szukania przyczyny błędu.

Jeżeli status wskazuje błąd, nie szukasz UPO. Odczytujesz kod, opis, szczegóły i ewentualne dane duplikatu. Dopiero potem decydujesz, czy poprawić dane, naprawić uprawnienia, odszukać pierwotną wysyłkę, czy ponowić operację techniczną.

Nie traktuj statusu sesji jako automatycznego potwierdzenia sukcesu każdego dokumentu. Sesja i faktury mają odrębne poziomy kontroli. W szczególności przy paczkach trzeba sprawdzić liczniki poprawnie i niepoprawnie przetworzonych faktur oraz listę dokumentów w sesji.

W praktyce nie wystarczy sprawdzić, czy sesja jest przetworzona. Trzeba ustalić, które faktury w tej sesji mają sukces, które mają błąd i jakie identyfikatory trzeba zapisać. To chroni przed sytuacją, w której paczka wygląda na obsłużoną, ale pojedyncza faktura wymaga poprawy.

Brak UPO nie jest samodzielną diagnozą. Przy statusach 100 i 150 UPO nie jest jeszcze punktem docelowym, bo faktura nadal nie ma wyniku końcowego.

Przy statusie 200 sprawdź numer KSeF, wygenerowany link do UPO, termin ważności linku i narzędzie, przez które dokument został wysłany. Link do pobrania UPO jest elementem odpowiedzi statusowej i może wymagać ponownego odpytywania statusu, gdy link wygasł.

Jeżeli problemem jest brak widocznego potwierdzenia, przejdź do poradnika Brak UPO w KSeF. Ten artykuł skupia się na statusie po wysyłce, a nie na pełnej procedurze odzyskiwania UPO.

Ponowna wysyłka ma sens dopiero po ustaleniu, co stało się z poprzednią operacją. Jeżeli nie wiesz, czy dokument nie dostał już numeru KSeF albo czy API nie wskazało duplikatu, druga wysyłka może tylko pogorszyć ślad zdarzeń.

Przy kodzie 440 najpierw odszukaj pierwotną sesję i pierwotny numer KSeF, jeśli zostały zwrócone. Przy błędach XML, semantyki albo uprawnień popraw źródło problemu, a nie tylko końcowy plik.

Szczegółową procedurę diagnozy znajdziesz w poradniku Faktura odrzucona przez KSeF.

W ścieżce użytkowej zacznij od właściwego podmiotu. Wybierz prawidłowy NIP sprzedawcy albo kontekst firmy, bo status odczytany w złym podmiocie nie wyjaśni realnej wysyłki.

Następnie odszukaj fakturę po numerze własnym, dacie, kontrahencie, numerze referencyjnym albo numerze KSeF, jeśli już został nadany. Sprawdź status dokumentu, a nie tylko status ostatniej akcji w interfejsie.

Jeżeli faktura ma sukces, zapisz numer KSeF i pobierz UPO w narzędziu, które obsłużyło wysyłkę. Jeżeli status wskazuje błąd, odczytaj szczegóły. Nie podaję tutaj nazw przycisków jako pewnych, bo interfejsy aplikacji i podręczniki mogą się zmieniać.

W integracji API status sprawdza się etapami. Najpierw ustalasz sesję, potem dokumenty w sesji, a dopiero po sukcesie konkretnej faktury przechodzisz do UPO. UPO nie zastępuje statusu, tylko jest kolejnym krokiem po potwierdzonym sukcesie.

Typowe ścieżki kontrolne obejmują listę sesji, szczegóły konkretnej sesji, listę faktur w sesji, szczegóły konkretnej faktury oraz listę faktur odrzuconych.

Integracja powinna zapisywać co najmniej numer referencyjny sesji, numer referencyjny faktury, status, numer KSeF, datę przyjęcia, błędy i informacje o UPO. Bez tych danych późniejsza obsługa reklamacji, duplikatu albo braku potwierdzenia staje się ręczna.

W KSeFGPT status po wysyłce ma być czytelny dla osoby, która nie chce analizować surowej odpowiedzi API. Po obsłużeniu wysyłki aplikacja pomaga zobaczyć, czy dokument został przekazany do KSeF, jaki ma status, czy pojawił się numer KSeF oraz czy dla obsługiwanego dokumentu dostępne jest UPO.

To ważne rozróżnienie: KSeFGPT porządkuje statusy i potwierdzenia dla faktur wysyłanych przez tę aplikację. Nie należy zakładać, że narzędzie pobierze UPO dla każdej faktury, która została kiedyś wysłana innym ERP albo inną integracją. W takim przypadku szukaj potwierdzenia w systemie, który wykonał wysyłkę, w Aplikacji Podatnika KSeF albo we własnej integracji API.

Praktycznie oznacza to jeden ślad pracy: faktura, status, numer KSeF i potwierdzenie są powiązane w tym samym kontekście. Dzięki temu łatwiej odróżnić dokument przetwarzany od przyjętego, a błąd od braku widocznego UPO.

Najczęstsze błędy nie wynikają z jednego trudnego kodu, tylko z pomieszania warstw: HTTP, sesji, faktury, numeru referencyjnego, numeru KSeF i UPO.

Po wysyłce faktury do KSeF pracuj według stałej sekwencji: sprawdź status, sprawdź identyfikatory, zdecyduj, czy czekać, pobrać UPO, czy diagnozować błąd. Nie zaczynaj od ponownej wysyłki i nie archiwizuj samego numeru referencyjnego jako dowodu przyjęcia.

Jeżeli potrzebujesz pełnego procesu, zacznij od Wysyłka faktur do KSeF. Po statusie sukcesu przejdź do UPO w KSeF. Gdy potwierdzenia nie widać, użyj poradnika Brak UPO w KSeF. Przy błędzie dokumentu przejdź do Faktura odrzucona przez KSeF.