Technicznie · KSeF

API KSeF w .NET — praktyczny przewodnik dla programistów

Ostatnia aktualizacja: 2025

Integracja z Krajowym Systemem e-Faktur w C# i .NET sprowadza się do wywołań REST API udostępnianego przez Ministerstwo Finansów. Poniżej omawiamy kluczowe elementy: autentykację, strukturę żądań i odpowiedzi oraz testy w sandbox.

Środowisko: sandbox i produkcja

KSeF udostępnia środowisko testowe (sandbox) oraz produkcyjne. W sandbox możesz bez ryzyka testować wysyłkę i odbieranie e-faktur. Adresy API i wymagania (certyfikaty, tokeny) różnią się między środowiskami — zawsze sprawdzaj aktualną dokumentację MF/KAS. W kodzie warto trzymać URL bazy API oraz ścieżki w konfiguracji (np. appsettings.json), żeby łatwo przełączać środowisko.

Autentykacja

Dostęp do API KSeF wymaga autentykacji. W środowisku produkcyjnym wykorzystuje się m.in. certyfikat kwalifikowany lub profil zaufany; w sandbox — mechanizmy opisane w dokumentacji (np. token testowy). W .NET typowe podejścia to:

  • użycie HttpClient z handlerem obsługującym certyfikat kliencki (np. HttpClientHandler.ClientCertificates),
  • dodawanie tokenu Bearer lub innego nagłówka wymaganego przez KSeF do każdego żądania,
  • cache’owanie tokenu (jeśli API go zwraca) do czasu wygaśnięcia, z odświeżaniem w tle.

Szczegóły (np. endpoint tokenu, format nagłówków) znajdziesz w aktualnej specyfikacji API KSeF.

Struktura e-faktury (JSON)

E-faktura wysyłana do KSeF ma zdefiniowaną strukturę (schemat). Dokumentacja określa wymagane i opcjonalne pola: dane sprzedawcy, nabywcy, pozycje, sumy, VAT itd. W .NET wygodnie jest:

  • zdefiniować modele C# (klasy) odwzorowujące tę strukturę i serializować je do JSON (np. System.Text.Json lub Newtonsoft.Json),
  • walidować JSON przed wysłaniem (np. pod kątem wymaganych pól i formatów), żeby ograniczyć błędy zwracane przez KSeF.

Przykładowe wywołanie wysyłki (pseudokod): przygotowanie obiektu faktury → serializacja do JSON → POST na endpoint KSeF z odpowiednimi nagłówkami i ciałem żądania.

Obsługa błędów i statusów

API KSeF zwraca kody HTTP i często body z opisem błędu (np. walidacja, duplikat, problem z certyfikatem). Warto:

  • sprawdzać response.IsSuccessStatusCode i w razie błędu czytać treść odpowiedzi,
  • logować żądania i odpowiedzi (w wersji okrojonej o dane osobowe/sensytywne) do diagnozowania problemów,
  • implementować retry z backoff przy błędach tymczasowych (np. 503), zgodnie z dobrymi praktykami dla API.

Testy w sandbox

Zanim uruchomisz integrację na produkcji, wykonaj w sandbox m.in.:

  • wysłanie poprawnej e-faktury i sprawdzenie zwróconego identyfikatora/statusu,
  • wysłanie dokumentu z błędem (np. brak wymaganego pola) i sprawdzenie komunikatu błędu,
  • odbieranie listy faktur lub pojedynczego dokumentu (jeśli Twój zakres to także odbiór),
  • test z użyciem certyfikatu/testowego konta tak, jak będzie w produkcji.

Dzięki temu w .NET uzyskasz stabilną warstwę komunikacji z KSeF i będziesz mógł skupić się na mapowaniu danych z ERP i obsłudze biznesowej.