Jak walidować faktury przed wysłaniem do KSeF

System KSeF odrzuca faktury z błędami strukturalnymi (XSD) i wybranymi naruszeniami merytorycznymi. Odrzucenie oznacza, że faktura nie została przyjęta i nie nadano numeru KSeF — trzeba ją poprawić i wysłać ponownie. Data przyjęcia w KSeF ponownego wysłania może różnić się od zamierzonej daty wystawienia, co może przesunąć okres rozliczeniowy VAT.

Walidacja wstępna eliminuje ten problem: sprawdzasz fakturę zanim ją wyślesz. Błędy są widoczne od razu, a poprawki można wprowadzić przed transmisją. To szczególnie ważne przy wysyłkach wsadowych, gdzie jeden błędny plik może zablokować całą paczkę.

1. 1
   Pobierz i zainstaluj KSeF Guard

   Instalator MSI (~30 MB) lub portable ZIP (bez uprawnień administratora). Dostępne na stronie ksefguard.pl/pl/download.

2. 2
   Przeciągnij pliki XML na okno aplikacji

   Możesz przeciągnąć pojedynczy plik lub cały folder. Aplikacja automatycznie wykryje pliki XML i rozpocznie skanowanie.

3. 3
   Przejrzyj wyniki

   Każdy błąd zawiera: ID reguły, opis problemu (PL + EN), sugestię naprawy, cytat z podstawy prawnej i podgląd źródła XML z podświetlonym elementem.

4. 4
   Eksportuj raport

   Dostępne formaty: TXT, CSV, JSON, PDF. Raport PDF zawiera pełny łańcuch prawny — można go dołączyć do dokumentacji audytowej.

KSeF Guard CLI jest przeznaczony do automatyzacji i integracji z pipeline'ami CI/CD. Działa na Windows i Linux.

ksef-guard validate faktura.xml

ksef-guard validate --format json --output wyniki.json .\faktury\

ksef-guard validate --format pdf --output raport.pdf .\faktury\

ksef-guard validate --preset maximum .\faktury\

CLI zwraca kody wyjścia, które można wykorzystać w skryptach i pipeline'ach CI/CD:

Pełna lista kodów wyjścia dostępna na stronie dokumentacji.

• Brakujące pola P_14_*W (BUS-003) — faktura walutowa bez kwot VAT przeliczonych na PLN
• Niezgodności arytmetyczne (BUS-044) — wartość netto wiersza nie odpowiada iloczynowi ilość × skorygowana cena
• Brak kursu waluty (BUS-006) — faktura walutowa bez kursu przeliczeniowego
• Data przyszła (BUS-030) — data wystawienia ponad 30 dni w przyszłość
• Brak koszyka podsumowania stawki zwolnionej (BUS-088) — stawka “zw” bez koszyka podsumowania P_13_7

KSeF Guard sprawdza 128 aktywnych reguł walidacji wywiedzionych z Ustawy o VAT i Broszury MF. Reguły zawierają udokumentowane źródła odpowiednie do klasy reguły — możesz dokładnie sprawdzić, dlaczego dany błąd jest wykrywany.

KSeF Guard można zintegrować z dowolnym systemem CI/CD. Oto szablon workflow GitHub Actions, który pobiera CLI i waliduje faktury:

- name: Pobierz ksef-guard
  run: |
    curl -fsSL -o ksef-guard.tar.gz \
      "https://www.ksefguard.pl/downloads/ksef-guard-linux-amd64.tar.gz"
    tar -xzf ksef-guard.tar.gz && chmod +x ksef-guard

- name: Waliduj faktury
  run: ./ksef-guard validate --format json --output results.json ./faktury/

Więcej szczegółowych przykładów (GitLab CI, konfiguracja YAML) znajdziesz na stronie dokumentacji.