Inhaltsverzeichnis

kassensichv.rest

→ 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

import kassensichv.types;
import kassensichv.rest;
import kassensichv.manager;

Erzeugen

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

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

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;
}

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

// 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)

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