Integracja z API KSeF krok po kroku — przewodnik techniczny

Architektura API KSeF

API KSeF v2 jest oparte o REST i dostępne pod adresem api.ksef.mf.gov.pl/api/v2. Wymaga autoryzacji tokenem sesyjnym uzyskanym poprzez proces challenge-response.

Krok 1: Autoryzacja

Proces autoryzacji składa się z 5 kroków: (1) pobranie challenge, (2) szyfrowanie tokenu, (3) podpisanie żądania, (4) wysłanie InitSession, (5) odbiór SessionToken.

Krok 2: Wysyłka faktury

Po uzyskaniu tokenu sesji, faktura w formacie XML jest szyfrowana kluczem RSA-OAEP SHA-256 i wysyłana do endpointu /online/Invoice/Send.

Krok 3: Pobranie statusu i UPO

Po wysyłce, system zwraca numer referencyjny. Polling endpointu /common/Status/{ReferenceNumber} pozwala monitorować status i pobrać UPO po pomyślnym przetworzeniu.

Obsługa błędów

API KSeF może zwrócić różne kody błędów. Najważniejsze to: walidacja schematu XML, błędy autoryzacji, błędy szyfrowania i limity rate-limiting.