Jak działa walidacja techniczna faktury w KSeF

Czym jest walidacja techniczna w KSeF

Walidacja techniczna to automatyczny proces sprawdzania faktury przez Krajowy System e-Faktur (KSeF) przed jej przyjęciem do systemu.

Proces ten obejmuje kilka warstw kontroli:

• sprawdzenie poprawności składni XML,
• weryfikację zgodności dokumentu z schematem XSD (np. FA(3)),
• kontrolę reguł systemowych KSeF,
• sprawdzenie uprawnień podmiotu wysyłającego.

Walidacja techniczna dotyczy głównie warstwy technicznej i strukturalnej dokumentu.

System nie ocenia treści biznesowej faktury. Nie sprawdza m.in.:

• czy transakcja faktycznie miała miejsce,
• czy ceny są rynkowe,
• czy rachunek bankowy należy do sprzedawcy,
• czy kontrahent jest wiarygodny.

Dlatego faktura poprawna technicznie może nadal wymagać weryfikacji biznesowej.

Proces walidacji krok po kroku

Etap 1: Wysłanie faktury do KSeF

Faktura jest wysyłana do KSeF poprzez:

• API systemowe,
• integrację z systemem ERP,
• aplikacje udostępnione przez Ministerstwo Finansów.

Dokument musi być zapisany w formacie XML zgodnym ze strukturą logiczną faktury.

Etap 2: Walidacja składni XML

Pierwszym krokiem jest sprawdzenie poprawności pliku XML.

System weryfikuje m.in.:

• czy dokument jest poprawnie zbudowany (well-formed),
• czy wszystkie elementy są prawidłowo zamknięte,
• czy nie ma błędów składni.

Jeżeli XML jest niepoprawny, faktura zostaje odrzucona.

Etap 3: Walidacja względem schematu XSD

Następnie KSeF sprawdza zgodność dokumentu z schematem logicznym faktury.

Dla okresu obowiązkowego stosowany jest schemat:

FA(3)

Weryfikacja obejmuje m.in.:

• obecność wymaganych elementów,
• typy danych,
• długość pól,
• dopuszczalne wartości,
• strukturę dokumentu.

Etap 4: Reguły systemowe KSeF

Po walidacji XSD stosowane są dodatkowe reguły systemowe określone w dokumentacji MF.

Przykłady kontroli:

• spójność niektórych danych,
• poprawność identyfikatorów,
• dopuszczalne zakresy wartości,
• ograniczenia techniczne.

Reguły te są publikowane w dokumentacji integracyjnej KSeF.

Etap 5: Weryfikacja uprawnień nadawcy

KSeF sprawdza, czy podmiot wysyłający dokument:

• jest poprawnie uwierzytelniony,
• posiada uprawnienia do działania w imieniu podatnika.

Uprawnienia mogą wynikać m.in. z:

• tokena KSeF,
• podpisu kwalifikowanego,
• pieczęci kwalifikowanej,
• uprawnień nadanych w systemie KSeF.

Etap 6: Przyjęcie faktury i nadanie numeru KSeF

Jeżeli wszystkie kontrole zakończą się sukcesem:

• faktura zostaje przyjęta do systemu KSeF,
• otrzymuje numer KSeF,
• generowane jest UPO (Urzędowe Poświadczenie Odbioru).

Faktura ustrukturyzowana jest uznawana za wystawioną w momencie nadania numeru KSeF.

Schemat FA(3) – struktura techniczna

Schemat FA(3) określa strukturę faktury ustrukturyzowanej w KSeF.

Przykładowa struktura dokumentu

Poniższy przykład ma charakter poglądowy.

<Faktura>
  <Naglowek>...</Naglowek>
  <Podmiot1>...</Podmiot1>
  <Podmiot2>...</Podmiot2>
  <Fa>
    <KodWaluty>PLN</KodWaluty>
    <P_1>2026-03-11</P_1>
    <P_2>FV/01/03/2026</P_2>
    <FaWiersz>...</FaWiersz>
  </Fa>
</Faktura>

Pełna struktura schematu zawiera znacznie więcej elementów.

Przykładowe pola wymagane

Typy danych i ograniczenia

Najczęstsze ograniczenia w schemacie:

• kwoty – liczby dziesiętne (decimal),
• daty – format ISO (YYYY-MM-DD),
• NIP – dokładnie 10 cyfr,
• kody – z zamkniętych list (waluty, kraje, jednostki),
• teksty – ograniczona maksymalna długość.

Najczęstsze błędy walidacji

Błędy strukturalne XML

Niepoprawna struktura XML

Przyczyna:

• brak zamykającego tagu,
• błędne zagnieżdżenie elementów.

Rozwiązanie:

• sprawdzenie poprawności składni XML.

Niezgodność ze schematem XSD

Element niezgodny ze schematem

Przyczyna:

• brak wymaganego pola,
• zła kolejność elementów,
• niedozwolona wartość.

Rozwiązanie:

• porównanie dokumentu z aktualnym schematem FA(3).

Błędy danych

Niepoprawny format pola

Przyczyna:

• wartość nie spełnia wymagań typu lub wzorca.

Przykład:

• data w formacie DD-MM-YYYY zamiast YYYY-MM-DD.

Czy KSeF sprawdza poprawność obliczeń

Walidacja techniczna w KSeF nie zastępuje kontroli księgowej ani biznesowej faktury.

Pozytywna walidacja oznacza, że dokument:

• jest poprawny technicznie,
• spełnia wymagania struktury,
• został poprawnie wysłany do systemu.

Nie oznacza to automatycznie, że faktura jest:

• ekonomicznie poprawna,
• zgodna z rzeczywistą transakcją,
• wolna od ryzyka oszustwa.

Dlatego w praktyce stosuje się również weryfikację biznesową faktur.

Co oznacza pozytywna walidacja

Pozytywna walidacja oznacza, że:

• dokument jest poprawny technicznie,
• spełnia wymagania schematu XSD,
• został wysłany przez podmiot z uprawnieniami w KSeF.

Czego walidacja nie gwarantuje

Pozytywna walidacja nie oznacza, że:

• transakcja rzeczywiście miała miejsce,
• kontrahent jest wiarygodny,
• rachunek bankowy należy do sprzedawcy,
• faktura nie jest elementem oszustwa.

Jak interpretować komunikaty błędów

Komunikaty błędów zawierają zwykle:

• kod błędu,
• opis problemu,
• wskazanie elementu XML.

Przykład struktury komunikatu:

<Blad>
  <Kod>...</Kod>
  <Opis>Opis błędu walidacji</Opis>
  <Element>/Faktura/Podmiot1/DaneIdentyfikacyjne/NIP</Element>
</Blad>

Narzędzia do walidacji

Walidacja lokalna

Przed wysyłką można używać narzędzi takich jak:

• edytory XML z obsługą XSD (np. Oxygen, XMLSpy),
• biblioteki programistyczne (np. lxml, xmlschema w Pythonie).

Środowisko testowe KSeF

Ministerstwo Finansów udostępnia środowisko testowe:

https://ksef-test.mf.gov.pl

Służy ono do testowania integracji przed użyciem produkcyjnego KSeF.

Automatyzacja walidacji

W systemach ERP często stosuje się dodatkową walidację przed wysyłką:

def validate_invoice(xml_content):
    if not is_wellformed(xml_content):
        return "Błąd składni XML"

    schema = load_schema("FA_3.xsd")
    if not schema.validate(xml_content):
        return schema.errors

    if not check_business_rules(xml_content):
        return "Błąd reguł biznesowych"

    return "OK"

Powiązane artykuły

• Co KSeF sprawdza, a czego nie sprawdza – pełny zakres walidacji
• Walidacja techniczna vs walidacja biznesowa – porównanie procesów

FAQ

Czy faktura w KSeF musi być podpisana elektronicznie

Nie zawsze.

Dostęp do systemu może być uwierzytelniany m.in.:

• podpisem kwalifikowanym,
• pieczęcią kwalifikowaną,
• tokenem KSeF.

Kluczowe jest posiadanie odpowiednich uprawnień w systemie KSeF.

Jak długo trwa walidacja

W typowych warunkach walidacja trwa kilka sekund.

Przy dużym obciążeniu systemu czas ten może być dłuższy. Dlatego integracje z KSeF często implementują:

• mechanizmy ponawiania zapytań,
• obsługę timeoutów,
• kolejki przetwarzania.

Treść ma charakter informacyjny i edukacyjny. Nie stanowi porady prawnej ani podatkowej.