Jak działa walidacja techniczna faktury w KSeF

Czym jest walidacja techniczna w KSeF

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

Proces ten obejmuje kilka warstw kontroli:

• sprawdzenie poprawności budowy pliku XML,
• weryfikację zgodności dokumentu ze schematem XSD (aktualnie FA(3)),
• kontrolę reguł systemowych KSeF,
• sprawdzenie uprawnień podmiotu wysyłającego.

Walidacja techniczna dotyczy głównie budowy i struktury dokumentu.

System nie ocenia treści biznesowej faktury ani nie wykonuje obliczeń matematycznych. Nie sprawdza m.in.:

• czy transakcja faktycznie miała miejsce,
• czy kwoty na fakturze są prawidłowo wyliczone (np. czy VAT zgadza się z kwotą netto),
• czy ceny są rynkowe,
• czy numer rachunku bankowego 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 przez:

• interfejs programistyczny (API) zintegrowany z systemem finansowo-księgowym (ERP),
• bezpłatną Aplikację Podatnika udostępnioną przez Ministerstwo Finansów.

Dokument musi być przygotowany w formacie XML zgodnym ze strukturą logiczną faktury obowiązującą w KSeF.

Etap 2: Sprawdzenie budowy pliku XML

Pierwszym krokiem jest kontrola poprawności pliku XML.

System weryfikuje m.in.:

• czy dokument jest poprawnie zbudowany (wszystkie elementy otwarte i zamknięte),
• czy nie ma błędów składni.

Jeżeli plik XML jest niepoprawny, faktura zostaje odrzucona.

Etap 3: Zgodność ze schematem XSD

Następnie KSeF sprawdza zgodność dokumentu z obowiązującym schematem logicznym faktury.

Od 1 lutego 2026 r. obowiązuje wyłącznie 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 weryfikacji schematu stosowane są dodatkowe reguły systemowe określone w dokumentacji Ministerstwa Finansów.

Przykłady kontroli:

• spójność niektórych danych,
• dopuszczalne zakresy wartości,
• zakaz przesłania faktury z datą wystawienia wskazującą na przyszłość,
• ograniczenia techniczne (np. rozmiar pliku).

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,
• certyfikatu KSeF,
• uprawnień nadanych w Module Certyfikatów i Uprawnień (MCU).

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 jej przesłania i zarejestrowania w KSeF (w trybie online jest to data przesłania pliku, jeśli jest zgodna z datą wskazaną na fakturze).

Schemat FA(3) – struktura techniczna

Schemat FA(3) określa strukturę faktury ustrukturyzowanej w KSeF i obowiązuje od 1 lutego 2026 r.

Przykładowa struktura dokumentu

Poniższy przykład ma charakter poglądowy i pokazuje tylko wybrane elementy struktury – rzeczywisty schemat jest znacznie bardziej rozbudowany.

<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>

Uwaga: wszystkie dane w powyższym przykładzie są fikcyjne i służą wyłącznie celom ilustracyjnym.

Przykładowe pola wymagane

Typy danych i ograniczenia

Najczęstsze ograniczenia w schemacie:

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

Najczęstsze błędy walidacji

Błędy budowy pliku XML

Niepoprawna struktura pliku

Przyczyna:

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

Rozwiązanie:

• sprawdzenie poprawności budowy pliku XML przed wysyłką (np. w edytorze XML lub narzędziu walidacyjnym).

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), dostępnym na stronie ksef.podatki.gov.pl.

Błędy danych

Niepoprawny format pola

Przyczyna:

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

Przykład:

• data wpisana jako DD-MM-YYYY zamiast wymaganego formatu YYYY-MM-DD.

Czy KSeF sprawdza poprawność obliczeń

Nie. KSeF nie wykonuje obliczeń matematycznych i nie odrzuci faktury z błędami rachunkowymi. Oznacza to, że faktura z nieprawidłowo wyliczoną kwotą VAT w stosunku do kwoty netto przejdzie walidację techniczną. Tego rodzaju weryfikacja leży po stronie oprogramowania do wystawiania faktur lub samego wystawcy.

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

Pozytywna walidacja oznacza, że dokument:

• jest poprawnie zbudowany technicznie,
• spełnia wymagania struktury FA(3),
• został poprawnie przesłany do systemu przez uprawniony podmiot.

Nie oznacza to automatycznie, że faktura jest:

• wolna od błędów rachunkowych,
• 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 i strukturalnie,
• spełnia wymagania schematu XSD (FA(3)),
• został przesłany przez podmiot posiadający uprawnienia w KSeF.

Czego walidacja nie gwarantuje

Pozytywna walidacja nie oznacza, że:

• transakcja rzeczywiście miała miejsce,
• kwoty na fakturze są poprawnie wyliczone,
• kontrahent jest wiarygodny,
• numer rachunku bankowego 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, którego dotyczy błąd.

Przykład struktury komunikatu (poglądowy):

<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ą schematów XSD (np. Oxygen XML Editor, XMLSpy),
• biblioteki programistyczne (np. lxml, xmlschema w języku Python).

Schematy XSD do pobrania są dostępne na stronie ksef.podatki.gov.pl w sekcji „Wsparcie dla integratorów".

Środowiska KSeF udostępnione przez Ministerstwo Finansów

Ministerstwo Finansów udostępnia kilka środowisk do testowania:

• środowisko testowe – przeznaczone głównie dla integratorów i programistów sprawdzających komunikację z API; faktury wysłane tu nie mają skutków podatkowych,
• środowisko przedprodukcyjne (Demo) – przeznaczone dla firm i biur rachunkowych do ćwiczenia wystawiania i odbierania faktur w warunkach zbliżonych do produkcyjnych; dane są fikcyjne, brak skutków podatkowych.

Dostęp do obu środowisk oraz do Aplikacji Podatnika KSeF znajdziesz na stronie ksef.podatki.gov.pl.

Adresy środowisk technicznych (API) są publikowane przez Ministerstwo Finansów w sekcji „Wsparcie dla integratorów" i mogą się zmieniać – zawsze korzystaj z aktualnych adresów podanych na oficjalnej stronie.

Automatyzacja walidacji w systemach finansowo-księgowych

W systemach finansowo-księgowych (ERP) często stosuje się dodatkową walidację przed wysyłką do KSeF. Poniższy przykład ma charakter poglądowy i ilustruje ogólną logikę takiego procesu:

def validate_invoice(xml_content):
    if not is_wellformed(xml_content):
        return "Błąd budowy pliku 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

• Jak zwalidować fakturę KSeF przed wysłaniem – walidacja praktyczna przed wysłaniem
• Co KSeF sprawdza, a czego nie sprawdza – pełny zakres walidacji
• Walidacja techniczna vs walidacja biznesowa – porównanie procesów
• Błędy walidacji KSeF – co oznaczają – słownik kodów błędów

Najczęstsze pytania

Czy faktura w KSeF musi być podpisana elektronicznie?

Nie zawsze. Kluczowe jest posiadanie odpowiednich uprawnień w systemie KSeF i uwierzytelnienie się przy wysyłce. Dostęp do systemu może odbywać się m.in. przez:

• podpis kwalifikowany,
• pieczęć kwalifikowaną,
• certyfikat KSeF,
• token KSeF.

Jak długo trwa walidacja?

W typowych warunkach walidacja trwa kilka sekund do kilku minut.

Przy dużym obciążeniu systemu czas ten może być dłuższy. Dlatego systemy integrujące się z KSeF zwykle stosują mechanizmy automatycznego ponowienia zapytania w razie braku odpowiedzi w określonym czasie.

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