Brak UPO w KSeF: jak pobrać urzędowe poświadczenie odbioru?

Brak UPO po wysłaniu faktury do KSeF nie jest samodzielną diagnozą. Najpierw sprawdź status faktury albo sesji, numer KSeF, numer referencyjny, kontekst NIP i narzędzie, przez które dokument został wysłany.

UPO można pobrać dopiero dla faktury poprawnie przyjętej przez KSeF albo dla zamkniętej i przetworzonej sesji, jeśli powstało UPO sesyjne. Status 100 lub 150 oznacza, że trzeba dalej monitorować tę samą wysyłkę, a nie od razu tworzyć kolejną.

Jeżeli faktura została odrzucona, nie dostanie numeru KSeF ani UPO. Wtedy trzeba odczytać kod błędu, poprawić źródło problemu i dopiero po weryfikacji wysłać poprawny XML ponownie.

Najgorsza reakcja na brak UPO to automatyczne ponowienie wysyłki bez sprawdzenia statusu. Możesz wtedy stworzyć duplikat albo utrudnić ustalenie, która operacja była pierwotna.

Brak widocznego UPO może wynikać z przetwarzania, błędu dokumentu, pracy w złej sesji, wygasłego linku albo ograniczeń narzędzia, w którym szukasz potwierdzenia. Dlatego procedura zawsze zaczyna się od statusu tej samej faktury lub sesji.

Status wysyłki mówi więcej niż sam komunikat, że plik został przekazany do systemu. W API KSeF status 100 oznacza przyjęcie faktury do dalszego przetwarzania, status 150 oznacza trwające przetwarzanie, a status 200 oznacza sukces.

Dopiero sukces faktury pozwala przejść do numeru KSeF i UPO. Statusy błędów wymagają diagnozy. Wtedy szukanie UPO nie ma sensu, dopóki nie wiadomo, czy dokument w ogóle został przyjęty.

W ścieżce ręcznej zacznij od właściwego kontekstu podatnika. Zaloguj się do Aplikacji Podatnika KSeF 2.0, wybierz odpowiedni podmiot albo NIP i odszukaj fakturę po numerze własnym, numerze KSeF, dacie lub danych wysyłki.

Następnie sprawdź status dokumentu. Jeżeli faktura jest przyjęta i ma numer KSeF, pobierz UPO z akcji dostępnej przy fakturze albo przy sesji. Jeżeli status wskazuje błąd, przejdź do diagnostyki odrzucenia zamiast pobierać potwierdzenie, które nie powstało.

Nie opisuję tu nazw przycisków jako pewnych, bo interfejs Aplikacji Podatnika może się zmieniać. Przed publikacją instrukcji krok po kroku trzeba porównać ją z aktualnym podręcznikiem MF albo z bieżącym ekranem aplikacji.

W integracji API najpierw pobierasz listę sesji albo status konkretnej sesji, potem listę faktur w sesji lub status pojedynczej faktury. Dopiero po ustaleniu, że dokument został poprawnie przyjęty, przechodzisz do endpointu UPO.

Dokumentacja CIRF opisuje dwie ścieżki dla UPO pojedynczej faktury: po numerze referencyjnym faktury oraz po numerze KSeF. Dla UPO sesji dokumentacja wskazuje osobny endpoint z numerem referencyjnym UPO.

W praktyce integracja powinna zapisywać numer referencyjny sesji, numer referencyjny faktury, numer KSeF, status, datę przyjęcia i link lub pobrany XML UPO. Bez tych danych późniejsze szukanie potwierdzenia jest znacznie trudniejsze.

W codziennej pracy łatwo pomylić UPO faktury z UPO sesji. UPO faktury dotyczy pojedynczego dokumentu. UPO sesji jest potwierdzeniem zbiorczym, które pojawia się po zamknięciu i przetworzeniu sesji.

Przy małej liczbie faktur zwykle interesuje Cię potwierdzenie dla konkretnej faktury. Przy wysyłce wsadowej liczy się też kontrola całej paczki: ile dokumentów przyjęto, ile odrzucono i z jakimi numerami KSeF trzeba połączyć UPO.

Numer KSeF identyfikuje fakturę przyjętą przez system i jest zwracany w UPO, ale przy pobieraniu przez endpointy sesyjne potrzebny jest także kontekst sesji. Sam numer KSeF bez wiedzy, gdzie i jak faktura była wysłana, może nie wystarczyć do sprawnego odtworzenia potwierdzenia.

Drugi częsty problem to mylenie numerów. Numer własny faktury pochodzi z systemu sprzedawcy, numer referencyjny sesji opisuje operację techniczną, a numer KSeF powstaje dopiero po przyjęciu faktury. Każdy z nich służy do czegoś innego.

Jeżeli masz tylko numer faktury z pola P_2, zacznij od wyszukania dokumentu w narzędziu, przez które faktura była wysłana. Dopiero potem odczytaj numer KSeF, numer sesji i ścieżkę do UPO.

Numer KSeF jest mocnym sygnałem, że faktura została przyjęta, ale problem z pobraniem UPO nadal może wystąpić po stronie linku, uprawnień, kontekstu albo aplikacji. Wtedy nie twórz nowej faktury i nie wysyłaj ponownie tego samego dokumentu.

Najpierw odśwież status faktury. Jeżeli odpowiedź zawiera link do UPO, sprawdź datę jego ważności. OpenAPI opisuje `upoDownloadUrl` jako link generowany przy odpytaniu o status, pobierany metodą HTTP GET i wygasający po określonym czasie.

Jeżeli link wygasł, wygeneruj go ponownie przez status. Jeżeli pracujesz przez aplikację, sprawdź, czy jesteś we właściwym NIP-ie i czy dana aplikacja obsługuje UPO dla tej faktury. W KSeFGPT UPO jest dostępne dla faktur wysłanych przez tę aplikację.

Jeżeli nie ma ani numeru KSeF, ani UPO, sprawa jest nadal otwarta. Dokument może być w przetwarzaniu albo mógł zostać odrzucony. Nie wysyłaj automatycznie kolejnej wersji, dopóki nie znasz końcowego statusu.

Sprawdź, czy status nie jest jeszcze 100 lub 150. Jeśli status wskazuje błąd, pobierz szczegóły, w tym kod, opis, szczegóły i ewentualne rozszerzenia. Przy kodzie 440 sprawdź pierwotną sesję i pierwotny numer KSeF, bo problem może dotyczyć duplikatu.

Pełną procedurę dla błędów znajdziesz w poradniku Faktura odrzucona przez KSeF. Ten tekst odpowiada tylko na pytanie, dlaczego nie widzisz UPO i jak ustalić, czy potwierdzenie w ogóle powinno już istnieć.

KSeFGPT porządkuje proces po wysyłce: użytkownik widzi status dokumentu, numer referencyjny, wynik przetwarzania i dalsze akcje przy fakturze. To ważne, bo brak UPO nie powinien kończyć się ręcznym zgadywaniem, czy dokument został przyjęty.

Jeżeli faktura została wysłana przez KSeFGPT, aplikacja może pokazać jej status i umożliwić pobranie UPO w tym samym procesie. Jeżeli dokument był wysłany innym systemem, trzeba szukać potwierdzenia w tamtym narzędziu, Aplikacji Podatnika KSeF albo przez integrację API.

Dzięki temu zespół księgowy ma jedną procedurę: sprawdzić status, odczytać numer KSeF, pobrać UPO po sukcesie albo przejść do diagnozy błędu. To ogranicza ryzyko, że faktura zostanie ponownie wysłana tylko dlatego, że potwierdzenie nie było widoczne na pierwszym ekranie.

FAQ techniczne MF wskazuje, że nie ma obowiązku pobierania i archiwizowania UPO KSeF. Mimo to w pracy operacyjnej warto zapisywać UPO lokalnie, bo ułatwia audyt, kontrolę statusów i wyjaśnianie pytań kontrahenta.

Najlepiej przechowywać komplet: XML faktury, numer KSeF, UPO, numer własny faktury z P_2, datę przyjęcia, NIP sprzedawcy, kontekst podatnika oraz informację, przez jakie narzędzie faktura była wysłana.

Prosta konwencja nazwy pliku może wyglądać tak: `NIP_sprzedawcy-numer_faktury-numer_KSeF-upo.xml`. Ważniejsze od samej nazwy jest to, żeby zespół zawsze mógł połączyć UPO z konkretną fakturą, a nie tylko z paczką albo sesją.

Przy braku UPO nie zaczynaj od ponownej wysyłki. Najpierw sprawdź status tej samej faktury lub sesji, numer KSeF, numer referencyjny, kontekst NIP i źródło wysyłki. Dopiero wynik statusu mówi, czy trzeba czekać, pobrać link ponownie, szukać w innym narzędziu czy naprawiać błąd.

Jeżeli status jest 200, pobierz UPO i zapisz je z numerem KSeF oraz numerem własnym faktury. Jeżeli status to 100 albo 150, monitoruj dalej. Jeżeli status wskazuje błąd, przejdź do diagnostyki odrzucenia zamiast tworzyć nową wersję dokumentu.

Do dalszego czytania: UPO w KSeF, Faktura odrzucona przez KSeF, Wysyłka faktur do KSeF oraz Ile czasu jest na wysyłkę do KSeF.