KSIDol-Dokumentation > KSIDol-Module > SMS-OTP

Modulanleitung: SMS-OTP

Nicht-technische Anleitung: wofür das Modul dient, wie man es nutzt und wie es mit Dolibarr zusammenspielt.

Online-SignaturPer SMS-Code (OTP)

Betroffene DokumenteAngebote, Bestellungen, Rechnungen, Verträge

KompatibilitätDolibarr 18 bis 24

NachvollziehbarkeitBeweisakte + unveränderliches Protokoll

1. Moduluberblick

Das SMS-OTP Modul (OTP-Signatur) ergänzt Dolibarr um eine verstärkte elektronische Signatur: Beim Online-Unterzeichnen eines Dokuments (Angebot, Bestellung, Rechnung, Vertrag) erhält der Unterzeichner einen Einmalcode (OTP) per SMS auf sein Telefon. Er muss diesen Code eingeben und anschließend seine Einwilligung ausdrücklich bestätigen, bevor der Signaturbereich erscheint. Die Signatur kann somit nur von einer Person geleistet werden, die die SMS tatsächlich auf der erwarteten Nummer erhalten hat, was den rechtlichen Wert der aus der Ferne eingeholten Vereinbarung stärkt. Bei jeder Signatur erstellt das Modul automatisch eine zeitgestempelte Beweisakte (das dem Unterzeichner tatsächlich vorgelegte Dokument, SHA-256-Prüfsumme zur Überprüfung, dass die Datei nicht verändert wurde, IP-Adresse, Browser, Mobilnummer, Einwilligungshinweis) und protokolliert jeden Schritt in einem unveränderlichen Protokoll. Das Modul stützt sich auf die native Online-Signatur von Dolibarr und auf dessen Standardobjekte (Geschäftspartner, Angebote, Bestellungen, Rechnungen, Verträge, Dokumente), ohne den Kern der Anwendung zu verändern: Es leitet den Signaturablauf lediglich auf seine eigene gesicherte Seite um, sofern dies aktiviert ist.

Versendet vor jeder Signatur einen Prüfcode (OTP) per SMS über das OVH SMS-Gateway
Sperrt die Signatur, solange der SMS-Code nicht gültig ist und die Einwilligung nicht bestätigt wurde
Erstellt eine zeitgestempelte Beweisakte mit Integritätsprüfung des Dokuments (SHA-256-Prüfsumme)
Führt ein unveränderliches Signaturprotokoll, das eingesehen, gefiltert und als PDF exportiert werden kann
Aktivierung Dokument für Dokument: Jeder Typ kann bei der nativen Dolibarr-Signatur bleiben oder auf OTP umgestellt werden
Nimmt keine Änderung am Dolibarr-Kern vor: Der native Ablauf bleibt jederzeit verfügbar

2. Durch SMS-Code verstärkte Online-Signatur

Dies ist die zentrale Funktion des Moduls: die Online-Signatur von Dolibarr in eine per SMS geprüfte Signatur zu verwandeln, ohne etwas am Kern der Anwendung zu ändern.

Wenn die Integration aktiviert ist, verweisen die aus einem Dolibarr-Datensatz an den Kunden gesendeten Signaturlinks auf die gesicherte Signaturseite des Moduls statt auf die native Seite
Der Unterzeichner sieht zunächst das Dokument, das tatsächlich berücksichtigt wird, und fordert dann einen Prüfcode per SMS an
Der per SMS erhaltene Code muss eingegeben und bestätigt werden, bevor der weitere Ablauf freigeschaltet wird
Bleibt die Integration inaktiv, verbleibt der Link auf der nativen Signaturseite von Dolibarr, ohne jegliches Eingreifen des Moduls
Es wird kein Code automatisch versendet: Der Unterzeichner löst den Versand selbst aus dem öffentlichen Ablauf heraus aus

3. Signaturablauf des Unterzeichners (gesicherte Seite)

Das Modul führt den Unterzeichner Schritt für Schritt auf einer speziellen öffentlichen Seite, mit mehreren Sicherheitssperren vor der Signatur.

Der Unterzeichner öffnet das vorgelegte Dokument und bestätigt die Mobilnummer, die den Code erhalten soll
Er gibt den per SMS erhaltenen OTP-Code ein; ein abgelaufener oder falscher Code wird abgelehnt und kann erneut gesendet werden (im festgelegten Rahmen)
Sobald der Code bestätigt ist, muss er seine Einwilligung ausdrücklich bestätigen (Kontrollkästchen und rechtlicher Hinweis), bevor der Signaturbereich erscheint
Anschließend wird die Signatur geleistet, das unterzeichnete Dokument und die Beweisakte werden gespeichert
Eine bereits gespeicherte Signatur ist gesperrt: Der Link erlaubt es nicht mehr, dasselbe Dokument erneut zu unterzeichnen (Schutz vor Wiederholung)

4. SMS-Versand und OTP-Parameter

Das Modul steuert den SMS-Versand über ein OVH SMS-Konto und ermöglicht eine feine Anpassung der Nachricht und der Code-Regeln.

Verbindung zum OVH SMS-Gateway (Endpoint, Anwendungsschlüssel, Consumer-Key, Dienst), mit einem Assistenten zur Erzeugung des Schlüssels mit den richtigen Rechten
Anpassbare OTP-Nachrichtenvorlage (automatisches Einfügen des Codes und der Ablaufzeit)
Codelänge (4 bis 10 Ziffern, standardmäßig 6), Gültigkeitsdauer (1 bis 60 Minuten, standardmäßig 10) und maximale Anzahl erneuter Versendungen sind konfigurierbar
Versandeinstellungen: Standardabsender, Priorität, Nachrichtentyp (transaktional/Marketing), Verzögerung vor dem Versand, STOP-Klausel
Verwaltung der Ländervorwahl (automatisches Hinzufügen, Erzwingen einer Standardvorwahl oder keine Aktion) und Testmodus
Übernahme der bestehenden Einstellungen des SMS-Versandmoduls (Beibehaltung der bereits vorhandenen Parameter)

5. SMS-Kontingente und Verbrauchsüberwachung

Das Modul ermöglicht die Kontrolle der SMS-Ausgaben durch die Zuweisung von Kontingenten und die Überwachung des verfügbaren Bestands.

Zuweisung eines SMS-Kontingents pro Benutzer, mit Verfolgung der zugewiesenen, verbrauchten und verfügbaren Anzahl
Anzeige eines Badges mit der Anzahl der für den Benutzer verbleibenden SMS
Warnung bei geringem Bestand (Badge am oberen Bildschirmrand und Warnkarte), sobald der Schwellenwert erreicht ist
Konfigurierbarer Nachbestell-Link zum Bestellen neuer SMS
Anzeige des verfügbaren Guthabens auf dem OVH-Konto

6. Beweisakte und Integritätsprüfung

Jede Signatur erzeugt automatisch eine Reihe von Beweisen, die im Streitfall die Gültigkeit der Vereinbarung belegen sollen.

Speicherung des exakt dem Unterzeichner vorgelegten Dokuments (eingefrorene Datei) und des unterzeichneten Dokuments
Berechnung einer SHA-256-Prüfsumme, mit der überprüft werden kann, dass das Dokument vor oder nach der Signatur nicht verändert wurde
Erstellung eines Beweis-PDFs (zeitgestempelte Beweisakte), das die technischen Elemente der Signatur enthält
Erstellung eines herunterladbaren Beweisarchivs, das die Dokumente, das Manifest und die Beweise zusammenfasst
Je nach Konfiguration erfasste Elemente: Datum und Uhrzeit (UTC), IP-Adresse, Browser, Mobilnummer, Sicherheitsschlüssel, Dokumentenprüfsumme und Einwilligungshinweis

7. Beweistresor (Aufbewahrungseinstellungen)

Ein spezieller Reiter ermöglicht es, die Regeln für die Archivierung und Aufbewahrung der Beweise an Ihre Compliance-Anforderungen anzupassen.

Auswahl des Tresor-Modus und des Hash-Algorithmus (standardmäßig SHA-256)
Konfigurierbare Aufbewahrungsdauer der Beweise (in Jahren)
Festlegung eines Compliance-Bereichs (z. B. FR/EU) und eines dem Unterzeichner vorgelegten rechtlichen Hinweises
Aktivierung oder Deaktivierung der Erfassung der IP-Adresse und des Browsers des Unterzeichners
Option für ein Nur-Anhängen-Protokoll (append-only), um jede Veränderung der Einträge zu verhindern

8. Protokoll und Signaturverlauf

Ein Reiter Verlauf fasst alle Signaturereignisse in einem einsehbaren und unveränderlichen Protokoll zusammen.

Zeitgestempelte Liste jedes Schritts: Öffnen des Links, Bestätigung der Nummer, Versand und Bestätigung des Codes, Einwilligung, erfasste Signatur, Archivierung oder Fehler
Suche und Filter nach Datum, Signatur, Geschäftspartner, Dokumententyp, Ereignis, Status, Referenz, IP-Adresse oder Detail
Sortierung und Paginierung der Einträge
Direkter Download des Beweis-PDFs, des unterzeichneten PDFs und des Beweisarchivs aus der Liste
Verkettung der Ereignisse (aufeinanderfolgende Prüfsummen), die die Unveränderlichkeit des Protokolls gewährleistet, ohne den Dolibarr-Kern zu verändern

9. Auswahl nach Dokumententyp und Diagnose

Das Modul lässt sich fein steuern, Dokumententyp für Dokumententyp, mit integrierten Prüfwerkzeugen.

Für jeden Typ (Angebot, Vertrag, Interventionsbericht, Bestellung, Rechnung) Auswahl zwischen Bearbeitung durch SMS-OTP oder nativer Dolibarr-Signatur
Der Interventionsbericht wird beispielsweise für eine Signatur vor Ort in nativer Form empfohlen
Diagnose-Schaltfläche zur Überprüfung des Endpoints, der Zugangsdaten, des Dienstes, des Zugriffs auf die OVH-API und des Vorhandenseins der erforderlichen Tabellen
Werkzeug zum Zurücksetzen des Moduls (Löschung der SMS-Daten und -Protokolle) nach Bestätigung
Globale Aktivierung der Integration in die native Online-Signatur, jederzeit aktivierbar/deaktivierbar

10. Verknupfungen mit Dolibarr

Das Modul arbeitet nicht isoliert: Es ist mit den nativen Bausteinen von Dolibarr verzahnt.

Angebote, Bestellungen, Rechnungen, Verträge : Das Modul greift auf die Datensätze von Angeboten, Bestellungen, Rechnungen und Verträgen in Dolibarr zu. Der für diese Dokumente erzeugte Online-Signaturlink wird auf den OTP-Ablauf des Moduls umgeleitet, wenn der betreffende Typ für die OTP-Bearbeitung konfiguriert ist.
Native Online-Signatur von Dolibarr : Das Modul stützt sich auf den standardmäßigen Online-Signaturmechanismus von Dolibarr und auf dessen Sicherheitsschlüssel. Es ersetzt lediglich die Adresse des Signaturlinks (durch Substitution), ohne den Kern zu verändern: Ist die Integration deaktiviert, bleibt der native Ablauf voll funktionsfähig.
Geschäftspartner und Kontakte : Das Modul übernimmt den Namen des Geschäftspartners und die dem Dokument zugeordnete Telefonnummer des Unterzeichners für den Versand der SMS und die Anzeige im Protokoll. Die Mobilnummer kann während des Signaturablaufs bestätigt oder korrigiert werden.
Dokumente (Dolibarr-Dateien) : Das vorgelegte Dokument, das unterzeichnete Dokument und das Beweisarchiv werden im Dokumentenbereich von Dolibarr in einem dem Modul gewidmeten Verzeichnis gespeichert und bleiben aus dem Verlauf herunterladbar.
Benutzer und Zugriffsrechte : Das Modul stützt sich für die SMS-Kontingente auf die Benutzerkonten von Dolibarr und für den Zugriff auf die Konfiguration und den Verlauf auf die Rechte (Lesen, Schreiben, Administration). Der Zugriff auf die Konfiguration ist Administratoren vorbehalten.
Validierungsereignisse (Auslöser) : Das Modul reagiert auf die Standardereignisse von Dolibarr an Dokumenten (Validierung eines Angebots, einer Bestellung oder einer Rechnung, Signatur eines Vorschlags, Änderung eines Vertrags), um die Konsistenz des Signaturablaufs aufrechtzuerhalten.