KSeF API – dokumentacja, środowisko testowe i pierwsza integracja

Integracja z KSeF przez API to zadanie, które na pierwszy rzut oka wygląda przerażająco – xml, schematy XSD, środowiska testowe, podpisy elektroniczne. W praktyce, po przejściu przez dokumentację Ministerstwa Finansów i pierwszych testach, okazuje się, że proces jest przewidywalny i dobrze udokumentowany. Ten artykuł przeprowadzi Cię przez kluczowe kroki: od konfiguracji środowiska testowego, przez wystawienie pierwszej faktury testowej, do gotowości produkcyjnej.

Czym jest KSeF API

KSeF API to interfejs REST udostępniony przez Ministerstwo Finansów, umożliwiający:

• Wystawienie faktury ustrukturyzowanej (FA(2)) do systemu KSeF

• Pobranie faktur przychodzących

• Weryfikację statusu faktury

• Pobranie numeru KSeF przypisanego do wystawionej faktury

• Anulowanie/korektę faktury

• Zarządzanie uprawnieniami do KSeF (dla podmiotów działających w imieniu innych)

Dokumentacja API dostępna jest na stronie podatki.gov.pl w sekcji KSeF. Ministerstwo udostępnia również SDK i przykładowe integracje w kilku językach programowania. O integracji KSeF z systemem ERP piszemy w artykule Integracja KSeF z systemem ERP – jak przygotować infrastrukturę.

Środowisko testowe KSeF – od czego zacząć

Ministerstwo Finansów udostępnia dwa środowiska:

• Środowisko Demo (demo.ksef.mf.gov.pl) – do testów bez prawdziwych danych podatkowych

• Środowisko Produkcyjne (ksef.mf.gov.pl) – docelowe środowisko od momentu obowiązku

Do korzystania z API testowego potrzebujesz:

1. Numer NIP firmy (w środowisku demo można używać fikcyjnych NIP z listy testów MF)

2. Certyfikat kwalifikowany lub profil zaufany (ePUAP) do autoryzacji

3. Token sesji – generowany przez API na podstawie uwierzytelnienia

Przepływ autoryzacji w KSeF API

` AUTORYZACJA PRZEZ CERTYFIKAT KWALIFIKOWANY:

1. Wygeneruj zapytanie autoryzacyjne (InitSessionRequest)

   • Zawiera: NIP, timestamp, identyfikator sesji
   • Dane są podpisywane certyfikatem kwalifikowanym (XAdES)

2. Wyślij POST /api/online/Session/AuthorisedWithCertificate

   • Body: podpisany XML

3. Odpowiedź zawiera ReferenceNumber (token sesji)

   • Token ważny przez 1 godzinę
   • Należy odświażać przed wygaśnięciem

4. Dalsze zapytania API:

   • Header: SessionToken: {token}
   • Można wykonywać operacje na fakturach `

Format faktury – XML FA(2)

Faktura w KSeF musi być wystawiona w formacie XML zgodnym ze schematem FA(2). To ustrukturyzowany format definiowany przez XSD (XML Schema Definition) publikowany przez Ministerstwo Finansów.

Uproszczona struktura faktury FA(2):

`

FA 2 2026-03-22T10:00:00 1234567890 Nazwa firmy sp. z o.o. 0987654321 Nabywca Sp. z o.o. PLN 2026-03-22 FV/2026/001 VAT 1 Usługa IT szt 1 1000.00 1000.00 23 1230.00 `

Uwaga: powyższy przykład to uproszczenie. Pełny schemat zawiera dziesiątki dodatkowych pól. Zawsze waliduj XML względem aktualnego XSD przed wysyłką.

Wysyłanie faktury do KSeF – przykład

` POST /api/online/Invoice/Send Headers: SessionToken: {token_sesji} Content-Type: application/octet-stream

Body: {skompresowany i zakodowany Base64 XML faktury}

Odpowiedź sukcesu (202 Accepted): { “referenceNumber”: “20260322-XX-XXXXXXXXXXX”, “processingCode”: 202, “processingDescription”: “Przetwarzanie…” } `

Wysłanie faktury to operacja asynchroniczna – API przyjmuje fakturę i zwraca referenceNumber. Następnie należy sprawdzać status:

` GET /api/online/Invoice/Status/{referenceNumber}

Odpowiedź gdy faktura przetworzona: { “processingCode”: 200, “referenceNumber”: “20260322-XX-XXXXXXXXXXX”, “ksefReferenceNumber”: “1234567890-20260322-XXXXXX-XX”, “elementReferenceNumber”: ”…” } `

ksefReferenceNumber to unikalny numer KSeF przypisany do faktury – musi być przechowywany i umieszczany na wydruku faktury.

Typowe błędy i jak je obsługiwać

• 400 Bad Request – nieprawidłowy XML (błąd walidacji schematu). Sprawdz komunikat błędu – zwykle wskazuje konkretne pole

• 401 Unauthorized – wygasły lub nieprawidłowy token sesji. Odśwież token

• 409 Conflict – duplikat faktury (ten sam NrFa). KSeF odrzuca duplikaty

• 503 Service Unavailable – KSeF w trybie offline (planowe przerwy techniczne). Ustaw retry z backoff

O obsłudze RPA do automatyzacji komunikacji z KSeF API piszemy w artykule RPA (Robotic Process Automation) – co to jest i czy warto wdrożyć. A o zastosowaniach LLM do przetwarzania danych z API – w artykule Large Language Models w procesach biznesowych – jak wykorzystać LLM-y w firmie.

Tryb offline KSeF – co to oznacza dla integracji

KSeF przewiduje tryb offline – okresy, gdy system nie jest dostępny (np. planowe przerwy). W trybie offline faktury mogą być wystawiane lokalnie (bez numeru KSeF), a następnie przesyłane do KSeF w określonym czasie po przywróceniu dostępności (typowo 1 dzień roboczy). Twoja integracja musi obsługiwać ten scenariusz – kolejkowanie faktur i automatyczne przesyłanie po powrocie systemu.

Checklista gotowości integracji KSeF

• ☑ Testy w środowisku demo – minimum 50 różnych przypadków faktur

• ☑ Obsługa tokenów sesji (odświeżanie, błędy 401)

• ☑ Walidacja XML przed wysyłką (lokalnie, nie tylko po odpowiedzi API)

• ☑ Obsługa asynchroniczna – polling statusu z timeout

• ☑ Zapis numeru KSeF w systemie ERP

• ☑ Kolejkowanie przy trybie offline

• ☑ Alerty przy błędach systemu

• ☑ Logi pełnej komunikacji z API (do celów audytowych)

Pełna checklista wdrożenia KSeF – w artykule Checklista wdrożenia KSeF – 10 kroków do gotowości. O korektach faktur przez API – w artykule Faktury korygujące w KSeF – zasady, terminy i pułapki.

Podsumowanie

KSeF API jest dobrze udokumentowane i dostępne – ale wymaga solidnego przygotowania. Kluczowe elementy: prawidłowy format XML FA(2), obsługa sesji, asynchroniczne przetwarzanie i przygotowanie na tryb offline. Zacznij od środowiska testowego i nie przenosić na produkcję bez przetestowania wszystkich edge caseów – błędy przy obowiązkowym KSeF to ryzyko kar i problemów operacyjnych.