[POST] /jobs/{jobId}/intents/sign – das Signatur-HowTo

Worum könnte es in einem Artikel mit solch einem Titel gehen? Um die nächste Job-Aggregation-API? Wer auf das Wort „sign“ getippt hat, lag schon richtig: Es geht um elektronische Signaturen. In diesem Artikel zeigen wir (kurz), wie Unternehmen im Finanzsektor auf konkrete Nutzungsfälle kommen und wie die zuständigen Informatiker eine elektronische Signaturlösung mittels REST-API einfach und ohne großen Aufwand einbinden können.

von Diplom-Ingenieur Valerio Neri, FP Sign

Um eines hier gleich vorwegzunehmen: Die Integration einer Lösung für elektronische Signaturen ist weder kompliziert, noch braucht sie monatelange Planung und Umsetzung.

Sicherlich wird ein solches Vorhaben nicht nur getrieben, weil es toll ist, mit REST-APIs zu arbeiten: Es muss ein konkreter Use Case vorliegen, der den Einsatz von elektronischen Signaturen im Bank- und Finanzsektor sinnvoll macht. Weniger sinnvoll ist es beispielsweise, eine Signaturlösung zu integrieren und erst dann einen passenden Use Case zu finden.  (Anm.: Eine ähnliche Diskussion sollte es auch beim Einsatz von Blockchain geben).

Use Cases für integrierte elektronische Signaturlösungen

Was sind jedoch geeignete Use Cases für den Einsatz von integrierbaren E-Signatur-Lösungen? Fangen wir bei den Gründen an:

1. Ein papierbasierter Prozess ist zu kostenintensiv oder ist durch neue Richtlinien nicht mehr praktisch durchführbar.
2. Die internen oder externen Anforderungen an einen bereits digitalisierten Prozess steigen (Beispiel: Feststellung der Identität eines Nutzers bzw. Vorgabe zur Nutzung einer qualifizierten elektronischen Signatur).

Die Use Cases haben somit grundsätzlich folgende Gemeinsamkeiten:

1. Medienbrüche sollen vermieden werden
– Zwischen IT und Papier
– Zwischen Papier und Papier

2. Freigabeprozesse sollen effizienter gestaltet werden
– Intern
– Extern
– Hybrid

3. Verträge sollen in Echtzeit angepasst oder grundsätzlich nur noch digital abgeschlossen werden (z. B. aufgrund neuer Richtlinien im Finanzsektor)
4. Zeitfaktor – Deadlines sollen besser eingehalten werden oder es wird eine schnellere Reaktionszeit bei der Unterzeichnung von Dokumenten verlangt
5. Kosten sollen optimiert werden

Projektplanung für einen PoC der E-Signatur

Mit einem Proof-Of-Concept (PoC) lassen sich Nutzungsfälle bzw. Use Cases für die elektronische Signatur mit wenig Aufwand und Kosten testen. Im Falle der Implementierung der E-Signatur in die Unternehmens-Workflows kann der Proof-of-Concept etwa mithilfe folgender Vorgehensweise umgesetzt werden:

Die wichtigsten Aussagen aus dieser beispielhaften Projektübersicht:

1. „Scheitern“ muss über Erfolgsfaktoren definiert werden
– Nur weil ein Projekt nicht klappt, ist nicht der komplette Ansatz falsch.
– Neubewerten, Ziele prüfen, Use Case prüfen
2. Iterative Vorgehensweise
– Man kann nicht alles definieren.
– Klare Ziele, enge Abstimmung, schnelle Schritte
3. Auftragnehmer beauftragen
– PoCs haben einen Wert, es muss ein Win-Win vorhanden sein.
– Man soll auch die Freiheit haben, nach dem PoC „danke und tschüss“ sagen zu können.
4. Fokus und Lessons-Learned
– Kleines Team, das den Fokus bestimmt und ausreichend Zeit bekommt.
– PoC-Ergebnisse knapp zusammenfassen (mehr Action-Items als Dokumentation).
– „Fuel“ für nächste Projekte: Gleich noch einen PoC umsetzen, als Erweiterung oder für andere Use Cases.

Integration mittels der REST-API

Nachdem die Use Cases für den Einsatz der elektronischen Signatur definiert wurden und die Entscheidung für die Implementierung getroffen wurde, kommt es zur eigentlichen Integration in die bestehende IT-Infrastruktur – mittels einer REST-API. Wir gehen jetzt davon aus, dass wir in der elektronischen Signaturlösung einen „technischen“ Benutzer definiert haben, der mit entsprechenden Rechten ausgestattet ist, um die API-Endpunkte aufrufen zu können.

Die wichtigsten Schritte der E-Signatur-Lösung mithilfe einer solchen API zeigen wir am Beispiel einer Postman-Konfiguration unseres Kollegen Stefan Boschulte. Wir werden uns hier auf die Aufrufe „login“, „create workflow intent“ und „add participant“ konzentrieren:

1) Login

Als erstes loggen wir den „technischen“ Benutzer ein. Hier könnten auch die Anmeldedaten eines „normalen“ Benutzers verwendet werden. Es empfiehlt sich jedoch immer eine Trennung vorzunehmen und für die API-Nutzung speziell eingerichtete Nutzerkonten zu verwenden.

Der /login Endpunkt erwartet hier den Benutzernamen und das Passwort. Die Parameter müssen im Body als JSON-String übergeben werden.

Als Antwort erhalten wir Informationen zu dem Benutzer und, was noch wichtiger ist, einen Authentication Token (Bearer Token) mit dem wir uns für die weiteren Aufrufe gegenüber der API authentifizieren. Die Antwort, die ebenfalls als JSON zurückkommt, sollte in ein Objekt konvertiert werden, um die Attribute weiter verwenden zu können.

Für die C#-Programmierer: Ja, es könnte hier auch eine Klasse für den Rückgabewert definiert werden. Der Einfachheit halber haben wir das hier weggelassen.

Bei dieser API wird auch die Tenant-ID (ID des zugehörigen Mandanten) zurückgegeben. Diese wird bei den weiteren API-Aufrufen als Header ebenfalls erwartet, um den Kontext des Aufrufs darzustellen. Ein Benutzer kann nämlich mehreren Mandanten zugeordnet sein und pro Mandant entsprechend unterschiedliche Rollen und Rechte besitzen.

2) Weitere Aufrufe vorbereiten

Für die weiteren API-Aufrufe müssen wir also sowohl den Bearer Token als auch die Tenant-ID mitgeben. Hierfür kann man die generischen Calls erst einmal kapseln:

3) Workflow anlegen

Ein „Workflow“ in der Welt der E-Signatur ist ein Signaturvorgang, bei dem ein digitales Dokument in die entsprechende Anwendung hochgeladen und an einen oder mehrere Empfänger zum Freigeben und/oder unterschreiben versendet wird.

Beispiel für Aktionen, die ein Signaturempfänger bzw. Gegenzeichner durchführen kann:

1. Lesebestätigung (ohne Unterschrift)
2. Unterschreiben (fortgeschrittene Signatur)
3. Unterschreiben mittels einer QES (qualifizierte elektronische Signatur)
4. Lediglich zur Information (ohne Bestätigung/Aktion)

Zusätzlich kann angegeben werden, ob ein Empfänger ein PDF-Formular ausfüllen soll.

Der Endpunkt sieht wie folgt aus:

 

An dieser Stelle muss erklärt werden, dass erst ein „Intent“ angelegt wird und darauf ein „Workflow“ instanziiert wird. Damit lassen sich Intents zwischenspeichern, ohne die Workflows zu starten. Die angegebenen Parameter decken folgende Punkte ab:

1. Kommentar: Beschreibung, die allen Beteiligten gesendet und angezeigt wird.
2. Delegable: Ist der Workflow delegierbar? Kann ein Signaturempfänger die Anfrage an einen anderen Empfänger weiterleiten?
3. Notification: Wer soll bei Abschluss des Signaturprozesses informiert werden? Nur der Signaturabsender oder alle Beteiligten?
4. Document: Das zu unterschreibende Dokument

Durch diesen Aufruf wird ein „Intent“ (eine Vorlage) angelegt und eine Intent-ID zurückgegeben. Auf deren Basis kann ein Workflow erzeugt werden. Bevor wir das tun, müssen wir noch weitere Teilnehmer hinzufügen.

4) Teilnehmer einem Workflow hinzufügen

Die hier erfragte {id} ist die von der im vorigen Schritt erstellten Vorlage. An dieser Stelle sind folgende Parameter gefragt:

1. Kommentar: Persönlicher Kommentar für den einen Beteiligten.
2. Participant: Enthält alle Informationen zu dem Empfänger. Wenn der Empfänger nicht existiert, kann er über die Signatureinstellung angelegt werden.
3. SignatureSetting: Hier wird eingestellt, welche Aktion der Empfänger durchführen muss (unterschreiben, bestätigen, lediglich zur Information erhalten). An dieser Stelle kann auch eingestellt werden, ob der Empfänger ein Konto braucht, um auf die Anfrage zugreifen zu können, oder ob der versendete Link ohne Anmeldung nutzbar ist (häufiger im B2C-Umfeld).
4. SignaturePresets: Hier können mehrere Unterschriftspositionen eingestellt werden, an denen die Unterschrift des Empfängers gesetzt wird. Dabei können die Seite und die Position angegeben werden. Wird dieser Parameter nicht gesetzt, kann der Empfänger frei entscheiden, wo und wie oft er seine Unterschrift setzt.

5) Den Workflow starten

Anhand der Intent-ID aus den vorherigen Schritten, kann der Workflow gestartet werden. Beim Starten wird noch angegeben, ob der Signaturersteller selbst zu Beginn ebenfalls eine Unterschrift setzt oder ob lediglich die Empfänger eine Aktion durchführen sollen.

Für diesen Aufruf wird die Intent-ID in den Request Body geschrieben. Folgende Parameter werden noch erwartet:

– OriginatorJob
– Die Aktion des Erstellers (keine Aktion, fortgeschrittene oder qualifizierte elektronische Signatur)
– Die „visuelle“ Unterschrift und die Positionen

Zusammenfassung

Über den Endpunkt für das Login haben wir einen Bearer Token und eine Tenant-ID erhalten. Beide Werte benötigen wir, um authentifiziert die anderen API-Funktionen aufzurufen. Als ersten haben wir den Workflow vorbereitet, indem wir einen Intent mit dem entsprechenden Dokument angelegt haben. Im weiteren Schritt haben wir zu dem Intent die Empfänger inkl. der jeweiligen Signatureinstellungen hinzugefügt. Zuletzt haben wir den Workflow gestartet. Nach dem Start übernimmt die E-Signatur-Anwendung die Verteilung von den Anfragen per E-Mail (wahlweise per SMS). Mit jeder getätigten elektronischen Unterschrift wird der Prozess automatisch fortgeführt. Über die API können der Status des Prozesses überprüft und das Ergebnis des Workflows abgerufen werden.

Was nun?

1) „You often need to get your own hands dirty bottom-up, before you can understand things top-down“. Die klare Empfehlung hier ist, einfach loszulegen:

1. Elektronische Signaturlösung je nach geplanten Use Cases auf dem Markt aussuchen
2. Sich mit der API vertraut machen
3. Onboarding Webinar zur API mit dem Anbieter der elektronischen Signaturlösung durchführen
4. Ausprobieren

2) Wenn man einen ersten Eindruck gewonnen hat, kann etwa nach dem weiter oben beschriebenen Projektplan ein Proof-of-Concept aufgesetzt werden.

3) Nach dem PoC kann entschieden werden, den Fokus mit weiteren PoCs zu schärfen oder gleich die Einführung zu starten.

Fazit

Wir haben gesehen, dass das Anbinden einer elektronischen Signaturlösung mittels REST-API nicht kompliziert ist und innerhalb kürzester Zeit ausprobiert werden kann. Dabei ist die Zieldefinition eine der wichtigsten Voraussetzungen für die nahtlose Implementierung: Man braucht kein Riesenprojekt starten, aber eine klare Zielstellung für den ersten PoC, um den Ball ins Rollen zu bringen.Diplom-Ingenieur Valerio Neri, FP Sign