Jak Krajowy System e-Faktur działa w praktyce: sesje, statusy, UPO i zasady, które dotyczą wywołań API.
FA(3) to ustrukturyzowany format XML, w którym KSeF zapisuje e-fakturę. Definiuje go oficjalny schemat (XSD) opublikowany przez Ministerstwo Finansów; to nie jest dokument do wydruku jak PDF — to dane odczytywalne maszynowo, które opisują sprzedawcę, nabywcę, pozycje, sumy i pola VAT. W praktyce generujesz XML z danych faktury i walidujesz go wobec schematu, zamiast pisać ręcznie.
Faktura KSeF w formacie FA(3) to jeden ustrukturyzowany dokument XML, którego elementem głównym jest Faktura. Nagłówek niesie metadane formularza (kod formularza, wariant, znacznik czasu wytworzenia i informacje o systemie), a dane faktury — data wystawienia P_1, numer faktury P_2, strony transakcji (Podmiot1 dla sprzedawcy, Podmiot2 dla nabywcy) oraz pozycje (FaWiersz) — leżą w elemencie Fa. Nie musisz pisać tego XML-a ręcznie — API takie jak Notaly buduje go ze zwykłego payloadu JSON.
Fakturą prawnie wiążącą w KSeF jest ustrukturyzowany plik XML FA(3), a UPO wraz z numerem KSeF to Twoje potwierdzenie, że dokument został przyjęty. KSeF przechowuje faktury, które u siebie gromadzi, przez 10 lat, więc możesz je odzyskać, dopóki masz dostęp; lokalnie archiwizuj razem XML, numer UPO i numer KSeF. PDF traktuj jako kopię do czytania dla ludzi, a nie jako dokument źródłowy.
KSeF (Krajowy System e-Faktur) to ogólnopolski system e-fakturowania, a obowiązek wystawiania faktur ustrukturyzowanych obejmuje czynnych podatników VAT stopniowo: to, kiedy firma musi się przełączyć, zależy od jej wielkości i od harmonogramu publikowanego przez Ministerstwo Finansów. Wdrożenie już kilkukrotnie przesuwano, dlatego zanim cokolwiek zmienisz, potwierdź swój termin w aktualnym oficjalnym harmonogramie. Niezmienne pozostaje wymaganie techniczne — gdy obowiązek już Cię obejmuje, faktury B2B trzeba wystawiać jako ustrukturyzowany XML FA(3) z numerem KSeF i UPO.
KSeF zgłasza problemy jako kody wyjątków w treści odpowiedzi, obok statusu HTTP — i to kod, a nie sam numer HTTP, mówi, co naprawdę się nie powiodło. Najczęstsze przyczyny to nieprawidłowe wyzwanie uwierzytelniające, nieprawidłowy certyfikat albo faktura, która nie przechodzi schematu FA(3) i jest następnie raportowana jako nieprawidłowo przetworzona. Zamiast zgadywać, porównaj polski opis z oficjalną tabelą kodów KSeF — ten sam numer potrafi znaczyć co innego w różnych endpointach.
FA(3) to aktualny schemat faktury ustrukturyzowanej w KSeF, a migracja ze starszej struktury FA(2) to przemapowanie pól, nie samo przemianowanie elementu głównego. W FA(3) dane faktury — między innymi P_6 (data dostawy lub wykonania usługi), bloki stron Podmiot1/Podmiot2 i pozycje FaWiersz — leżą wewnątrz elementu Fa, oddzielnie od nagłówka formularza (Nagłówek). Sprawdź położenie każdego pola względem aktualnego XSD, zamiast zakładać, że pozycje z FA(2) nadal obowiązują.
W KSeF faktura korygująca to nowy dokument FA(3), który wskazuje korygowaną fakturę przez pola takie jak NrKSeFFaKorygowanej (numer KSeF faktury korygowanej) i PrzyczynaKorekty (powód korekty). Nie edytujesz pierwotnej faktury — wysyłasz dokument korygujący, który się do niej odwołuje. To, czy korekta jest wymagana i jak rozliczyć różnicę VAT, to decyzja podatkowa dla księgowego; format FA(3) opisuje wyłącznie strukturę.
Samodzielna integracja z KSeF to sporo roboty technicznej: po Twojej stronie leży XML w formacie FA(3), uwierzytelnianie, szyfrowana wysyłka i pilnowanie statusów. Gotowe API przyjmuje zwykły JSON i zdejmuje z Ciebie całą resztę. Dla sklepu internetowego czy zespołu SaaS to zwykle szybsza i tańsza droga, a własna budowa opłaca się dopiero wtedy, gdy fakturowanie elektroniczne jest sercem Twojego produktu.
P_2 to pole numeru faktury w elemencie Fa dokumentu FA(3) i musi jednoznacznie identyfikować jedną wystawioną fakturę. Stosuj stabilny, sekwencyjny schemat i nigdy nie używaj numeru ponownie — inaczej KSeF może odrzucić dokument jako duplikat.
Przejście na KSeF to zmiana danych i procesu, a nie tylko podmiana API: potrzebujesz czystych identyfikatorów stron, odwzorowania faktury dającego poprawny FA(3), metody uwierzytelnienia i przebiegu testowego przed produkcją. Przejście przez tę krótką listę w sandboksie sprawia, że wejście na produkcję staje się zmianą konfiguracji, a nie pierwszą próbą.
Tryb offline KSeF to procedura awaryjna Ministerstwa Finansów na fakturowanie, gdy platforma jest niedostępna; dokument i tak trzeba później przesłać do KSeF, w oknie wyznaczonym przez Ministerstwo. W KSeF 2.0 faktura offline ma dwa kody QR: KOD I to link weryfikacyjny generowany przez wystawcę z sumy SHA-256 pliku XML, a KOD II to kod QR wystawcy podpisany certyfikatem KSeF typu Offline.
Identyfikatory podatkowe sprzedawcy i nabywcy to najczęstsza przyczyna odrzucenia faktury FA(3): NIP sprzedawcy musi pasować do uwierzytelnionego kontekstu KSeF, a NIP nabywcy musi być prawidłowym polskim identyfikatorem podatkowym. W schemacie FA(3) sprzedawca to Podmiot1, a nabywca to Podmiot2, i każda strona przechowuje swój NIP w bloku identyfikacyjnym.
Załóż konto sandbox: klucz API w kilka sekund, 3 darmowe faktury testowe w KSeF TEST, bez karty płatniczej.
