KSeF API – UPO i numer KSeF

Po wysłaniu faktury do KSeF integracja otrzymuje dwie różne informacje, które łatwo pomylić: numer KSeF i UPO. Oba dotyczą tej samej faktury, ale pełnią różną rolę — i tylko jedno z nich jest formalnym dowodem, że dokument został prawnie doręczony do systemu. Rozróżnienie to ma praktyczne znaczenie przy projektowaniu integracji, zwłaszcza w kontekście tego, co i kiedy zapisać jako dowód wysyłki.

Czym jest numer KSeF

Numer KSeF to unikalny identyfikator nadawany fakturze po jej pozytywnym przetworzeniu przez system. Jest zwracany w odpowiedzi API stosunkowo szybko po wysyłce i służy jako referencja do dokumentu — używa się go m.in. przy pobieraniu faktury, wystawianiu do niej korekty czy w komunikacji z kontrahentem.

Czym jest UPO

UPO — Urzędowe Poświadczenie Odbioru — to osobny dokument potwierdzający, że faktura została skutecznie i prawnie doręczona do Krajowego Systemu e-Faktur. To UPO, a nie sam numer KSeF, stanowi formalny dowód spełnienia obowiązku wystawienia faktury ustrukturyzowanej — i to ono powinno trafić do archiwum firmowego jako dokumentacja podatkowa.

Dlaczego to rozróżnienie ma znaczenie

Numer KSeF pojawia się w odpowiedzi na żądanie wysyłki i można go łatwo potraktować jako „potwierdzenie, że wszystko się udało". W praktyce to sygnał, że dokument został przyjęty do przetworzenia i zidentyfikowany w systemie — ale to UPO jest dokumentem, który warto przechowywać jako dowód prawny na wypadek kontroli czy sporu z kontrahentem. Integracja, która archiwizuje wyłącznie numer KSeF bez pobrania i zapisania UPO, pomija najważniejszy element potwierdzający zgodność z przepisami.

Jak wygląda pobranie UPO przez API

Proces pobrania UPO odbywa się zwykle jako osobne żądanie, wykonywane po otrzymaniu numeru KSeF i (w zależności od implementacji) numeru referencyjnego sesji wysyłki:

1. Wysyłka faktury. W odpowiedzi otrzymujesz numer KSeF oraz numer referencyjny sesji, w ramach której dokument został przetworzony.
2. Żądanie o UPO. Osobne wywołanie API, wskazujące numer KSeF lub numer referencyjny sesji, zwraca dokument UPO — zwykle w formacie XML.
3. Archiwizacja. Pobrane UPO powinno zostać zapisane w Twoim systemie, powiązane jednoznacznie z odpowiadającą mu fakturą (np. przez numer KSeF jako klucz).

Przykładowe żądanie o UPO przez API KSeFService:

POST /api/v1/invoices/upo
Content-Type: application/json

{
  "clientId": "...",
  "login": "...",
  "password": "...",
  "api_env": "TEST",
  "sessionReference": "20251209-SO-178C9DF000-9498D48B5B-BB",
  "ksefNumber": "5771876968-20251209-0100805B192F-B3"
}

Co jeśli UPO nie jest jeszcze dostępne

Pobranie UPO nie zawsze jest możliwe natychmiast po otrzymaniu numeru KSeF — przetwarzanie po stronie systemu może wymagać chwili. Dobra integracja uwzględnia to, implementując mechanizm ponownego sprawdzenia dostępności UPO po pewnym czasie, zamiast traktować brak natychmiastowej odpowiedzi jako błąd. Warto też zaplanować cykliczne sprawdzanie faktur, dla których UPO nie zostało jeszcze pobrane, żeby żaden dokument nie „zawisł" bez kompletnego potwierdzenia — więcej o takiej automatyzacji pisaliśmy w artykule o skryptach do wysyłki wsadowej i pobierania UPO.

Co zapisać, a co pokazać użytkownikowi

• Numer KSeF — warto wyświetlać go w interfejsie użytkownika i wykorzystywać jako identyfikator referencyjny w dalszej komunikacji z kontrahentem.
• UPO — powinno trafić do archiwum dokumentów, powiązane z fakturą, najlepiej przechowywane w oryginalnym formacie XML otrzymanym z systemu, bez modyfikacji.
• Numer referencyjny sesji — warto zachować go w bazie danych nawet po pobraniu UPO, na wypadek konieczności ponownego zapytania o status lub historię wysyłki.

Podsumowanie

Numer KSeF i UPO to dwa różne elementy tego samego procesu — pierwszy identyfikuje dokument, drugi potwierdza jego prawne doręczenie. Integracja, która traktuje numer KSeF jako wystarczający dowód wysyłki, pomija krok, który faktycznie ma znaczenie prawne. Pobranie i archiwizacja UPO powinny być stałym elementem każdego procesu wysyłki faktur do KSeF.

Chcesz, żeby UPO pobierało się automatycznie po każdej wysyłce, bez dodatkowej logiki po Twojej stronie? Sprawdź dokumentację API KSeFService lub zobacz pełny przykład integracji krok po kroku.