Walidacja XML faktury przed wysyłką do KSeF – dlaczego jest kluczowa w integracjach marketplace

Faktura może wyglądać poprawnie w panelu sprzedawcy, przejść przez system ERP, dostać numer w marketplace, a mimo to zostać odrzucona przez KSeF. Powód bywa banalny: niezgodny format daty, brak obowiązkowego pola, źle przypisany NIP, niepoprawna stawka VAT albo element XML umieszczony w niewłaściwym miejscu. Dla pojedynczej faktury to irytacja. Dla integracji marketplace, która generuje setki lub tysiące dokumentów dziennie, to już realny problem operacyjny.

Walidacja XML faktury przed wysyłką do KSeF nie jest dodatkiem dla perfekcjonistów. To filtr bezpieczeństwa, który powinien zatrzymać błąd zanim dokument trafi do systemu Ministerstwa Finansów. Zwłaszcza tam, gdzie dane płyną z wielu źródeł: koszyka zakupowego, systemu płatności, konta sprzedawcy, magazynu, modułu zwrotów, programu księgowego i API marketplace.

XML faktury nie wybacza „prawie poprawnych” danych

W integracjach marketplace najwięcej problemów nie bierze się z samego KSeF, tylko z jakości danych zebranych wcześniej. Sprzedawca widzi zamówienie. Klient dostał produkt. Płatność się zgadza. Dopiero przy fakturze okazuje się, że dane nabywcy są niepełne, adres jest rozbity inaczej niż wymaga struktura, a numer identyfikacyjny podano w polu, które nie pasuje do typu kontrahenta.

KSeF przyjmuje faktury ustrukturyzowane zgodne ze strukturą logiczną FA(3). Od 1 lutego 2026 r. to właśnie FA(3) jest obowiązującym wzorem dla faktur ustrukturyzowanych. W praktyce oznacza to, że integracja nie może produkować „dowolnego XML-a przypominającego fakturę”. Dokument musi być zgodny ze schematem, typami danych, kolejnością elementów i regułami biznesowymi.

Najczęstsze błędy, które warto wyłapać przed wysyłką:

• brak pól wymaganych dla danego typu faktury lub kontrahenta,
• niepoprawny format daty, kwoty albo numeru identyfikacyjnego,
• niezgodność sum: pozycje faktury, VAT i wartość brutto nie składają się matematycznie,
• błędne oznaczenie nabywcy krajowego, unijnego albo spoza UE,
• użycie starej struktury zamiast aktualnej wersji FA(3),
• przekazanie znaków specjalnych, których system pośredni nie obsłużył poprawnie,
• mieszanie danych zamówienia z danymi do faktury, szczególnie przy zakupach firmowych.

Najwyższy priorytet ma walidacja techniczna: zgodność XML ze schematem XSD. Bez tego nie ma sensu analizować kolejnych warstw, bo dokument i tak polegnie na podstawowym progu. Drugi poziom to walidacja biznesowa: czy kwoty, stawki, role stron i dane identyfikacyjne mają sens. Dopiero trzeci poziom to kontrola procesowa, czyli pytanie, czy faktura powinna zostać wystawiona teraz, dla tego zamówienia i z tych danych.

Tego nie warto odwracać. Najpierw poprawność struktury, potem logika podatkowa, na końcu automatyzacja procesu.

Marketplace ma więcej punktów awarii niż klasyczny sklep

W zwykłym sklepie internetowym właściciel często kontroluje cały proces: formularz zamówienia, dane klienta, płatność, wystawienie dokumentu i księgowanie. Marketplace działa inaczej. Sprzedawca może mieć własny system magazynowy, marketplace własny format danych, operator płatności osobne identyfikatory transakcji, a księgowość jeszcze inną logikę numeracji.

To tworzy kilka ryzyk, których nie widać przy małej skali:

• różne źródła prawdy — inne dane w zamówieniu, inne na koncie klienta, inne w systemie fakturowym;
• opóźnienia synchronizacji — faktura powstaje zanim aktualizacja danych nabywcy dotrze z marketplace;
• wielowalutowość — kurs, waluta i przeliczenia muszą być spójne z zasadami fakturowania;
• korekty i zwroty częściowe — system musi wiedzieć, do której faktury odnosi się korekta i jakie pozycje obejmuje;
• sprzedaż wielu sprzedawców w jednym koszyku — jeden zakup użytkownika nie zawsze oznacza jedną fakturę;
• różne modele prowizji — marketplace może rozliczać prowizję, usługę logistyczną, opłatę za płatność i sprzedaż towaru jako oddzielne zdarzenia.

W takim środowisku samo sprawdzenie, czy XML „jest poprawny”, nie wystarczy. Walidacja powinna być osadzona w procesie. Dobra praktyka wygląda tak: system najpierw buduje fakturę z danych źródłowych, następnie wykonuje walidację XSD, później sprawdza reguły biznesowe, a dopiero potem wysyła dokument do KSeF. Jeżeli błąd wystąpi, faktura trafia do kolejki wyjątków, a nie ginie w logach technicznych.

To ważna decyzja projektowa. Nie należy wysyłać dokumentów do KSeF tylko po to, żeby sprawdzić, czy przejdą. Środowisko produkcyjne nie powinno pełnić funkcji testera jakości danych. Przy dużym wolumenie kończy się to chaosem: ponowieniami, rozbieżnościami statusów, ręcznym poprawianiem rekordów i niepewnością, czy faktura została skutecznie wystawiona.

Najrozsądniejszy wariant to blokada wysyłki, gdy błąd dotyczy pól obowiązkowych, identyfikacji stron, sum kontrolnych albo zgodności ze schematem. Błędy miękkie — na przykład podejrzanie krótka nazwa firmy czy nietypowy adres — można oznaczyć ostrzeżeniem, ale nie zawsze trzeba zatrzymywać cały proces. Granica jest prosta: jeśli błąd może spowodować odrzucenie faktury albo błędne rozliczenie podatkowe, dokument nie powinien wyjść z systemu.

Jak ustawić walidację, żeby nie blokowała sprzedaży

Największy błąd we wdrożeniach KSeF dla marketplace polega na traktowaniu walidacji jak jednego przycisku: „sprawdź fakturę”. W rzeczywistości potrzebne są co najmniej cztery warstwy kontroli.

Pierwsza to walidacja wejścia danych. Formularz fakturowy nie powinien przyjmować dowolnej treści w polach krytycznych. NIP, kraj, typ nabywcy, adres, waluta i dane firmy powinny być kontrolowane już przy zamówieniu albo przy edycji danych konta. Im później wykryty błąd, tym drożej kosztuje jego obsługa.

Druga to walidacja mapowania. To moment, w którym dane z marketplace są przepisywane do struktury faktury. Tu łatwo o pomyłkę: pole „company_name” z API platformy nie zawsze znaczy to samo co nazwa nabywcy na fakturze. Podobnie adres dostawy nie musi być adresem nabywcy. W integracjach wielokanałowych trzeba jawnie opisać, skąd pochodzi każde pole faktury i co zrobić, gdy danych brakuje.

Trzecia to walidacja XML względem XSD. Ten etap powinien działać automatycznie dla każdej faktury przed wysyłką. Jeżeli system obsługuje paczki faktur, walidacja musi wskazywać konkretny dokument i konkretny błąd, a nie tylko informować, że „paczka jest niepoprawna”.

Czwarta to monitoring po wysyłce. Walidacja przed KSeF ogranicza ryzyko, ale nie gwarantuje, że każdy dokument zostanie przyjęty bez problemu. Po stronie integracji nadal trzeba obsłużyć statusy, identyfikatory, ponowienia, awarie połączenia, przerwy techniczne i przypadki, w których dokument został przyjęty, ale dalszy proces w systemie księgowym zatrzymał się z innego powodu.

Praktyczna kolejność wdrożenia jest taka:

• najpierw aktualna struktura FA(3) i poprawne generowanie XML,
• potem twarde walidatory dla pól obowiązkowych, kwot i identyfikatorów,
• następnie kolejka błędów z czytelnym opisem dla księgowości lub supportu,
• dopiero później automatyczne ponowienia, dashboardy i bardziej zaawansowane reguły.

Nie warto zaczynać od rozbudowanego panelu monitoringu, jeśli sam XML jest niestabilny. Ładny dashboard nie naprawi faktur, które mają błędnie policzony VAT albo źle zmapowanego nabywcę.

Dobrze zaprojektowana walidacja powinna też rozróżniać błędy techniczne i biznesowe. Komunikat „element P_13_1 niezgodny ze schematem” jest przydatny dla programisty, ale dla działu księgowości brzmi jak kod z czarnej skrzynki. Lepszy komunikat to: „Suma netto pozycji ze stawką 23% nie zgadza się z wartością netto wykazaną w podsumowaniu faktury”. Taki błąd da się naprawić bez szukania w dokumentacji XML.

Więcej informacji na: https://ksefservice.pl

FAQ

Czy poprawny XML gwarantuje przyjęcie faktury przez KSeF?
Nie. Poprawność XML względem schematu jest warunkiem podstawowym, ale dochodzą jeszcze reguły biznesowe, dostępność systemu, autoryzacja, status sesji i poprawna obsługa odpowiedzi z API.

Czy walidację trzeba robić dla każdej faktury osobno?
Tak, zwłaszcza w marketplace. Nawet jeśli dokumenty powstają z tego samego szablonu, dane nabywcy, stawki VAT, rabaty, korekty i waluty mogą się różnić. Jeden poprawny przypadek testowy nie zabezpiecza całej sprzedaży.

Co powinno zatrzymać wysyłkę faktury do KSeF?
Błędy w strukturze XML, brak pól wymaganych, niespójne sumy, niepoprawny NIP, błędny typ kontrahenta, niezgodna wersja schematu i każda sytuacja, w której dokument może zostać odrzucony albo wystawiony z danymi niezgodnymi z transakcją.

Czy marketplace powinien sam poprawiać błędne dane faktury?
Tylko w ograniczonym zakresie. System może ujednolicić format daty, usunąć zbędne spacje albo przeliczyć sumy zgodnie z ustaloną regułą, ale nie powinien zgadywać nazwy firmy, numeru NIP, kraju nabywcy ani podstawy korekty. Takie przypadki wymagają świadomej poprawy danych.

Od czego zacząć, jeśli integracja już wysyła faktury, ale pojawiają się odrzucenia?
Najpierw trzeba zebrać odrzucone dokumenty i pogrupować błędy. Jeżeli powtarza się ten sam problem, popraw mapowanie albo regułę walidacji przed wysyłką. Ręczne naprawianie pojedynczych faktur ma sens tylko wtedy, gdy błąd jest incydentalny. Jeśli wraca codziennie, problem siedzi w procesie, nie w fakturze.