====== kassensichv.file ======

→ [[lyx_-_programmiersprache:units:kassensichv|Zurück zur KassenSichV-Übersicht]]

USB-TSE-Anbindung über das lokale Dateisystem. Unterstützt Swissbit, Epson und andere Hardware-TSEs, die über ein Dateiprotokoll kommunizieren. Kein Vendor-SDK erforderlich.

**Protokoll:** Der Provider schreibt Request-Dateien auf den TSE-Mount-Punkt, wartet auf Response-Dateien (Poll alle 100 ms), liest die Antwort und löscht beide Dateien.

===== Import =====

<code lyx>
import kassensichv.types;
import kassensichv.file;
import kassensichv.manager;
</code>

===== Erzeugen =====

<code lyx>
pub fn TseFileNew(configJson: int64): int64;
// configJson: pchar mit JSON-Konfiguration (Pflichtfeld: base_path)
// Gibt TseManager-Handle zurück (allokiert)
// Mit TseManagerFree() freigeben
</code>

===== Konfiguration =====

**Pflichtfeld:**

^ Feld ^ Typ ^ Beschreibung ^
| ''base_path'' | string | Pfad zum USB-TSE-Mount-Punkt (z.B. ''/mnt/tse'' oder ''E:\'') |

**Optionale Felder:**

^ Feld ^ Standard ^ Beschreibung ^
| ''timeout_ms'' | 5000 | Maximale Wartezeit auf TSE-Antwort in Millisekunden |
| ''poll_ms'' | 100 | Intervall zwischen Datei-Checks in Millisekunden |

===== Beispiel: Swissbit-USB-Stick =====

<code lyx>
import kassensichv.types;
import kassensichv.file;
import kassensichv.manager;

fn main(): int64 {
    var cfg: pchar := "{\"base_path\":\"/mnt/tse\",\"timeout_ms\":5000}"c;
    var mgr: int64 := TseFileNew(cfg as int64);

    var beleg: BelegDaten;
    beleg.prozessTyp   := PROZESSTYP_KASSENBELEG;
    beleg.kassenNr     := "KASSE-001"c;
    beleg.prozessDaten := "Artikel;9.90_0.00_0.00_0.00_0.00"c;
    beleg.umsatz       := 990;

    var sig: int64 := TseProcessBeleg(mgr, addr beleg);
    var s: SigErgebnis := (sig as *SigErgebnis)^;

    if s.success == 1 then {
        PrintLn(s.qrCode as pchar);
    } else {
        Print("TSE-Fehler: "c); PrintLn(s.errorMsg as pchar);
    }

    SigErgebnisFree(sig);
    TseManagerFree(mgr);
    return 0;
}
</code>

===== Dateiprot okoll =====

Der Provider kommuniziert über JSON-Dateien auf dem TSE-Mount-Punkt:

**Request-Datei:** ''{base_path}/{TransId}_req.json''
<code json>
{
  "trans_id": "TX-20260612093045123",
  "process_type": "Kassenbeleg-V1",
  "process_data": "Kaffee;2.50_0.00_0.00_0.00_0.00",
  "state": "FINISHED"
}
</code>

**Response-Datei:** ''{base_path}/{TransId}_res.json'' (von der TSE geschrieben)
<code json>
{
  "tse_serial": "SWB-0123456789ABCDEF",
  "signature_counter": 42,
  "transaction_counter": 42,
  "signature_value": "MEQCIBaXyz..."
}
</code>

Nach erfolgreichem Lesen der Response werden **beide Dateien automatisch gelöscht** — keine manuelle Aufräumung nötig.

===== Timeout-Verhalten =====

Wenn die TSE die Response-Datei nicht innerhalb von ''timeout_ms'' schreibt:
  * ''TseProcessBeleg'' gibt ''success=0'' zurück mit ''errorMsg'' "Timeout" und code=408
  * Die Request-Datei bleibt auf dem TSE-Mount-Punkt liegen (TSE verarbeitet noch)
  * **Compliance-Problem:** Die TSE-Transaktion kann noch offen sein — Kassensoftware muss dies erkennen und behandeln

Bei wiederhergestellter Verbindung den Status über ''TseGetStatus'' prüfen.

===== Mount-Punkt einrichten =====

Unter Linux muss der USB-TSE-Stick gemountet sein. Typisches Setup:

<code bash>
# USB-Stick als TSE-Mount einrichten
sudo mount /dev/sdb1 /mnt/tse

# Oder via /etc/fstab für dauerhaften Mount
UUID=xxx-yyy  /mnt/tse  vfat  auto,user,rw  0 0
</code>

Seriennummer der TSE liegt in ''{base_path}/tse_serial.txt'' — wird beim ersten ''TseGetSerial'' gelesen.

===== Unterstützte Hardware =====

^ Hersteller ^ Modell ^ Anmerkung ^
| Swissbit | TSE-Stick (USB) | Weit verbreitet, FIFO-Dateiprotokoll |
| Epson | TSE-Stick (USB) | Ähnliches Dateiprotokoll |
| Generisch | beliebig | Jede Hardware, die das JSON-Request/Response-Protokoll implementiert |

**Wichtig:** Das konkrete Dateiformat kann je nach Hersteller leicht abweichen. ''kassensichv.file'' setzt die in der Bibliothek dokumentierte Format-Variante voraus. Bei abweichenden Formaten die Konfiguration des Herstellers prüfen.

-----

Letzte Aktualisierung: 2026-06-12