Dokumentacja

Wszystko, czego potrzebujesz, aby zintegrować KSeF Guard ze swoim workflow.

Kody zakończenia

KSeF Guard używa następujących kodów zakończenia:

Kod	Znaczenie	Akcja CI
0	Wszystkie pliki PASS (XSD poprawne + zgodne z regułami)	Pipeline przechodzi
1	Jeden lub więcej plików ma błędy walidacji XSD	Pipeline nie przechodzi
2	Jeden lub więcej plików ma błędy zgodności merytorycznej	Pipeline nie przechodzi
10	Nieprawidłowe argumenty lub brakujące flagi	Popraw polecenie
11	Błąd weryfikacji sumy kontrolnej schematu	Zainstaluj ponownie lub zweryfikuj binarkę
12	Błąd I/O pliku (nie znaleziono, brak uprawnień, przekroczono limit rozmiaru)	Sprawdź ścieżki plików i uprawnienia
13	Osiągnięto limit licencji/planu	Sprawdź licencję lub ulepsz plan
130	Przerwane sygnałem (SIGINT/SIGTERM)	Walidacja anulowana — uruchom ponownie

Gdy występuje wiele typów błędów, zwracany jest kod o najwyższym priorytecie. Priorytet: Schema (11) > Licencja (13) > IO (12) > XSD (1) > Merytoryczny (2).

Zalecana konfiguracja

Używaj --format summary dla szybkiego wyniku w logach, --format json --output results.json do archiwizacji.
Plan Pro zalecany dla CI/CD (bez limitów na skany, wsparcie YAML).
Aktywuj licencję przed pierwszym użyciem: ksef-guard license activate --key TWÓJ_KLUCZ (powiązane z maszyną, przechowywane lokalnie).

Użycie CLI

Typowe polecenia walidacji:

# Walidacja pojedynczego pliku

ksef-guard validate faktura.xml

# Walidacja katalogu z fakturami XML

ksef-guard validate .\faktury\

# Wyjście JSON do archiwizacji artefaktów

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

# Podsumowanie do logów CI

ksef-guard validate --format summary .\faktury\

# Eksport CSV

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

# Raport PDF (Standard+)

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

# Z presetem reguł

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

# Z konfiguracją YAML (Pro)

ksef-guard validate --config .ksef-guard.yml .\faktury\

# Generuj PDF z istniejących wyników JSON (Standard+)

ksef-guard render-pdf --input wyniki.json --output raport.pdf

# Aktywuj licencję

ksef-guard license activate --key TWÓJ_KLUCZ

# Sprawdź status licencji

ksef-guard license status --json

# Dezaktywuj licencję (odwiąż maszynę)

ksef-guard license deactivate

# Lista wszystkich reguł walidacji

ksef-guard --list-rules

# Lista reguł jako JSON (do narzędzi)

ksef-guard --list-rules --format json

# Wymaż wszystkie lokalne dane (licencja, historia, konfiguracja)

ksef-guard --erase-all-data --yes

Macierz funkcji wg planu

Funkcje CLI dostępne na każdym planie:

Funkcja	Darmowy	Standard+	Pro
Formaty	text, summary	text, summary, csv, json, pdf	Wszystkie formaty
--output	Nie (tylko stdout)	Tak (--output)	Tak (--output)
Konfiguracja reguł	Tylko domyślne	Włącz/wyłącz reguły flagami CLI	Konfiguracja YAML + flagi CLI
PDF	—	Standardowa marka	White-label (własne logo/nagłówek)
Dzienny limit	10 plików/dzień	5 000 plików/dzień	Bez limitu

Plik konfiguracji

Utwórz plik .ksef-guard.yml w katalogu głównym projektu (wymaga planu Pro):

preset: recommended
rules:
  KSEF-BUS-030: warning
  KSEF-BUS-197: off

Presety

Wbudowane presety walidacji kontrolują aktywne reguły:

Preset	Aktywne reguły	Ostrzeżenia wpływają na kod wyjścia?
essential	Tylko GOV_MANDATED	Nie
recommended	Wszystkie aktywne reguły	Nie (domyślnie)
maximum	Wszystkie aktywne reguły	Tak (kod wyjścia 2)

GitHub Actions

Dodaj ten workflow do .github/workflows/ksef-validate.yml:

Wyjście JSON, --output i aktywacja licencji wymagają planu Standard lub Pro.

name: KSeF Validation
on:
  push:
    paths:
      - 'invoices/**/*.xml'
  pull_request:
    paths:
      - 'invoices/**/*.xml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download 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: Activate license (Standard/Pro)
        run: ./ksef-guard license activate --key ${{ secrets.KSEF_GUARD_LICENSE_KEY }}

      - name: Validate invoices
        run: |
          ./ksef-guard validate \
            --format json \
            --output results.json \
            ./invoices/

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: ksef-validation-results
          path: results.json
          retention-days: 30

GitLab CI

Dodaj to zadanie do .gitlab-ci.yml:

Wyjście JSON, --output i aktywacja licencji wymagają planu Standard lub Pro.

ksef-validate:
  stage: validate
  image: ubuntu:latest
  before_script:
    - apt-get update -qq && apt-get install -y -qq curl
    - 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
    - ./ksef-guard license activate --key ${KSEF_GUARD_LICENSE_KEY}
  script:
    - ./ksef-guard validate
        --format json
        --output results.json
        ./invoices/
  artifacts:
    when: always
    paths:
      - results.json
    expire_in: 30 days
  rules:
    - changes:
        - invoices/**/*.xml

Wskazówki

Uruchom 'ksef-guard license activate --key TWÓJ_KLUCZ' raz na każdym CI runnerze, aby powiązać licencję z tą maszyną.
Używaj --format json --output results.json i uploaduj jako artefakt builda.
Wyjście --format summary jest kompaktowe i idealne do logów CI.
Połącz z --preset maximum lub --warnings-as-errors dla ściślejszych kontroli.
Walidacja KSeF Guard działa offline �� brak wywołań sieciowych podczas walidacji. Aktywacja licencji i aktualizacje mogą wymagać połączenia.