KSeF API pobieranie UPO po numerze KSeF – brak bezpośredniego endpointu

Pobieranie UPO po numerze KSeF

Urzędowe Poświadczenie Odbioru (UPO) to dokument XML podpisany przez Ministerstwo Finansów w formacie XAdES, potwierdzający przyjęcie faktury (lub całej sesji) do KSeF.

W KSeF API 2.0 wszystkie endpointy pobierania UPO są zagnieżdżone pod numerem referencyjnym sesji: GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}/upo (po numerze referencyjnym faktury w sesji) oraz GET /sessions/{referenceNumber}/invoices/ksef/{ksefNumber}/upo (po numerze KSeF faktury, ale nadal w obrębie konkretnej sesji). Nie istnieje wariant przyjmujący wyłącznie numer KSeF, bez referenceNumber sesji.

Sprawdzenie stanu sesji (GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}) zwraca też pole upoDownloadUrl z bezpośrednim linkiem do UPO danej faktury oraz upoDownloadUrlExpirationDate - datę wygaśnięcia tego linku.

Jeśli znasz tylko numer KSeF faktury, a nie masz zapisanego numeru referencyjnego sesji, musisz go najpierw ustalić - np. z własnej ewidencji zapisanej przy wysyłce, albo przeszukując listę sesji (GET /sessions).

Instrukcja krok po kroku

1. Ustal numer referencyjny sesji

Każdy endpoint UPO wymaga referenceNumber sesji, w ramach której faktura została wysłana. Jeśli go nie masz, sprawdź własną ewidencję zapisaną przy wysyłce lub przeszukaj listę sesji przez GET /sessions.

2. Pobierz UPO po numerze KSeF w obrębie sesji

Wywołaj GET /sessions/{referenceNumber}/invoices/ksef/{ksefNumber}/upo, podając zarówno referenceNumber sesji, jak i numer KSeF faktury. Zwrócony jest dokument XML podpisany XAdES, zgodny ze schematem UPO.

3. Alternatywnie użyj numeru referencyjnego faktury

Jeśli zamiast numeru KSeF masz numer referencyjny faktury w sesji (invoiceReferenceNumber), użyj GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}/upo.

4. Skorzystaj z linku upoDownloadUrl ze statusu faktury

Sprawdzenie stanu pojedynczej faktury w sesji (GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}) zwraca pole upoDownloadUrl z bezpośrednim linkiem do UPO oraz upoDownloadUrlExpirationDate - datę, do której link jest ważny.

5. Zapisuj numer referencyjny sesji przy wysyłce

Najlepszą praktyką jest zapisywanie referenceNumber sesji razem z numerem KSeF faktury w lokalnej bazie danych już w momencie wysyłki - to jedyny sposób, aby później szybko pobrać UPO bez przeszukiwania listy sesji.

Najczęstsze problemy i rozwiązania

Nie mam numeru referencyjnego sesji - jak pobrać UPO?

Wszystkie endpointy UPO wymagają referenceNumber sesji - nie ma sposobu pobrania UPO wyłącznie po numerze KSeF. Sprawdź własną ewidencję zapisaną przy wysyłce faktury albo przeszukaj listę sesji przez GET /sessions, aby odnaleźć sesję, w której faktura została wysłana.

Czy istnieje endpoint do pobierania UPO po numerze KSeF?

Istnieje endpoint GET /sessions/{referenceNumber}/invoices/ksef/{ksefNumber}/upo, który przyjmuje numer KSeF jako parametr, ale nadal wymaga podania referenceNumber sesji. Nie ma wariantu przyjmującego wyłącznie numer KSeF faktury.

Link upoDownloadUrl wygasł

Pole upoDownloadUrlExpirationDate w odpowiedzi GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber} określa termin ważności linku upoDownloadUrl. Po jego wygaśnięciu pobierz UPO bezpośrednio przez GET /sessions/{referenceNumber}/invoices/ksef/{ksefNumber}/upo lub GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}/upo.

Znam tylko numer KSeF faktury, nie znam numeru sesji

Numer KSeF faktury nie zawiera informacji o sesji, a metadane faktury (POST /invoices/query/metadata) nie zwracają numeru referencyjnego sesji. Jedynym sposobem odnalezienia sesji jest przeszukanie listy sesji (GET /sessions) lub skorzystanie z własnej ewidencji zapisanej w momencie wysyłki faktury.

Brak endpointu wyłącznie po numerze KSeF

W KSeF API 2.0 wszystkie trzy endpointy UPO są zagnieżdżone pod numerem referencyjnym sesji: GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}/upo, GET /sessions/{referenceNumber}/invoices/ksef/{ksefNumber}/upo oraz zbiorcze GET /sessions/{referenceNumber}/upo/{upoReferenceNumber}. Numer KSeF faktury można użyć jako parametr jednego z wariantów, ale referenceNumber sesji jest zawsze wymagany.

Dwa warianty pobrania UPO pojedynczej faktury

GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}/upo pobiera UPO na podstawie numeru referencyjnego faktury w sesji. GET /sessions/{referenceNumber}/invoices/ksef/{ksefNumber}/upo pobiera to samo UPO na podstawie numeru KSeF faktury - oba warianty zwracają dokument XML podpisany XAdES przez Ministerstwo Finansów, zgodny ze schematem UPO.

UPO zbiorcze sesji

Po zamknięciu sesji odpowiedź GET /sessions/{referenceNumber} zawiera listę referencji do zbiorczych UPO w polu upo.pages[] (referenceNumber i downloadUrl dla każdej strony). Zbiorcze UPO potwierdza przyjęcie wszystkich poprawnie przesłanych faktur w danej sesji i może obejmować maksymalnie 10 000 pozycji faktur na jeden dokument.

Link upoDownloadUrl i termin jego ważności

Odpowiedź GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber} zawiera pole upoDownloadUrl - bezpośredni link do pobrania UPO danej faktury - oraz upoDownloadUrlExpirationDate, czyli datę wygaśnięcia tego linku. Po wygaśnięciu linku UPO nadal można pobrać przez wskazane wyżej endpointy /upo.

Najlepsze praktyki

Zapisuj numer referencyjny sesji (referenceNumber) razem z numerem KSeF faktury w lokalnej bazie danych już w momencie wysyłki - to jedyny niezawodny sposób, aby później szybko pobrać UPO. Jeśli tego nie zrobiłeś, jedynym pozostałym sposobem odnalezienia sesji jest przeszukanie listy sesji przez GET /sessions.

FAQ

Powiązane tematy

• KSeF API pobieranie faktur
• KSeF API sesja odzyskiwanie danych
• KSeF API wysyłanie faktur