Interfejs KSeF API to oficjalny kanał komunikacji programistycznej REST API, za pomocą którego systemy finansowo-księgowe oraz systemy ERP łączą się bezpośrednio z centralnymi serwerami Ministerstwa Finansów. Integracja techniczna opiera się na architekturze klient-serwer i wymianie ustrukturyzowanych komunikatów w formacie JSON oraz XML. Zrozumienie oficjalnej dokumentacji oraz logicznej struktury przesyłu danych jest kluczem do zaprojektowania stabilnego i wydajnego środowiska IT, które automatyzuje proces fakturowania w firmie bez ryzyka utraty spójności danych.
Architektura API KSeF – jak przygotować system do komunikacji?
Architektura Krajowego Systemu e-Faktur została zaprojektowana w modelu bezstanowym, co oznacza, że każde zapytanie kierowane do serwerów rządowych musi zawierać pełen komplet informacji niezbędnych do jego poprawnego przetworzenia. Komunikacja odbywa się za pomocą standardowych metod protokołu HTTPS, a odpowiedzi serwera zwracane są w formacie JSON.
W procesie projektowania architektury przepływu dokumentów należy uwzględnić asynchroniczność systemu. Interfejs API KSeF nie przetwarza przesyłanych paczek faktur w czasie rzeczywistym. Przyjęcie dokumentów przez bramkę rządową odbywa się dwuetapowo:
- Etap 1 (Wstępna walidacja): System weryfikuje poprawność połączenia, strukturę pliku i zwraca unikalny numer referencyjny sesji (Session ID).
- Etap 2 (Przetwarzanie procesowe): Po przejściu kolejki przetwarzania, KSeF nadaje fakturze oficjalny, 35-znakowy identyfikator i generuje Urzędowe Poświadczenie Odbioru (UPO), które system ERP musi samodzielnie pobrać w ramach osobnego zapytania.
Dokumentacja KSeF dla deweloperów – od czego zacząć integrację?
Punktem wyjścia do analizy technicznej jest oficjalna dokumentacja KSeF udostępniana przez Ministerstwo Finansów, która precyzuje specyfikację OpenAPI (plik YAML) oraz udostępnia dedykowane środowiska testowe.
Dla zapewnienia bezpiecznego procesu wdrożenia, infrastruktura sieciowa KSeF została podzielona na trzy niezależne środowiska:
- Środowisko testowe (Sandbox): Służy do przeprowadzania symulacji wysyłki, testowania odpowiedzi bramki i walidacji błędów bez wywoływania skutków prawno-podatkowych.
- Środowisko przedprodukcyjne (Demo): Odzwierciedla pełną wydajność systemu i pozwala na testowanie stabilności połączeń na rzeczywistych bazach danych. Szczegółowe instrukcje dotyczące tego etapu znajdziesz w poradniku: Środowisko przedprodukcyjne demo API KSeF 2.0.
- Środowisko produkcyjne: Oficjalna platforma rządowa, na której rejestrowane są prawnie wiążące dokumenty księgowe firm.
Oficjalna dokumentacja techniczna precyzuje nie tylko strukturę samych endpointów, ale również sztywne limity przepustowości (Rate Limiting). Systemy IT w firmach muszą być przygotowane na obsługę limitów zapytań w godzinach szczytu sprzedażowego, aby nie doprowadzić do blokowania kolejki wysyłkowej.
Przykłady plików XML (FA_VAT) i walidacja schematyczna e-faktury
Każda e-faktura przesyłana przez API musi mieć strukturę pliku XML zgodną z aktualną wersją wzoru dokumentu elektronicznego. Obecnie obowiązującą i nadrzędną strukturą logiczną jest schemat FA(3).
Walidacja dokumentu przez API KSeF odbywa się na poziomie czysto technicznym i schematycznym. Serwery Ministerstwa Finansów sprawdzają zgodność pliku z plikiem schemy XSD. Oznacza to, że system weryfikuje obecność pól obowiązkowych (takich jak numery NIP stron transakcji, daty, kwoty czy oznaczenia walut) oraz poprawność formatów danych. API KSeF nie bada natomiast poprawności merytorycznej faktury – jeśli w pliku XML zostaną wpisane błędne stawki podatkowe lub pomylone kwoty, ale struktura pliku będzie poprawna, system nada fakturze unikalny numer i wprowadzi ją do obiegu prawnego.
Autoryzacja w API – tokeny sesyjne i klucze dostępu
Bezpieczeństwo wymiany danych w API KSeF opiera się na restrykcyjnych mechanizmach uwierzytelniania. Każda sesja interaktywna lub nieinteraktywna wymaga przejścia procedury autoryzacji przed wykonaniem jakiejkolwiek operacji na dokumentach.
Głównym narzędziem autoryzacji w codziennej pracy systemów ERP są autoryzacyjne tokeny KSeF. Są to unikalne ciągi znaków generowane z poziomu rządowej Aplikacji Podatnika przez osobę posiadającą najwyższe uprawnienia w firmie (np. podpis kwalifikowany lub profil zaufany). Token ten przypisywany jest do konkretnego podmiotu i może posiadać ściśle zdefiniowany zakres uprawnień (np. wyłącznie do zapisu faktur, wyłącznie do odczytu lub uprawnienia pełne). Podczas inicjalizacji sesji przez API, token jest wykorzystywany do wygenerowania tymczasowego tokena sesyjnego, który zabezpiecza i autoryzuje każde kolejne zapytanie HTTPS w ramach danego połączenia.
Techniczna integracja systemów informatycznych z API KSeF to zaawansowany proces, który wymaga odpowiedniej wiedzy i umiejętności.
Zamiast ryzykować błędy, warto powierzyć to zadanie specjalistom. Sprawdź nasz proces wdrożenia na stronie Wdrożenie KSeF IT. Przeprowadzimy pełen audyt Twojej obecnej infrastruktury IT i zaprojektujemy bezpieczny pomost technologiczny z API Ministerstwa Finansów.