Faktura w KSeF FA(2): pola, UPO i błędy walidacji 2026 (i jak uniknąć odrzutu przy pierwszym wystawieniu)

Z tego, co widzimy przy wdrożeniach integracji z KSeF, firmy uczą się na własnych błędach dokładnie w tym samym miejscu: pierwsza faktura testowa wraca odrzucona, księgowa dzwoni z pytaniem „co to jest ten kod błędu", a informatyk szuka winy w kodzie, choć problem siedzi w danych kontrahenta wpisanych ręcznie trzy lata temu. Nie zaczynałbym więc tego artykułu od definicji KSeF, bo tę już każdy zna. Zacznę od tego, gdzie realnie leży ryzyko przy pierwszym wystawieniu faktury ustrukturyzowanej, bo tam popełnia się 90% błędów.

Problem nie jest w schemacie XML, tylko w danych źródłowych

Schemat FA(2) jest sztywny i dobrze udokumentowany, to nie jest jego wina. Winne są dane, które od lat leżą w ERP i nikomu nie przeszkadzały, bo faktura papierowa czy PDF toleruje niedopowiedzenia. KSeF nie toleruje. Jeśli w Optimie kontrahent ma NIP wpisany ze spacją albo z prefiksem „PL" tam, gdzie system tego nie oczekuje, faktura PDF wygląda normalnie, a struktura XML już nie przejdzie walidacji. To samo z jednostką miary: w fakturze papierowej „szt." i „szt" to bez różnicy, w FA(2) jednostka musi być zgodna ze słownikiem kodów jednostek miary GUS albo UN/ECE Recommendation 20, a dowolna literówka albo lokalny skrót wymyślony przez handlowca dziesięć lat temu skutkuje odrzutem.

Dlatego w praktyce pierwszy krok integracji nie polega na podłączeniu API KSeF, tylko na audycie słowników w systemie ERP: kartoteka kontrahentów, kartoteka jednostek miary, kartoteka form płatności, przypisane kody GTU do towarów. Dopiero gdy te słowniki są spójne, ma sens testowanie wysyłki na bramce testowej Ministerstwa Finansów. Zaczynanie od strony technicznej integracji, zanim ktokolwiek spojrzał na jakość danych w ERP, to najczęstszy powód, dla którego wdrożenia się przeciągają o kilka tygodni ponad plan.

Pola obowiązkowe FA(2), które najczęściej wywalają walidację

Struktura FA(2) ma dużo pól opcjonalnych i to jest pułapka, bo firmy zakładają, że skoro pole jest opcjonalne w schemacie, to nie trzeba się nim przejmować. Problem w tym, że część pól jest opcjonalna warunkowo: jeśli sprzedajesz towar objęty GTU, kod staje się obowiązkowy dla tej pozycji, mimo że w ogólnym opisie schematu widnieje jako nieobowiązkowy.

NIP i dane identyfikacyjne kontrahenta

Najczęstszy błąd na starcie to niezgodność formatu NIP sprzedawcy albo nabywcy z wymaganym wzorcem (same cyfry, bez myślników, spacji, bez prefiksu kraju w polu przeznaczonym na sam NIP). Drugi w kolejności problem to kontrahent zagraniczny bez polskiego NIP, dla którego trzeba prawidłowo wypełnić pole identyfikatora zagranicznego, a nie próbować wcisnąć go w pole na NIP krajowy. W integracjach z wFirmą i Fakturownią widzieliśmy też sytuacje, w których dane kontrahenta importowane były kiedyś ręcznie z Excela i nikt nie zauważył, że nazwa firmy ma dodatkową spację na końcu albo że pole „kraj" jest puste, choć wizualnie na fakturze PDF to nigdy nie było widać.

Jednostki miary

To jest jeden z najbardziej niedocenianych elementów. FA(2) wymaga kodu jednostki miary zgodnego z obowiązującym słownikiem, a nie dowolnego tekstu. Systemy ERP, szczególnie starsze instalacje Optimy, mają w kartotece towarowej jednostki wpisane ręcznie przez lata, często niespójnie: „kg", "KG", "kilogram", "kilogramy" jako cztery różne pozycje w słowniku dla tego samego towaru w różnych magazynach. Przy eksporcie do KSeF trzeba to zmapować jeden do jednego na kod z listy dopuszczonych jednostek, inaczej faktura zostanie odrzucona już na etapie walidacji struktury, zanim w ogóle trafi do dalszego przetwarzania.

Kody GTU

Kody GTU (grupowanie towarów i usług) są znane firmom z JPK_VAT, ale przy KSeF pojawia się nowy problem: mapowanie kodu GTU musi być przypisane na poziomie pozycji faktury w strukturze XML, a nie tylko zapisane gdzieś w opisie księgowym transakcji. Jeśli w ERP kod GTU jest przypisywany ręcznie przez księgową dopiero na etapie deklaracji VAT, a nie w momencie wystawiania faktury, integracja z KSeF wymusza przeniesienie tej logiki wcześniej, do samego procesu fakturowania. To jedna z częstszych zmian organizacyjnych, jakie trzeba wprowadzić przed pierwszym wystawieniem faktury ustrukturyzowanej, nie tylko techniczna, ale i proceduralna.

Sposób płatności

Pole dotyczące formy płatności w FA(2) musi być wypełnione zgodnie ze zdefiniowanym słownikiem (np. gotówka, przelew, karta, kompensata), a nie dowolnym opisem tekstowym z systemu księgowego. W wFirmie i Fakturowni to zwykle działa poprawnie od razu, bo systemy te mają gotowe mapowanie pod KSeF. Większy problem widzimy tam, gdzie faktury trafiają do KSeF z systemów magazynowo-sprzedażowych zintegrowanych z Optimą przez własne, pisane wewnętrznie skrypty eksportu: tam sposób płatności bywa polem wolnotekstowym i ktoś musi ręcznie zbudować mapowanie na dozwolone wartości, zanim pierwszy plik XML w ogóle trafi do bramki testowej.

UPO: co faktycznie potwierdza i dlaczego bez niego faktura „nie istnieje"

Urzędowe Poświadczenie Odbioru to dokument XML generowany przez system KSeF w momencie, gdy faktura przejdzie pozytywnie walidację i zostanie przyjęta do systemu. UPO zawiera między innymi numer KSeF nadany fakturze (unikalny identyfikator przypisywany przez system po akceptacji), datę i godzinę przyjęcia dokumentu. To właśnie ten moment, a nie moment wysłania pliku przez firmę, jest momentem wystawienia faktury w rozumieniu przepisów o KSeF.

Konsekwencja jest prosta i część firm łapie się na niej dopiero przy pierwszym wystawieniu: jeśli faktura nie przejdzie walidacji, UPO nie zostanie wygenerowane, numer KSeF nie zostanie nadany i formalnie faktura nie została wystawiona, niezależnie od tego, że plik trafił do systemu i księgowa widziała potwierdzenie wysyłki w swoim programie. Program księgowy pokazuje status wysyłki, a nie status akceptacji. To są dwie różne rzeczy i w procedurach wewnętrznych trzeba je rozdzielić: ktoś musi codziennie sprawdzać, czy każda wysłana faktura faktycznie dostała UPO, a nie tylko czy plik opuścił system źródłowy.

W integracjach, które budujemy, ten krok zwykle automatyzujemy: system co jakiś czas odpytuje status faktury w KSeF i jeśli po określonym czasie UPO nie przyszło, wysyła alert do osoby odpowiedzialnej za fakturowanie, zamiast czekać, aż ktoś zorientuje się na koniec miesiąca, że kilkanaście faktur w ogóle nie zostało uznanych za wystawione.

Najczęstsze błędy walidacji przy pierwszym wystawieniu

Bramka testowa Ministerstwa Finansów pozwala sprawdzić poprawność struktury XML jeszcze przed startem produkcyjnym i z naszego doświadczenia warto z niej korzystać znacznie dłużej, niż firmy zakładają na początku, minimum kilka tygodni testów na realnych, historycznych fakturach, nie na dwóch przykładowych rekordach. Błędy, które wracają z bramki testowej, zwykle należą do kilku powtarzalnych kategorii.

Jedno zastrzeżenie, żeby nie było zbyt różowo: żadna integracja nie eliminuje błędów walidacji do zera, zwłaszcza przy pierwszym miesiącu pracy na produkcji. Realistyczny cel to sprowadzenie liczby odrzutów do pojedynczych przypadków tygodniowo i to obsługiwanych ręcznie przez księgową, nie setek faktur, które trzeba poprawiać masowo. Automatyzacja dobrze radzi sobie z powtarzalnymi, przewidywalnymi błędami, ale wyjątek, na przykład nietypowy kontrahent zagraniczny albo niestandardowa transakcja, i tak trafia do człowieka do ręcznej weryfikacji, i to jest zdrowe podejście, a nie porażka systemu.

Terminy obowiązkowego KSeF i co to oznacza dla harmonogramu integracji

Zgodnie z najnowszą nowelizacją ustawy o VAT obowiązek wystawiania faktur w KSeF wchodzi w życie etapami: od 1 lutego 2026 dla podatników, których wartość sprzedaży w 2024 roku przekroczyła 200 mln zł, od 1 kwietnia 2026 dla pozostałych czynnych podatników VAT, a od 1 stycznia 2027 dla podatników zwolnionych podmiotowo z VAT. To oznacza, że firmy z pierwszej grupy mają realnie mniej czasu na testy, niż im się wydaje, bo bramka testowa i tak wymaga tygodni pracy na porządkowaniu danych, zanim integracja pójdzie na produkcję bez niespodzianek.

Z naszej perspektywy błędem jest odkładanie testów integracji do ostatniego kwartału przed terminem. Firmy, które zaczynają porządkować słowniki kontrahentów, jednostek i form płatności z rocznym wyprzedzeniem, trafiają na produkcję z liczbą błędów bliską zeru. Te, które zaczynają na trzy tygodnie przed obowiązkowym terminem, zwykle spędzają pierwszy miesiąc na gaszeniu pożarów i ręcznym poprawianiu odrzuconych faktur, co dla biura rachunkowego obsługującego kilkadziesiąt podmiotów jest realnym obciążeniem operacyjnym, nie teoretycznym ryzykiem.

Jak w praktyce ogarnąć integrację ERP z KSeF

Kolejność, która się sprawdza w naszych wdrożeniach, wygląda tak: najpierw audyt danych w systemie źródłowym (Optima, wFirma, Fakturownia albo dedykowany system sprzedażowy), potem mapowanie słowników na wymagania FA(2), dopiero na końcu podłączenie API i testy na bramce testowej MF na realnych danych historycznych. Odwrócenie tej kolejności, czyli najpierw technika, potem sprzątanie danych, jest głównym powodem opóźnień, jakie widzimy w projektach, które próbowano zrobić samodzielnie bez wcześniejszego doświadczenia z podobną integracją.

Jeśli firma wystawia dziś kilkaset faktur miesięcznie ręcznie albo przez system, który nie ma gotowego modułu KSeF, warto potraktować ten obowiązek nie jako karę administracyjną, tylko jako okazję do uporządkowania procesu fakturowania od podstaw. To dobry moment, żeby przy okazji spiąć fakturowanie z resztą procesów księgowych, bo szczegóły techniczne integracji z KSeF opisujemy dokładniej przy okazji tematu automatyzacji faktur, a dla biur rachunkowych obsługujących wielu klientów jednocześnie sensowniejsze bywa spojrzenie szersze, czyli automatyzacja całego biura rachunkowego, nie tylko samego modułu fakturowania.