Jak pobrać UPO po numerze KSeF faktury bez session reference?

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

W KSeF API 2.0 nie ma bezpośredniego endpointu do pobierania UPO (Urzędowego Poświadczenia Odbioru) po numerze KSeF faktury bez znajomości numeru referencyjnego sesji. UPO można pobrać ze statusu faktury lub użyć originalSessionReferenceNumber przy ponownym wysłaniu faktury.

Pobieranie UPO po numerze KSeF

Urzędowe Poświadczenie Odbioru (UPO) to dokument potwierdzający przyjęcie faktury do KSeF. UPO zawiera numer KSeF faktury i jest generowane w momencie przetwarzania faktury przez system.

W KSeF API 2.0 nie ma bezpośredniego endpointu do pobierania UPO wyłącznie po numerze KSeF faktury bez znajomości numeru referencyjnego sesji, pod którym faktura została wysłana. Jest to celowe zabezpieczenie, aby UPO nie dostało się w niepowołane ręce.

Alternatywne metody pobierania UPO: pobranie UPO ze statusu faktury (link do UPO jest zwracany w odpowiedzi statusu), użycie originalSessionReferenceNumber przy ponownym wysłaniu faktury (jeśli faktura była wcześniej wysłana), pobranie UPO z odpowiedzi na wysłanie faktury (jeśli UPO jest dostępne natychmiast).

Link do UPO w odpowiedziach API jest zabezpieczony czasem ważności (aktywnością) i wymaga autoryzacji w odpowiednim kontekście (NIP). UPO może być dostępne nawet jeśli faktura "zniknęła" z KSeF, ponieważ UPO jest generowane osobno w momencie przetwarzania.

Instrukcja krok po kroku

1. Pobierz status faktury

Użyj endpointu GET /api/v2/invoices/ksef/{ksefNumber}/status, aby pobrać status faktury po numerze KSeF. W odpowiedzi statusu znajdziesz link do UPO (pole invoiceUpoUrl lub podobne), jeśli UPO jest dostępne. Link jest zabezpieczony czasem ważności i wymaga autoryzacji.

2. Użyj originalSessionReferenceNumber

Jeśli faktura była wcześniej wysłana i została ponownie wysłana, w odpowiedzi na ponowne wysłanie znajdziesz pola originalSessionReferenceNumber i originalKsefNumber. Możesz użyć originalSessionReferenceNumber do pobrania UPO z sesji, jeśli UPO jest dostępne dla tej sesji.

3. Pobierz UPO z odpowiedzi na wysłanie

Po wysłaniu faktury do KSeF, w odpowiedzi na wysłanie (status przetwarzania) może być dostępny link do UPO, jeśli faktura została przyjęta. Zapisz link do UPO natychmiast po wysłaniu faktury, aby mieć dostęp do UPO bez konieczności znajomości session reference.

4. Zapisz session reference

Najlepszą praktyką jest zapisywanie numeru referencyjnego sesji (sessionReferenceNumber) razem z numerem KSeF faktury w lokalnej bazie danych. Dzięki temu będziesz mógł pobrać UPO z sesji w przyszłości, jeśli będzie potrzebne.

5. Obsłuż sytuację bez session reference

Jeśli nie masz session reference, użyj metody pobierania statusu faktury i sprawdź, czy link do UPO jest dostępny w odpowiedzi. Jeśli faktura "zniknęła" z KSeF, UPO może nadal być dostępne, ponieważ jest generowane osobno w momencie przetwarzania. Sprawdź również UPO sesji, jeśli jest dostępne.

Najczęstsze problemy i rozwiązania

Nie mam session reference - jak pobrać UPO?

Użyj endpointu GET /api/v2/invoices/ksef/{ksefNumber}/status, aby pobrać status faktury. W odpowiedzi statusu może być dostępny link do UPO. Jeśli faktura była ponownie wysłana, sprawdź pola originalSessionReferenceNumber i originalKsefNumber w odpowiedzi. Zapisz session reference razem z numerem KSeF w lokalnej bazie danych przy wysyłaniu faktury.

Czy istnieje endpoint do pobierania UPO po numerze KSeF?

Nie ma bezpośredniego endpointu do pobierania UPO wyłącznie po numerze KSeF bez znajomości session reference. Jest to celowe zabezpieczenie. Użyj alternatywnych metod: pobranie UPO ze statusu faktury, użycie originalSessionReferenceNumber, pobranie UPO z odpowiedzi na wysłanie faktury.

Link do UPO wygasł

Link do UPO w odpowiedziach API jest zabezpieczony czasem ważności (aktywnością). Jeśli link wygasł, spróbuj ponownie pobrać status faktury, aby uzyskać nowy link. Jeśli faktura "zniknęła" z KSeF, UPO może nadal być dostępne - sprawdź UPO sesji lub skontaktuj się z pomocą techniczną MF.

Faktura zniknęła z KSeF - czy UPO jest dostępne?

UPO może być dostępne nawet jeśli faktura "zniknęła" z KSeF, ponieważ UPO jest generowane osobno w momencie przetwarzania faktury. Sprawdź UPO sesji lub użyj originalSessionReferenceNumber, jeśli faktura była ponownie wysłana. Skontaktuj się z pomocą techniczną MF, jeśli potrzebujesz dostępu do UPO dla "znikniętej" faktury.

Brak bezpośredniego endpointu

W KSeF API 2.0 nie ma bezpośredniego endpointu do pobierania UPO wyłącznie po numerze KSeF faktury bez znajomości numeru referencyjnego sesji. Jest to celowe zabezpieczenie, aby UPO nie dostało się w niepowołane ręce. Zapytanie o Status/UPO to kwestia optymalizacji - nawet gdyby był endpoint, wymagałby autoryzacji w odpowiednim kontekście (NIP).

Alternatywne metody pobierania UPO

Pobranie UPO ze statusu faktury: użyj endpointu GET /api/v2/invoices/ksef/{ksefNumber}/status, w odpowiedzi znajdziesz link do UPO (pole invoiceUpoUrl lub podobne). Użycie originalSessionReferenceNumber: jeśli faktura była ponownie wysłana, w odpowiedzi znajdziesz pola originalSessionReferenceNumber i originalKsefNumber - możesz użyć originalSessionReferenceNumber do pobrania UPO z sesji. Pobranie UPO z odpowiedzi na wysłanie: po wysłaniu faktury, w odpowiedzi na status przetwarzania może być dostępny link do UPO - zapisz go natychmiast.

Zabezpieczenia dostępu do UPO

Link do UPO w odpowiedziach API jest zabezpieczony czasem ważności (aktywnością) - link wygasa po określonym czasie. Dostęp do UPO wymaga autoryzacji w odpowiednim kontekście (NIP) - musisz być zalogowany w kontekście wystawcy lub nabywcy faktury. UPO może być dostępne nawet jeśli faktura "zniknęła" z KSeF, ponieważ UPO jest generowane osobno w momencie przetwarzania faktury.

Najlepsze praktyki

Zapisz numer referencyjny sesji (sessionReferenceNumber) razem z numerem KSeF faktury w lokalnej bazie danych przy wysyłaniu faktury. Dzięki temu będziesz mógł pobrać UPO z sesji w przyszłości. Pobierz i zapisz link do UPO natychmiast po wysłaniu faktury, jeśli jest dostępny w odpowiedzi. Jeśli nie masz session reference, użyj metody pobierania statusu faktury i sprawdź, czy link do UPO jest dostępny. Rozważ użycie originalSessionReferenceNumber przy ponownym wysłaniu faktury, jeśli faktura była wcześniej wysłana.

FAQ

Czy istnieje endpoint do pobierania UPO po numerze KSeF?

Nie ma bezpośredniego endpointu do pobierania UPO wyłącznie po numerze KSeF bez znajomości session reference. Jest to celowe zabezpieczenie. Użyj alternatywnych metod: pobranie UPO ze statusu faktury (GET /api/v2/invoices/ksef/{ksefNumber}/status), użycie originalSessionReferenceNumber, pobranie UPO z odpowiedzi na wysłanie faktury.

Jak pobrać UPO bez session reference?

Użyj endpointu GET /api/v2/invoices/ksef/{ksefNumber}/status, aby pobrać status faktury. W odpowiedzi statusu może być dostępny link do UPO. Jeśli faktura była ponownie wysłana, sprawdź pola originalSessionReferenceNumber i originalKsefNumber w odpowiedzi. Najlepszą praktyką jest zapisywanie session reference razem z numerem KSeF przy wysyłaniu faktury.

Czy UPO jest dostępne, jeśli faktura zniknęła z KSeF?

Dlaczego nie ma endpointu do pobierania UPO po numerze KSeF?

Brak bezpośredniego endpointu to celowe zabezpieczenie, aby UPO nie dostało się w niepowołane ręce. Zapytanie o Status/UPO wymaga autoryzacji w odpowiednim kontekście (NIP), więc nawet gdyby był endpoint, wymagałby autoryzacji. Alternatywne metody (status faktury, originalSessionReferenceNumber) zapewniają dostęp do UPO przy zachowaniu bezpieczeństwa.

Link do UPO wygasł - co robić?

Link do UPO w odpowiedziach API jest zabezpieczony czasem ważności. Jeśli link wygasł, spróbuj ponownie pobrać status faktury, aby uzyskać nowy link. Jeśli faktura "zniknęła" z KSeF, sprawdź UPO sesji lub skontaktuj się z pomocą techniczną MF. Najlepszą praktyką jest zapisywanie linku do UPO natychmiast po wysłaniu faktury.