KSeF API sesja wsadowa – format żądania PUT

Format żądania PUT dla sesji wsadowej

Po otwarciu sesji wsadowej (POST /api/v2/sessions/batch) otrzymujesz listę partUploadRequests zawierającą dynamiczne URL-e, metody HTTP (PUT) i nagłówki wymagane do przesłania każdej części paczki.

Każda część paczki musi być przesłana osobno do wskazanego URL-a metodą PUT. Po udanym przesłaniu (status 201 Created lub 200 OK) przechodzisz do kolejnej części, aż wszystkie części zostaną przesłane.

Dynamiczne endpointy mogą się różnić w zależności od konfiguracji systemu. Przykłady implementacji można znaleźć w oficjalnych bibliotekach C# i Java (metoda SendBatchParts).

Instrukcja krok po kroku

1. Otwórz sesję wsadową

Wywołaj POST /api/v2/sessions/batch z parametrami sesji (formCode, encryptionKey, fileParts). W odpowiedzi otrzymasz listę partUploadRequests zawierającą dynamiczne URL-e, metody i nagłówki dla każdej części paczki.

2. Przygotuj część paczki

Przygotuj zaszyfrowaną część paczki zgodnie z informacjami w fileParts. Każda część musi być nie większa niż 100 MB (przed zaszyfrowaniem) i zaszyfrowana algorytmem AES-256-CBC.

3. Prześlij część metodą PUT

Wyślij część paczki metodą PUT do URL-a wskazanego w partUploadRequests. Użyj nagłówków zwróconych w partUploadRequests (mogą zawierać autoryzację, content-type, itp.). W odpowiedzi otrzymasz status 201 Created lub 200 OK przy pomyślnym przesłaniu.

4. Prześlij kolejne części

Powtórz proces dla wszystkich części paczki wskazanych w partUploadRequests. Przesyłaj części sekwencyjnie, jedna po drugiej, aż wszystkie części zostaną przesłane.

5. Zamknij sesję

Po przesłaniu wszystkich części zamknij sesję wsadową wywołując POST /api/v2/sessions/batch/{referenceNumber}/close. Sprawdź status sesji i pobierz zbiorcze UPO (Urzędowe Poświadczenie Odbioru).

Najczęstsze problemy i rozwiązania

Nie wiem, jak sformatować żądanie PUT

Format żądania PUT zależy od konfiguracji zwróconej w partUploadRequests przy otwarciu sesji. URL, metoda (PUT) i nagłówki są zwracane dynamicznie. Sprawdź przykłady w oficjalnych bibliotekach C# i Java (metoda SendBatchParts) lub dokumentacji API. Ciało żądania to zaszyfrowana część paczki.

Błąd przy przesyłaniu części paczki

Sprawdź, czy używasz właściwego URL-a z partUploadRequests, czy nagłówki są poprawne (mogą zawierać autoryzację, content-type), czy część paczki jest poprawnie zaszyfrowana i czy rozmiar nie przekracza 100 MB (przed zaszyfrowaniem). Zweryfikuj, czy przesyłasz części w odpowiedniej kolejności.

Różne formaty odpowiedzi

Dynamiczne endpointy mogą zwracać różne formaty odpowiedzi w zależności od konfiguracji. Po udanym przesłaniu możesz otrzymać status 201 Created lub 200 OK. Sprawdź odpowiedź, aby upewnić się, że część została poprawnie przesłana, zanim przejdziesz do kolejnej.

Jak sprawdzić, które części zostały przesłane?

Sprawdź status sesji wsadowej używając GET /api/v2/sessions/batch/{referenceNumber}. Status zawiera informacje o przesłanych częściach i ich statusach. Możesz również sprawdzić faktury w sesji używając GET /api/v2/sessions/batch/{referenceNumber}/invoices.

Dynamiczne endpointy w sesji wsadowej

Po otwarciu sesji wsadowej (POST /api/v2/sessions/batch) otrzymujesz listę partUploadRequests zawierającą dla każdej części paczki: URL (dynamiczny endpoint), metodę HTTP (PUT) oraz nagłówki wymagane do przesłania. Endpointy są generowane dynamicznie i mogą się różnić w zależności od konfiguracji systemu. Każda część musi być przesłana osobno do wskazanego URL-a.

Format żądania PUT

Żądanie PUT składa się z: URL-a z partUploadRequests, metody PUT, nagłówków zwróconych w partUploadRequests (mogą zawierać autoryzację, content-type, itp.) oraz ciała żądania zawierającego zaszyfrowaną część paczki. Po udanym przesłaniu otrzymasz status 201 Created lub 200 OK. Format może się różnić w zależności od konfiguracji, więc sprawdź odpowiedź przed przejściem do kolejnej części.

Przesyłanie części paczki

Paczka ZIP z fakturami musi być podzielona na części nie większe niż 100 MB (przed zaszyfrowaniem). Każda część jest szyfrowana algorytmem AES-256-CBC i przesyłana osobno metodą PUT do wskazanego URL-a. Części przesyłane są sekwencyjnie, jedna po drugiej, aż wszystkie części zostaną przesłane. Po przesłaniu wszystkich części sesja jest zamykana i pobierane jest zbiorcze UPO.

Przykłady implementacji

Oficjalne biblioteki C# i Java zawierają przykłady implementacji przesyłania części paczki (metoda SendBatchParts). Przykłady pokazują, jak używać dynamicznych endpointów, nagłówków i formatu żądania PUT. Dokumentacja API zawiera również szczegóły dotyczące formatu i wymagań.

FAQ

Powiązane tematy

• KSeF API 2.0 – dokumentacja i integracja
• KSeF API wysyłanie faktur
• KSeF API sesja odzyskiwanie danych