Konzepte

Was eine Sitzung, eine Beweis-Zeile und eine Audit-Kette wirklich sind, in möglichst wenigen Worten. Lesen Sie dies einmal, und die API-Referenz wird Sinn ergeben.

Organisation

Der Tenant auf oberster Ebene. Eine Organisation entspricht einem Kundenkonto. Jede andere Ressource (Sitzungen, Beweise, Audit-Events, Nutzer) ist über Row-Level Security auf den zugrunde liegenden Postgres-Tabellen an eine Organisation gebunden. Ein Bug im Anwendungscode kann keine Tenant-Grenze überschreiten — die Datenbank verweigert die Abfrage.

Eine Organisation hat: Mitglieder (Nutzer mit rollenbasiertem Zugriff), Branding (Logo / Farben / PDF-Fußzeile), ein Abrechnungsabonnement, optionale KYB-Rechtsträgerdaten, optionale SSO-Konfiguration und eine Aufbewahrungsrichtlinie.

Mitglied, Rolle, Berechtigung

Ein Mitgliedschaft ist die Verknüpfung zwischen einem Nutzer und einer Organisation. Ein Nutzer kann Mitgliedschaften in mehreren Organisationen halten und zwischen ihnen wechseln (die aktive Organisation wird als JWT-Claim mitgeführt).

Jede Organisation legt bei der Erstellung vier Systemrollen an:

org_admin — volle Kontrolle. Abrechnung, Mitglieder, Branding, Aufbewahrung.
inspector — kann Inspektionen durchführen, Beweise erfassen, Berichte signieren.
observer — schreibgeschützter Zugriff auf Sitzungen + Audit-Daten.
auditor — schreibgeschützter Zugriff plus Berechtigung zur Ketten-Verifikation.

Org-Admins können benutzerdefinierte Rollen erstellen, indem sie den Berechtigungskatalog zusammenstellen. Berechtigungen werden auf der View-Ebene per Slug geprüft + auf der DB-Ebene durch RLS gegengeprüft.

Sitzung

Eine Inspektion. Die Abrechnungseinheit (Sie zahlen pro abgeschlossener Sitzung) und die Beweiseinheit (eine Audit-Kette gilt pro Sitzung, nicht pro Organisation).

Eine Sitzung hat: einen Operator (Ihr Teammitglied, das sie gestartet hat), einen oder mehrere Teilnehmer (den Außendienst-Nutzer plus optionale Beobachter), Einwilligungsstatus, optionale GPS-Position, optionale Notizen, eine Audit-Kette und — nach dem Schließen — TSA-verankerte Zeitstempel-Token.

Teilnehmer

Eine Person in einer Sitzung. Es gibt einen Operator pro Sitzung und mindestens einen Außendienst-Nutzer; optionale zusätzliche Beobachter werden unterstützt. Außendienst-Nutzer treten über eine einmalig nutzbare signierte URL bei (kein Konto erforderlich); Operatoren + Beobachter sind Mitglieder der Organisation.

Beweis

Ein während einer Sitzung erfasstes Beweisstück. Arten:

snapshot — Standbild von der Kamera des Außendienst-Nutzers.
annotation — Zeichnung, die über einen Snapshot oder ein Whiteboard gelegt wird.
whiteboard — Excalidraw-Leinwand aus der Sitzung, exportiert als PNG + State.
clip — kurzes Videosegment.
document — hochgeladene Datei (von der Chat-Ebene für PDF-zur-Signatur verwendet).

Jede Beweis-Zeile hat einen SHA-256 ihres Binärinhalts, gespeichert in der Audit-Kette. Eine nachträgliche Manipulation der Datei lässt die Verifikation scheitern.

Audit-Kette

Das kryptografische Rückgrat. Jedes Event in einer Sitzung — Sitzungserstellung, Einwilligungserteilung, GPS-Aufzeichnung, Beweiserfassung, Annotation, Whiteboard-Speicherung, Signatur, Sitzungsende — erzeugt eine AuditEvent -Zeile mit:

{
  "session": "<uuid>",
  "sequence": N,
  "occurred_at": "<iso8601>",
  "kind": "evidence.snapshot_added",
  "actor": { "user": <id|null>, "participant": <id|null> },
  "payload": { /* event-specific */ },
  "prev_hash": "<sha256 of previous event>",
  "hash": "<sha256 of canonical_json of this event>"
}

Das erste Event verwendet prev_hash = "0" * 64 (Genesis). Jedes nachfolgende Event verwendet den Hash des vorherigen Events als prev_hash und erhöht sequence um 1. Ein Postgres-Advisory-Lock serialisiert Schreibvorgänge pro Sitzung; ein Append-only-Trigger blockiert UPDATE + DELETE auf der Tabelle.

TimestampToken (TSA-Anker)

Am Sitzungsende (und bei operatorausgelöstem „Jetzt stempeln“) wird der aktuelle Kettenkopf an drei unabhängige Zeitstempelautoritäten übermittelt:

YodaLedger — Tezos-Blockchain-Anker. ~15–20 Minuten Finalität. Asynchron; wir erhalten einen Callback, wenn der Block bestätigt ist.
FreeTSA — RFC-3161-Zeitstempel. Synchron; Token wird sofort zurückgegeben. Austauschbar gegen einen kostenpflichtigen QTSP (DataSure) für eIDAS-Art.-42-Konformität.
OpenTimestamps — Bitcoin-Anker über das OpenTimestamps-Kalenderprotokoll. Asynchron; der Upgrade-Pfad läuft über einen Celery-Sweep.

Drei ist Absicht — verschwindet eine TSA, verankern die anderen beiden die Kette weiterhin. Ein Prüfer kann unabhängig gegen jede von ihnen verifizieren, mithilfe öffentlicher Block-Explorer / Verify-Endpunkte.

Signatur (SES / AES / QES)

Drei eIDAS-Stufen, alle auf demselben Audit-Bericht-PDF:

SES (Einfache elektronische Signatur) — audit-ketten-gestützt, kein Signaturzertifikat. Geeignet für interne Aufzeichnungen.
AES (Fortgeschrittene elektronische Signatur) — identitätsgebundenes Signaturzertifikat, PAdES-B-T-verankert. Geeignet für die meisten B2B-Verträge.
QES (Qualifizierte elektronische Signatur) — höchste eIDAS-Stufe, rechtlich einer handschriftlichen Unterschrift in der gesamten EU gleichgestellt. Gekoppelt an die KYB-Prüfung der ausstellenden Organisation.

Kampagne (optional)

Eine logische Gruppierung von Sitzungen für gebündeltes Reporting — „Kfz-Schäden Q2 2026“ oder „Übergabemängel Standort A“. Sitzungen erfordern keine Kampagne; es ist eine Reporting-Hilfe.

Webhook

Eine vom Kunden registrierte URL, die HMAC-signierte Event-POSTs empfängt. Event-Typen: session.created, session.completed, participant.joined, participant.left, evidence.added, recording.ready, audit.anchored, signature.completed, plus ein webhook.test zur Zustellverifikation.

Signatur: Stripe-artiger t=...,v1=... -Header mit HMAC-SHA256 über <timestamp>.<body>. Der constructEvent() -Helper des SDK verifiziert in konstanter Zeit mit einer 5-minütigen Clock-Skew-Toleranz.