KSeF API lista sesji – pobieranie metadanych

Listowanie sesji w KSeF API 2.0

Endpoint GET /sessions pozwala na pobranie listy sesji w KSeF API 2.0. Wymaganym parametrem jest sessionType (Online lub Batch) - jedno zapytanie zwraca sesje jednego typu. Lista zawiera numery referencyjne sesji, daty utworzenia, statusy i inne metadane.

Endpoint umożliwia odzyskanie informacji o sesjach po awarii systemu lub synchronizację danych z KSeF. Znając numer referencyjny sesji, możesz pobrać jej szczegóły oraz listę faktur wysłanych w danej sesji - tym samym endpointem GET /sessions/{referenceNumber} niezależnie od typu sesji.

Lista sesji jest przydatna do zarządzania wysyłkami, monitorowania statusu faktur, odzyskiwania danych po awarii oraz synchronizacji stanu między lokalnym systemem a KSeF.

Instrukcja krok po kroku

1. Wywołaj endpoint listy sesji

Wywołaj GET /sessions z wymaganym parametrem sessionType (Online lub Batch) oraz opcjonalnymi parametrami zakresu dat: dateCreatedFrom, dateCreatedTo (data utworzenia), dateClosedFrom, dateClosedTo (data zamknięcia) lub dateModifiedFrom, dateModifiedTo (data ostatniej aktywności). Endpoint wymaga autoryzacji accessToken w nagłówku Authorization: Bearer.

2. Przetwórz listę sesji

Otrzymasz listę sesji danego typu zawierającą dla każdej sesji: numer referencyjny (referenceNumber), datę utworzenia, status oraz metadane. Duże wyniki są stronicowane (parametr pageSize oraz nagłówek x-continuation-token do pobrania kolejnej strony). Przetwórz listę, aby zidentyfikować sesje, które Cię interesują.

3. Pobierz szczegóły sesji

Dla każdej sesji z listy możesz pobrać szczegóły używając GET /sessions/{referenceNumber} - ten sam endpoint obsługuje zarówno sesje interaktywne, jak i wsadowe. Szczegóły zawierają metadane sesji, status i informacje o fakturach.

4. Pobierz faktury z sesji

Używając numeru referencyjnego sesji, możesz pobrać listę faktur wysłanych w danej sesji: GET /sessions/{referenceNumber}/invoices (ten sam endpoint dla obu typów sesji) lub GET /sessions/{referenceNumber}/invoices/failed dla faktur przetworzonych niepoprawnie.

Najczęstsze problemy i rozwiązania

Jak filtrować sesje według typu?

Parametr sessionType (Online lub Batch) jest wymagany w zapytaniu GET /sessions - jedno wywołanie zwraca sesje tylko jednego typu. Aby pobrać oba typy, trzeba wykonać dwa oddzielne zapytania (raz z sessionType=Online, raz z sessionType=Batch).

Jak pobrać sesje z dłuższego okresu?

Użyj parametrów zapytania dateCreatedFrom i dateCreatedTo (lub dateClosedFrom/dateClosedTo, dateModifiedFrom/dateModifiedTo), aby określić zakres dat. Wyniki są stronicowane parametrem pageSize (10-1000) - kolejne strony pobiera się nagłówkiem x-continuation-token zwróconym w poprzedniej odpowiedzi.

Różnice między sesjami interaktywnymi a wsadowymi

Sesje interaktywne (Online) są używane do wysyłki pojedynczych faktur w czasie rzeczywistym. Sesje wsadowe (Batch) są używane do wysyłki wielu faktur w paczkach. Typ sesji wskazuje się parametrem sessionType w zapytaniu GET /sessions. Do pobierania szczegółów obu typów służy ten sam endpoint: GET /sessions/{referenceNumber}.

Jak sprawdzić status faktur w sesji?

Pobierz listę faktur z sesji używając GET /sessions/{referenceNumber}/invoices (wspólny endpoint dla obu typów sesji) lub GET /sessions/{referenceNumber}/invoices/failed dla faktur przetworzonych niepoprawnie. Lista zawiera statusy faktur, numery KSeF i metadane. Możesz również sprawdzić szczegóły pojedynczej faktury endpointem GET /sessions/{referenceNumber}/invoices/{invoiceReferenceNumber}.

Endpoint GET /sessions

Endpoint zwraca listę sesji jednego typu w określonym zakresie dat. Wymaga parametru sessionType (Online lub Batch) oraz opcjonalnie parametrów zakresu dat: dateCreatedFrom/dateCreatedTo, dateClosedFrom/dateClosedTo, dateModifiedFrom/dateModifiedTo, a także referenceNumber i statuses do zawężenia wyników. Endpoint wymaga autoryzacji accessToken w nagłówku Authorization: Bearer. Lista zawiera dla każdej sesji: numer referencyjny, datę utworzenia, status i metadane.

Format odpowiedzi

Odpowiedź zawiera listę sesji z metadanymi: referenceNumber (numer referencyjny sesji), data utworzenia, status sesji (InProgress, Succeeded, Failed, Cancelled) oraz opcjonalnie inne metadane (liczba faktur, data zamknięcia, itp.). Wyniki są stronicowane - rozmiar strony ustawia parametr pageSize (10-1000), a kolejną stronę pobiera się przekazując nagłówek x-continuation-token zwrócony w poprzedniej odpowiedzi.

Pobieranie szczegółów sesji

Znając numer referencyjny sesji z listy, możesz pobrać jej szczegóły: GET /sessions/{referenceNumber} - ten sam endpoint obsługuje zarówno sesje interaktywne, jak i wsadowe. Szczegóły zawierają pełne metadane sesji, status, informacje o fakturach i UPO.

Zastosowania listy sesji

Lista sesji jest przydatna do: odzyskiwania danych po awarii systemu (identyfikacja sesji, które zostały utracone), synchronizacji stanu między lokalnym systemem a KSeF, monitorowania statusu wysyłek faktur, zarządzania sesjami i analizy historii wysyłek. Endpoint umożliwia kompleksowe zarządzanie sesjami i fakturach w systemie KSeF.

FAQ

Powiązane tematy

• KSeF API sesja odzyskiwanie danych
• KSeF API sesja wsadowa upload
• KSeF API pobieranie faktur