====== kassensichv.rest ======

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

Cloud-TSE-Anbindung über HTTPS/REST. Unterstützt Fiskaly, Deutsche Fiskal und kompatible APIs. TLS 1.2 mindestens erzwungen. Automatische Retry-Logik bei Server-Fehlern. API-Key wird nie geloggt.

===== Import =====

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

===== Erzeugen =====

<code lyx>
pub fn TseRestNew(configJson: int64): int64;
// configJson: pchar mit JSON-Konfiguration (Pflichtfelder — siehe unten)
// Gibt TseManager-Handle zurück (allokiert)
// Bei fehlenden Pflichtfeldern: success=0 im ersten TseProcessBeleg (code=400)
// Mit TseManagerFree() freigeben
</code>

===== Konfiguration =====

Das JSON-Konfigurationsobjekt wird beim Erstellen des Managers übergeben.

**Pflichtfelder:**

^ Feld ^ Typ ^ Beschreibung ^
| ''api_url'' | string | Basis-URL der TSE-API ohne trailing Slash |
| ''api_key'' | string | Bearer-Token — wird nie geloggt (nur erste 4 Zeichen in Logs) |
| ''client_id'' | string | Kassen-ID beim Cloud-Anbieter |

**Optionale Felder:**

^ Feld ^ Standard ^ Beschreibung ^
| ''connect_timeout_ms'' | 5000 | TCP-Verbindungs-Timeout in Millisekunden |
| ''read_timeout_ms'' | 10000 | Antwort-Timeout (TSE-Signier-Vorgang kann langsam sein) |

===== Beispiel: Fiskaly =====

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

fn main(): int64 {
    var cfg: pchar := concat(
        "{\"api_url\":\"https://kassensichv.io/api/v1\","c,
        "\"api_key\":\"<DEIN-API-KEY>\","c,
        "\"client_id\":\"KASSE-001\"}"c
    );
    var mgr: int64 := TseRestNew(cfg as int64);

    var beleg: BelegDaten;
    beleg.prozessTyp   := PROZESSTYP_KASSENBELEG;
    beleg.kassenNr     := "KASSE-001"c;
    beleg.prozessDaten := "Kaffee;2.50_0.00_0.00_0.00_0.00"c;
    beleg.umsatz       := 250;

    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("Fehler: "c); PrintLn(s.errorMsg as pchar);
    }

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

===== Retry-Verhalten =====

Bei HTTP 503 oder 504 wiederholt der Provider den Request automatisch mit exponentiellem Backoff:

| Versuch | Wartezeit |
|---|---|
| 1 | sofort |
| 2 | 1 Sekunde |
| 3 | 2 Sekunden |
| nach 3 Versuchen | ''ETseConnectionError'' (code=503) |

Bei anderen HTTP-Fehlercodes (400, 401, 404, 500) wird **kein** Retry durchgeführt.

===== TLS-Sicherheit =====

Der REST-Provider erzwingt mindestens **TLS 1.2**. Verbindungen mit älteren Protokollen werden abgelehnt. Dies entspricht der KassenSichV-Anforderung für sichere Kommunikation mit Cloud-TSEs.

===== Unterstützte Provider =====

^ Anbieter ^ api_url ^ Anmerkung ^
| Fiskaly | ''https://kassensichv.io/api/v1'' | Häufigster Cloud-TSE-Anbieter in DE |
| Deutsche Fiskal | ''https://api.fiscal.de/v1'' | BSI-zertifiziert |
| Kompatible APIs | beliebig | Müssen das Fiskaly-REST-Schema implementieren |

===== API-Mapping =====

Intern werden folgende REST-Aufrufe verwendet:

^ Operation ^ HTTP-Methode ^ Pfad ^
| ''TseOpenBeleg'' | POST | ''/tx'' |
| ''TseUpdateBeleg'' | POST | ''/tx/{transId}'' |
| ''TseCloseBeleg'' | POST | ''/tx/{transId}'' (mit state=FINISHED) |
| ''TseExportAuditData'' | GET | ''/export/{client_id}'' |
| ''TseGetStatus'' | GET | ''/status/{client_id}'' |
| ''TseGetSerial'' | GET | ''/tss/{client_id}'' |

Alle Requests tragen den ''Authorization: Bearer {api_key}''-Header. Der API-Key erscheint **nie** in Logs.

===== Wechsel zwischen Sandbox und Produktion =====

<code lyx>
// Entwicklung / Test gegen Fiskaly-Sandbox
var cfgDev: pchar := "{\"api_url\":\"https://kassensichv.io/api/v1\",...}"c;

// Produktion
var cfgProd: pchar := "{\"api_url\":\"https://kassensichv.io/api/v1\",...}"c;
// (gleiche URL, aber mit Produktions-API-Key und tatsächlicher Kassen-ID)
</code>

Fiskaly unterscheidet Sandbox und Produktion über den API-Key, nicht die URL. Andere Anbieter können separate URLs für Test und Produktion haben.

-----

Letzte Aktualisierung: 2026-06-12