Jak odczytać XML z KSeF?

XML z KSeF to plik danych, a nie dokument do czytania jak zwykły PDF. Możesz otworzyć go w edytorze tekstu, ale bez znajomości struktury FA(3) łatwo pomylić numer faktury, numer KSeF, dane stron albo techniczne metadane.

Najbezpieczniejsza kolejność to: potwierdź pochodzenie pliku, sprawdź wersję FA(3), odczytaj dane sprzedawcy i nabywcy, porównaj pozycje oraz kwoty, a potem uruchom walidację. Dopiero czytelna wizualizacja PDF pomaga przejrzeć fakturę oczami człowieka.

Konwersja XML do PDF nie zastępuje walidacji i nie potwierdza, że faktura została przyjęta przez KSeF. PDF jest podglądem. Oficjalne znaczenie mają XML FA(3), status systemowy, numer KSeF i UPO.

Jeżeli potrzebujesz instrukcji samego generowania wizualizacji, przejdź do poradnika Jak zamienić XML KSeF na czytelną fakturę PDF.

1. Czym jest XML z KSeF

2. Cztery poziomy sprawdzenia XML

3. Mapa XML dla nietechnicznego użytkownika

4. Numer KSeF, numer faktury i metadane

5. Walidacja przed wizualizacją

6. Czerwone flagi w pliku XML

7. Jak połączyć odczyt, walidację i archiwizację

8. Najczęściej zadawane pytania

Poniższa tabela pokazuje, co warto ustalić zanim uznasz, że plik XML z KSeF jest gotowy do księgowania lub przekazania dalej.

Plik XML z KSeF zawiera fakturę ustrukturyzowaną, czyli dokument zapisany według określonego schematu danych. W praktyce oznacza to, że nazwa sprzedawcy, NIP, numer faktury, data, pozycje, stawki VAT i kwoty są zapisane w konkretnych elementach, które może odczytać system księgowy.

Taki plik nie musi wyglądać przyjaźnie dla człowieka. Zobaczysz znaczniki, nawiasy ostre i pola o nazwach technicznych, ale dla KSeF właśnie ta struktura jest kluczowa. System nie ocenia układu graficznego faktury, tylko dane zapisane w formacie XML FA(3).

Jeżeli chcesz zrozumieć podstawy formatu, wróć do poradnika XML i format FA(3) w KSeF. Ten artykuł skupia się na praktycznym odczytaniu pliku, który już masz na dysku lub dostałeś z programu księgowego.

Najpierw ustal, skąd pochodzi XML. Inaczej traktujesz plik pobrany bezpośrednio z KSeF, inaczej eksport z programu księgowego, a jeszcze inaczej załącznik otrzymany mailem. Jeżeli nie znasz źródła, nie uruchamiaj żadnych makr, skryptów ani konwerterów instalowanych z przypadkowych stron.

Do pierwszego podglądu wystarczy zwykły edytor tekstu. Nie edytuj jednak pliku, jeżeli ma być dowodem, załącznikiem do procesu księgowego albo materiałem do diagnozy błędu. Zapisz oryginał w niezmienionej postaci i pracuj na kopii.

Jeżeli plik ma służyć do księgowania lub wyjaśnienia rozbieżności, od razu zapisz również kontekst: kto go przekazał, kiedy został pobrany, czy ma numer KSeF, czy masz UPO i z jakiego systemu pochodzi eksport.

Samo otwarcie pliku nie oznacza jeszcze, że faktura została sprawdzona. W praktyce trzeba rozdzielić cztery różne czynności: odczyt tekstu, wizualizację, walidację i potwierdzenie w KSeF.

To rozróżnienie chroni przed częstym błędem: ktoś widzi czytelny PDF albo poprawnie otwarty plik XML i zakłada, że dokument jest automatycznie poprawny. Tymczasem każdy poziom odpowiada na inne pytanie.

Jeżeli dokument ma trafić do księgowania, nie zatrzymuj się na pierwszym poziomie. Otwarty XML pokazuje dane, ale dopiero połączenie walidacji, numeru KSeF, metadanych i UPO daje sensowny obraz statusu faktury.

Nie musisz znać całego schematu XSD, żeby wykonać pierwszą kontrolę. Wystarczy wiedzieć, które obszary odpowiadają najważniejszym częściom faktury. Nazwy węzłów mogą wyglądać technicznie, ale ich sens jest księgowy.

Naglowek identyfikuje formularz, wariant struktury i dane techniczne. Podmiot1 to sprzedawca, a Podmiot2 to nabywca. Fa zawiera dane faktury, w tym numer, daty, walutę i rodzaj faktury. FaWiersz opisuje pozycje faktury. Pola podsumowujące w sekcji Fa pokazują wartości netto, VAT i brutto według stawek.

Przykład praktyczny: gdy szukasz NIP sprzedawcy, zacznij od obszaru Podmiot1. Gdy szukasz numeru własnego faktury, przejdź do danych w obszarze Fa. Gdy sprawdzasz kwoty i stawki, porównaj FaWiersz z polami podsumowującymi w Fa, zamiast czytać cały dokument od początku.

Nie traktuj tej mapy jako pełnej listy pól obowiązkowych. Wymagania zależą od typu faktury i szczegółowych reguł FA(3). Mapa ma pomóc w orientacji, a nie zastąpić walidację pliku.

Pierwsza kontrola nie polega na czytaniu całego pliku od góry do dołu. Zacznij od pól, które najczęściej decydują o identyfikacji dokumentu i dalszej pracy księgowej.

Porównaj numer faktury z dokumentem źródłowym lub systemem księgowym. Następnie sprawdź NIP sprzedawcy, NIP nabywcy, datę wystawienia, datę sprzedaży, jeżeli występuje, walutę, pozycje, stawki VAT i sumy. Jeżeli faktura ma numer KSeF, zapisz go razem z datą przyjęcia i statusem.

Jeżeli widzisz różnicę między XML a oczekiwanym dokumentem, nie poprawiaj ręcznie końcowego pliku bez zrozumienia przyczyny. Najczęściej poprawia się dane w systemie źródłowym, a potem generuje nowy XML.

Jednym z najczęstszych źródeł pomyłek jest mieszanie numeru faktury z numerem KSeF. Numer faktury nadaje sprzedawca w swoim systemie. Numer KSeF nadaje centralny system po przyjęciu dokumentu i ma własną strukturę techniczną.

Numer KSeF ma 35 znaków i składa się z NIP sprzedawcy, daty przyjęcia, 12-znakowej części technicznej oraz 2-znakowej sumy kontrolnej CRC-8. To nie jest zamiennik numeru faktury z pola sprzedażowego i nie powinien być ręcznie wymyślany ani korygowany.

Przy odbieraniu faktur przez KSeF możesz spotkać zarówno XML faktury, jak i metadane. Metadane pomagają wyszukać dokument, sprawdzić identyfikatory i statusy, ale nie są tym samym co pełna treść faktury. Jeżeli chcesz szerzej rozdzielić identyfikatory, zobacz Numer KSeF na fakturze. Dlatego przy audycie zachowuj komplet: XML, metadane, numer KSeF, status oraz UPO w KSeF, jeżeli jest dostępne.

Czytelny PDF pomaga szybko zobaczyć, co jest na fakturze, ale najpierw warto wiedzieć, czy XML ma sens techniczny. Walidator wykrywa problemy, których oko człowieka nie zobaczy w podglądzie, na przykład nieprawidłowy format daty, brak wymaganego elementu albo niezgodność ze schematem.

Walidacja techniczna nie daje gwarancji poprawności podatkowej. Może pomóc wykryć problemy strukturalne i część niespójności, ale nie rozstrzyga, czy transakcja została prawidłowo opodatkowana, czy stawka VAT jest merytorycznie właściwa i czy faktura odpowiada umowie.

Jeżeli chcesz sprawdzić plik przed dalszą pracą, użyj walidatora XML KSeF. To publiczne narzędzie z limitem w 24-godzinnym oknie, więc aktualne warunki użycia najlepiej sprawdzić bezpośrednio na stronie narzędzia.

XML jest formatem dla systemów, a PDF jest wygodnym widokiem dla człowieka. Konwersja do PDF ma sens, gdy chcesz szybko porównać dane z zamówieniem, pokazać fakturę osobie nietechnicznej, przekazać dokument do akceptacji lub sprawdzić pozycje bez przewijania surowego pliku.

Nie traktuj jednak PDF jako nowej wersji faktury. Jeżeli PDF powstał z XML, jest tylko wizualizacją danych. Jeżeli w danych źródłowych jest błąd, PDF pokaże ten sam błąd w ładniejszej formie.

KSeFGPT udostępnia konwerter XML do PDF KSeF. To publiczne narzędzie z limitem w 24-godzinnym oknie, dlatego bieżące warunki użycia warto sprawdzić bezpośrednio na stronie konwertera.

Poniższe sygnały nie zawsze oznaczają odrzucenie faktury, ale wymagają zatrzymania procesu i sprawdzenia źródła danych. Szczególnie ostrożnie traktuj pliki, które mają trafić do księgowania lub stanowić podstawę sporu z kontrahentem.

Jeżeli coś wygląda podejrzanie, nie ograniczaj się do wizualizacji PDF. Zachowaj oryginalny XML, uruchom walidację, sprawdź metadane i porównaj dokument z danymi w systemie, który go wygenerował.

Nie wgrywaj wrażliwego XML do przypadkowych konwerterów znalezionych w wyszukiwarce. Faktura może zawierać dane kontrahentów, adresy, numery rachunków, kwoty i informacje handlowe, więc używaj narzędzi, których politykę prywatności oraz zakres przetwarzania rozumiesz.

Praktyczny proces powinien mieć trzy warstwy. Najpierw zachowujesz oryginalny XML i metadane pobrania. Potem sprawdzasz plik technicznie. Na końcu tworzysz czytelny podgląd PDF lub przekazujesz dane do systemu księgowego.

Dzięki temu nie tracisz dowodu źródłowego. Jeżeli po drodze pojawi się błąd, możesz wrócić do oryginału, sprawdzić status KSeF, porównać numer faktury z numerem KSeF i odtworzyć, kto oraz kiedy pracował na pliku.

Przy większej liczbie dokumentów ręczne otwieranie XML szybko staje się ryzykowne. Wtedy warto oprzeć proces na narzędziu, które łączy import, walidację, podgląd, wyszukiwanie po kontrahencie i archiwizację wyników.

Jeżeli chcesz zrozumieć strukturę dokumentu, zacznij od poradnika XML i format FA(3) w KSeF. Jeżeli pracujesz z fakturą otrzymaną jako PDF i dopiero potrzebujesz XML, przejdź do artykułu Darmowy konwerter PDF do XML KSeF.

Do technicznej kontroli plików przyda się tekst Walidacja i przetwarzanie XML w KSeF. Jeżeli XML został odrzucony przez system, sprawdź poradnik Faktura odrzucona przez KSeF.

Nie zaczynaj od przepisywania danych z XML do arkusza. Najpierw zachowaj oryginał, potwierdź źródło, sprawdź numer KSeF lub status dokumentu i uruchom walidację. Dopiero potem twórz PDF, przekazuj dane do księgowania albo wyjaśniaj różnice z kontrahentem.

Dla pojedynczych plików wystarczy połączenie walidatora i konwertera XML do PDF. Przy większej liczbie faktur potrzebny jest proces, który pozwala śledzić źródło pliku, wersję, wynik walidacji i archiwum dokumentów.

Rekomendowane artykuły: XML i format FA(3) w KSeF, Numer KSeF na fakturze, Status faktury KSeF oraz Brak UPO w KSeF.