KSeF: statusy wysyłki i typowe błędy walidacji FA(3)

TL;DR

W KSeF samo „wysłanie” dokumentu nie oznacza jeszcze sukcesu. Trzeba rozumieć statusy sesji, numer KSeF, UPO oraz błędy walidacji FA(3). Najczęstsze problemy wynikają z niezgodności XML ze schemą, błędnych dat, kolejności elementów albo niepełnych danych.

Co dzieje się po wysłaniu faktury?

Po wysłaniu dokumentu do KSeF firma powinna obserwować kilka rzeczy:

• czy dokument został przyjęty przez system,
• czy otrzymał numer KSeF,
• czy pojawiło się UPO,
• czy wystąpił błąd techniczny lub walidacyjny.

W praktyce właśnie ten moment decyduje, czy faktura naprawdę weszła do obrotu przez KSeF.

Typowe statusy operacyjne

W systemach zintegrowanych spotkasz zwykle następujące etapy:

• do wysłania,
• oczekujące,
• wysłane,
• przyjęte / numer KSeF nadany,
• błąd,
• offline.

Nazwy mogą się różnić w zależności od aplikacji, ale logika jest podobna: trzeba odróżnić dokument tylko wysłany od dokumentu ostatecznie przyjętego.

Gdzie w tym wszystkim jest UPO?

UPO potwierdza, że dokument został przyjęty i przetworzony. W praktyce stanowi najważniejsze potwierdzenie dla użytkownika biznesowego. Sam status „wysłano” bez finalnego potwierdzenia nie daje jeszcze pełnego komfortu.

Czym są błędy walidacji FA(3)?

FA(3) to aktualna struktura logiczna e-faktury. Jeżeli XML nie zgadza się ze schemą, KSeF odrzuci dokument lub zwróci błąd walidacyjny.

Najczęstsze przyczyny:

• błędny namespace,
• zła kolejność elementów,
• brak wymaganych pól,
• zły format daty,
• niepoprawne wartości liczbowe,
• użycie starej struktury zamiast FA(3).

Najczęstsze problemy praktyczne

Brak pól obowiązkowych

W XML może brakować wymaganych sekcji lub danych kontrahenta.

Zły format danych

Daty, liczby i niektóre kody muszą być zgodne z oczekiwanym formatem.

Błędna kolejność elementów

To częsty problem przy własnych generatorach XML.

Niezgodny namespace

Jeżeli system generuje XML według starej struktury, dokument nie przejdzie poprawnie walidacji.

Jak ograniczyć liczbę błędów?

Najlepiej wdrożyć trzy zasady:

1. walidacja XML lokalnie przed wysyłką,
2. czytelny monitoring statusów po wysyłce,
3. archiwizacja UPO i logów odpowiedzi.

Jak pomaga KSeF Desk?

KSeF Desk już pokazuje statusy, przechowuje logikę obsługi odpowiedzi i ma rozwijany model śledzenia błędów oraz statusów dostawy. To ważne, bo użytkownik biznesowy nie chce analizować surowych payloadów API — chce widzieć prosty komunikat i wiedzieć, co dalej zrobić.

FAQ

Czy numer KSeF oznacza pełny sukces?

To bardzo ważny etap, ale w praktyce warto jeszcze mieć porządek w UPO i archiwizacji statusów.

Czy każda aplikacja pokazuje statusy tak samo?

Nie. Dlatego warto patrzeć nie na kolor ikonki, tylko na faktyczny sens statusu.

Czy błędy walidacji da się ograniczyć?

Tak, przez lokalną walidację XML, dobre mapowanie danych i aktualną strukturę FA(3).

Źródła do weryfikacji

• praktyczne bazy wiedzy o UPO i statusach wysyłki
• materiały o błędach walidacji FA(3)
• dokumentacja integracyjna i oficjalna struktura KSeF

Powiązane tematy i kolejne kroki

Statusy wysyłki i walidacja są najmocniej powiązane z tymi tematami:

• Co to jest UPO w KSeF i gdzie je sprawdzić?,
• Najczęstsze błędy przy wysyłce faktur do KSeF i jak je obsłużyć,
• KSeF API: co musi umieć integracja w praktyce.

Warto znać też definicję FA(3) w KSeF.