KSeF API – FA(3) krok po kroku
Zanim faktura trafi do KSeF, musi istnieć jako dokument XML zgodny ze schematem logicznym FA(3). To ten dokument — a nie dane w Twojej bazie czy obiekt JSON w kodzie — jest tym, co faktycznie ocenia system Ministerstwa Finansów. Jeśli integracja odrzuca faktury, w zdecydowanej większości przypadków problem leży właśnie tutaj: w niezgodności wygenerowanego XML ze strukturą wymaganą przez FA(3).
Czym jest FA(3)
FA(3) to aktualny schemat logiczny faktury ustrukturyzowanej wymagany przez KSeF — dokument XSD określający, jakie elementy musi zawierać faktura, w jakiej kolejności i w jakim formacie. Schemat obejmuje m.in. dane sprzedawcy i nabywcy, pozycje faktury, stawki VAT, sposób płatności, adnotacje oraz — w zależności od typu dokumentu — dodatkowe sekcje (np. dla faktur korygujących czy zaliczkowych).
Dlaczego to nie jest „zwykły XML"
Największa trudność przy generowaniu FA(3) nie leży w samym formacie XML jako takim, tylko w precyzji wymaganej przez schemat: konkretna kolejność elementów, konkretne typy danych, konkretne reguły co do tego, które pola są obowiązkowe w danym kontekście, a które opcjonalne. Dokument technicznie poprawny jako XML, ale niezgodny z regułami XSD, zostanie odrzucony — i to na etapie, na którym trudno się domyślić przyczyny bez dokładnej analizy komunikatu błędu.
Krok 1 — zebranie danych źródłowych
Pierwszy etap to skompletowanie danych transakcji w Twoim systemie: dane sprzedawcy (Twojej firmy), dane nabywcy, lista pozycji z cenami i stawkami VAT, sposób i termin płatności, data wystawienia. Na tym etapie dane wciąż mają dowolną strukturę, jaką narzuca Twój system źródłowy — sklep, ERP czy własna baza danych.
Krok 2 — mapowanie danych na strukturę FA(3)
To najważniejszy i najbardziej podatny na błędy etap. Dane źródłowe trzeba przekształcić tak, by odpowiadały polom oczekiwanym przez schemat:
- Dane kontrahentów — NIP, nazwa, adres muszą być kompletne i w formacie zgodnym z wymaganiami schematu (np. NIP bez dodatkowych znaków, w oczekiwanej długości).
- Stawki VAT — jeśli Twój system przechowuje stawki w innym formacie niż wymagany przez FA(3) (np. jako litery A–E z kasy fiskalnej), trzeba je zmapować na wartości procentowe oczekiwane przez schemat faktury.
- Sumy i zaokrąglenia — wartości netto, VAT i brutto muszą być spójne matematycznie; rozbieżność wynikająca z błędnej kolejności zaokrągleń to częsty powód odrzuceń.
- Adnotacje — pola takie jak sposób rozliczenia, procedury szczególne czy oznaczenia (np. przy samofakturowaniu) muszą być ustawione zgodnie z faktycznym charakterem transakcji.
Krok 3 — zachowanie właściwej kolejności elementów
Schemat XSD FA(3) definiuje ścisłą kolejność elementów XML. Nawet jeśli wszystkie wymagane dane są obecne, ale kolejność elementów w dokumencie nie odpowiada schematowi, walidacja zakończy się niepowodzeniem. To błąd, który szczególnie często pojawia się przy ręcznym budowaniu XML bez użycia dedykowanego generatora — łatwo wstawić element „logicznie", zapominając, że XSD wymaga konkretnej sekwencji.
Krok 4 — walidacja XSD przed wysyłką
Dobra praktyka to zwalidowanie gotowego dokumentu względem schematu XSD FA(3) jeszcze zanim trafi do KSeF. Pozwala to wyłapać niezgodności strukturalne od razu — z konkretnym wskazaniem, który element i dlaczego nie spełnia wymagań schematu — zamiast dowiadywać się o tym dopiero po odrzuceniu przez system Ministerstwa Finansów, gdzie diagnoza bywa trudniejsza.
Krok 5 — wysyłka i interpretacja odpowiedzi
Po pozytywnej walidacji lokalnej dokument trafia do KSeF. Warto pamiętać, że walidacja lokalna względem XSD nie gwarantuje stuprocentowo akceptacji — KSeF może odrzucić dokument również z powodów biznesowych (np. niezgodność danych kontrahenta z rejestrem), niezwiązanych bezpośrednio ze strukturą XML.
Typowe problemy przy generowaniu FA(3)
- Niepoprawna kolejność elementów — najczęstszy błąd przy ręcznym budowaniu XML.
- Błędne mapowanie stawek VAT — szczególnie przy integracji z systemami, gdzie stawki są przechowywane w innym formacie (np. litery z kasy fiskalnej).
- Niespójne sumy — rozbieżność między sumą wartości pozycji a wartością całkowitą dokumentu, często wynikająca z błędnej kolejności zaokrągleń przy wielu pozycjach.
- Braki w danych kontrahenta — niekompletny adres lub błędny NIP, szczególnie przy automatycznym imporcie danych z zewnętrznych źródeł.
- Nieaktualny schemat — generator XML zbudowany pod starszą wersję FA(3), niezaktualizowany po zmianie specyfikacji.
Czy trzeba budować generator FA(3) samodzielnie
Ręczne budowanie generatora zgodnego z pełnym schematem FA(3) — łącznie z obsługą wszystkich typów dokumentów (faktura podstawowa, korygująca, zaliczkowa, eksportowa) — to spory nakład pracy, który trzeba potem utrzymywać wraz ze zmianami specyfikacji. Warstwy pośredniczące (jak API KSeFService) pozwalają pominąć ten etap: wystarczy przekazać dane w prostszym formacie (JSON), a poprawny, zwalidowany dokument FA(3) generowany jest automatycznie po drugiej stronie.
Podsumowanie
FA(3) to nie formalność do „odhaczenia", tylko rdzeń całej integracji z KSeF — większość realnych problemów z wysyłką faktur ma swoje źródło właśnie na etapie generowania tego dokumentu. Zrozumienie struktury schematu i konsekwentna walidacja przed wysyłką znacząco skracają czas debugowania integracji.
Chcesz generować FA(3) bez budowania własnego generatora XML? Sprawdź dokumentację API KSeFService lub zobacz praktyczny przykład integracji krok po kroku.
