Walidacja i przetwarzanie XML w KSeF – jak platforma interpretuje fakturę

Wprowadzenie

W systemie Krajowy System e-Faktur faktura nie jest dokumentem wizualnym (np. PDF), lecz ustrukturyzowanym dokumentem XML, który musi być zgodny z oficjalną schemą publikowaną przez Ministerstwo Finansów.

Repozytorium CIRFMF/ksef-docs zawiera dokumentację techniczną API oraz procesów integracyjnych KSeF 2.0 i jest głównym źródłem wiedzy dla integratorów systemów ERP i aplikacji fakturowych.

W momencie przesłania dokumentu XML do KSeF rozpoczyna się wielostopniowy proces walidacji oraz parsowania dokumentu, który decyduje o tym, czy faktura zostanie przyjęta do systemu.

Architektura przetwarzania faktury XML w KSeF

Proces przetwarzania faktury można podzielić na kilka głównych etapów: przesłanie dokumentu do API KSeF, walidacja techniczna dokumentu XML, walidacja biznesowa danych, identyfikacja duplikatów, zapis faktury w systemie i nadanie numeru KSeF.

Każdy z tych etapów odpowiada za sprawdzenie innego rodzaju wymagań.

1. Walidacja techniczna XML (XSD)

Pierwszym etapem jest walidacja struktury XML względem schemy XSD. Faktura musi być zapisana w formacie XML, kodowana w UTF-8 i zgodna z aktualnym schematem faktury FA(3).

Schemat XSD definiuje m.in.: strukturę dokumentu, dozwolone elementy i atrybuty, typy danych (np. data, kwota, identyfikator), pola wymagane i opcjonalne oraz ograniczenia wartości.

Przykładowe błędy wykrywane na tym etapie: brak wymaganych pól (np. numeru faktury P_2), nieprawidłowy format daty, niezgodność z przestrzenią nazw XML, nieprawidłowy typ danych.

Jeśli XML nie spełnia schemy XSD, dokument zostaje odrzucony jeszcze przed analizą biznesową.

2. Parsowanie dokumentu XML

Po przejściu walidacji strukturalnej system KSeF rozpoczyna parsowanie dokumentu. Parsowanie polega na odczytaniu struktury XML, zamianie elementów XML na wewnętrzne modele danych systemu oraz weryfikacji relacji między elementami.

W tym procesie elementy XML, takie jak Podmiot1 (sprzedawca), Podmiot2 (nabywca), Fa (dane nagłówka faktury) oraz FaWiersz (pozycja faktury), są mapowane na obiekty w systemie KSeF.

Na tym etapie system buduje model faktury w bazie danych KSeF.

3. Walidacja biznesowa dokumentu

Po zbudowaniu modelu danych następuje walidacja biznesowa. Sprawdzane są m.in.: poprawność dat, relacje między polami, spójność sum netto i VAT oraz zgodność identyfikatorów podatkowych.

Przykładowa reguła: data wystawienia faktury nie może być późniejsza niż moment przyjęcia dokumentu do KSeF.

Na tym etapie wykrywane są również problemy takie jak: niespójne wartości w podsumowaniu faktury, brak wymaganych danych podatkowych oraz błędne identyfikatory podmiotów.

4. Weryfikacja duplikatów

KSeF przeprowadza także kontrolę unikalności faktury. System sprawdza kombinację: NIP sprzedawcy, rodzaj faktury oraz numer faktury.

Jeśli w systemie istnieje już faktura z takim zestawem danych, dokument zostaje odrzucony jako duplikat. Okres sprawdzania duplikatów obejmuje do 10 lat wstecz.

5. Kontrola techniczna i limity systemowe

Przed zapisaniem faktury sprawdzane są także limity techniczne. Przykładowe ograniczenia: maksymalny rozmiar XML to około 1 MB, do 3 MB dla dokumentów z załącznikami, przesyłanie wsadowe w paczkach ZIP do 100 MB.

Kontrola ta ma na celu zapewnienie stabilności infrastruktury systemu.

6. Szyfrowanie i bezpieczeństwo

Po przesłaniu dokumentu jego treść jest chroniona kryptograficznie. Wykorzystywane są m.in. szyfrowanie AES-256-CBC dla danych faktury oraz RSAES-OAEP dla klucza szyfrującego.

Dodatkowo walidowany jest podpis elektroniczny dokumentu. Warto zauważyć, że walidacja struktury XML (XSD) i walidacja podpisu kryptograficznego to dwa niezależne procesy.

7. Nadanie numeru KSeF

Jeżeli dokument przejdzie wszystkie etapy weryfikacji: faktura zostaje zapisana w systemie, system nadaje jej unikalny identyfikator KSeF, a dokument staje się oficjalnie wystawioną fakturą.

Dopiero od tego momentu dokument uznawany jest za wystawiony w sensie prawnym.

Sprawdź swój XML przed wysłaniem — darmowy walidator

Zanim wyślesz fakturę do KSeF, warto upewnić się, że plik XML jest poprawny. Udostępniamy darmowy walidator XML KSeF, który pozwala sprawdzić zgodność dokumentu ze schemą XSD, poprawność struktury, NIP-ów, dat i kwot — bez rejestracji i bez przesyłania danych na zewnętrzne serwery.

Wypróbuj nasz darmowy walidator XML i wyeliminuj błędy zanim trafią do systemu KSeF.

Podsumowanie

Walidacja faktury XML w KSeF to proces wieloetapowy, który obejmuje zarówno kontrolę techniczną, jak i biznesową.

Najważniejsze elementy procesu: walidacja struktury XML względem schemy XSD, parsowanie dokumentu i mapowanie danych, walidacja reguł biznesowych, kontrola duplikatów, sprawdzenie limitów technicznych, weryfikacja bezpieczeństwa i podpisu oraz zapis faktury i nadanie numeru KSeF.

Takie podejście pozwala zapewnić, że każda faktura przechowywana w systemie KSeF jest spójna, poprawna strukturalnie i zgodna z przepisami podatkowymi.