Blog

Blog Notaly

Praktyczne odpowiedzi o KSeF, FA(3) i e-fakturowaniu w Polsce.

Najnowszy wpisFA(3)

Struktura XML FA(3): Nagłówek, Fa, Podmiot1/2 i FaWiersz

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.

Tomek12 paź 20263 min czytania

Więcej wpisów

Terminy
Terminy KSeF: od kiedy Twoja firma musi przejść na e-faktury

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.

Tomek12 paź 20262 min czytania
KSeF
Kody błędów KSeF: jak czytać odrzuconą fakturę

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.

Tomek12 paź 20263 min czytania
FA(3)
Faktura korygująca w KSeF: jak jest zbudowana

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ę.

Tomek12 paź 20262 min czytania
Integracje
Integracja z KSeF: budować samemu czy użyć API?

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.

Tomek12 paź 20263 min czytania
KSeF
Numeracja faktur KSeF: jak uniknąć zduplikowanego dokumentu FA(3) (P_2)

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.

Tomek12 paź 20262 min czytania
Poradniki
Przejście na KSeF: praktyczna lista kontrolna

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ą.

Tomek12 paź 20262 min czytania
FA(3)
NIP sprzedawcy i nabywcy w KSeF: jak poprawnie wskazać strony

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.

Tomek12 paź 20263 min czytania
KSeF
PDF faktury KSeF i kod QR: KOD I a KOD II

Gdy faktura zostaje przyjęta, KSeF zwraca UPO (urzędowe poświadczenie odbioru) i numer KSeF; czytelny PDF to wizualizacja, którą Notaly generuje z danych FA(3) i na której umieszcza oficjalny kod QR KOD I. KOD I i KOD II to dwa różne kody, a nie dwa stany jednego: KOD I to link weryfikacyjny budowany przez wystawcę z sumy SHA-256 pliku XML, a KOD II to kod QR wystawcy podpisany certyfikatem KSeF typu Offline, dodawany tylko na fakturze offline.

Tomek12 paź 20263 min czytania
KSeF
Checklista gotowości na KSeF dla małych firm

Gotowość na KSeF to dane stron, pola faktury, sposób uwierzytelniania i przetestowany przepływ — wszystko przygotowane, zanim obejmie Cię obowiązek. Przejdź krótką listę: NIP-y nabywcy i sprzedawcy, mapowanie pól FA(3), uwierzytelnianie tokenem i jeden przebieg testowy, żeby zmiana była mechaniczna, a nie gorączkowa.

Tomek12 paź 20263 min czytania
Integracje
Ponowienia i idempotencja w KSeF: jak nie zdublować faktury

Bezmyślne ponowienie żądania KSeF po timeoutcie może utworzyć duplikat faktury, bo żądanie mogło dotrzeć do KSeF, choć Ty nigdy nie zobaczyłeś odpowiedzi. Bezpieczny wzorzec to stały klucz idempotencji po Twojej stronie przy każdym zgłoszeniu, sprawdzenie statusu faktury w KSeF przed ponowną wysyłką i ponowne wysłanie tylko wtedy, gdy masz pewność, że wcześniejsza próba się nie powiodła.

Tomek12 paź 20263 min czytania
KSeF
Testy KSeF w sandboxie: jak sprawdzić integrację bez ryzyka w produkcji

Integrację z KSeF testujesz w środowisku testowym (api-test.ksef.mf.gov.pl), gdzie każde zgłoszenie nie ma skutku prawnego ani podatkowego. Sandbox Notaly wysyła dokumenty do TEST KSeF z użyciem testowych poświadczeń platformy i daje Ci trzy darmowe faktury testowe, dzięki czemu sprawdzisz XML FA(3) i cały przepływ, zanim w ogóle zbliżysz się do produkcji.

Tomek12 paź 20263 min czytania