Erste Schritte (Postman Collection)

Mit der bereitgestellten Postman Collection können erste Schritte zur Integration der signoSign/Universal REST API durchgeführt werden.

Vorbereitung

Grundlage für die Demo sind die Collection und das folgende PDF-Dokument, in dem die zugehörigen Suchtexte und Eingabefelder zu den Beispielen vorhanden sind.

• Beispiel Dokument: https://downloads.signotec.com/Postman/signotec-postman-example.pdf

• Postman Collection: https://www.postman.com/signotec/signotec-signosign-universal

Nach dem Import der Postman Collection müssen die Collection-Variablen für Benutzername und Kennwort angepasst werden. Hierzu muss der importierte Ordner per Doppelklick geöffnet und der Reiter “Variablen” ausgewählt werden.

Nachdem der Server und die Zugangsdaten korrekt hinterlegt sind, können die nachfolgenden Anwendungsfälle ausgeführt werden.

Dokument hochladen und lokal unterschreiben

In dem Ordner “Upload and Sign a Document” sind alle API-Aufrufe vorhanden, mit denen ein Dokument hochgeladen und lokal geöffnet und unterschrieben werden kann.

1. Login ausführen, um ein Instance-Token zu generieren.

2. Beim Dokumenten-Upload das Dokument im Body im Parameter “document“ hinzufügen und ausführen.

3. Dokument in den Viewer laden.

4. (Optional) Index setzen, damit beim Remote-Save eine Zuordnung erfolgen kann. Der Indexwert muss im Body angepasst werden.

5. Anhand eines Suchtextes dynamische Signaturfelder setzen.

6. Anhand eines weiteren Suchtextes dynamische Signaturfelder setzen.

7. Platzierung eines statischen Signaturfelds.

8. Aktualisierung der Viewer-Konfiguration um z. B. die “Remote Save URL” zu setzen und andere Einstellungen des Viewers vorzunehmen.

9. Die URL des aktuellen Viewers abrufen.

10. URL in einem neuen Tab öffnen und das Dokument ausfüllen und unterschreiben.

Dokument hochladen für Fernsignatur versenden

In dem Ordner “Upload and Share a Document” sind alle API-Aufrufe vorhanden, mit denen ein Dokument hochgeladen und zum Unterzeichner gesendet werden kann.

1. Login ausführen, um ein Instance-Token zu generieren.

2. Beim Dokumenten-Upload das Dokument im Body im Parameter “document“ hinzufügen und ausführen.

3. Erstellen des “Sharingcases”. In diesem Aufruf muss der Body angepasst werden.

   1. Falls eine Benachrichtigung per Mail direkt aus dem System erfolgen soll, muss im Parameter “emailAddressee” der Empfänger angegeben werden.

   2. Mit dem Parameter “documentConfiguration” kann für Sharingcase und Dokument eine Konfiguration mitgegeben werden, in der z. B. das Ziel der Weiterleitung oder die Positionen der Signaturfelder mitgegeben werden können.

   3. Für die Authentifizierung gibt es vier Möglichkeiten im Aufruf:

      1. “password” wird leer mitgegeben → Keine Authentifizierung erforderlich

      2. “password” wird mitgegeben → Empfänger muss das Passwort eingeben, bevor das Dokument geöffnet werden kann.

      3. “tanAddressee” wird mitgegeben → Authentifizierung per TAN erforderlich.

      4. Weder “tanAddressee” noch “password” mitgegeben → Kennwort wird automatisch generiert und im Response ausgegeben.

4. (Optional) Anpassung der Sharingcase-Konfiguration, falls einzelne Einstellungen nochmal angepasst werden müssen.

5. Es gibt verschiedene Möglichkeiten, wie der Unterschreiber über den nun erstellten Sharingcase informiert werden kann.

   1. Falls die Benachrichtigung aus der Integration erfolgen soll, so kann der Link des Sharingcases abgerufen werden. Dieser kann anschließend flexibel dem Empfänger mitgeteilt werden.

   2. Die Benachrichtigung kann auch direkt aus dem System erfolgen. Hierzu wird der Benachrichtigungsendpunkt (“notify”) aufgerufen. Beim Aufruf kann die Sprache der Benachrichtigung über den Body-Parameter “locale” gewählt werden.

Falls der Sharingcase gelöscht werden soll, so kann dies über den Aufruf von “Abort Sharingcase” jederzeit erfolgen. Die zugehörigen Links werden ungültig, sodass bereits benachrichtigte Benutzer das Dokument nicht mehr aufrufen können. Das Dokument selbst bleibt in der Anwendung vorhanden und muss bei Bedarf separat gelöscht werden.

Dokument hochladen und im Workflow versenden

In dem Ordner “Upload and Workflow Document” sind alle API-Aufrufe vorhanden, mit denen ein Dokument hochgeladen und ein Workflow erstellt und gestartet werden kann.

1. Login ausführen, um ein Instance-Token zu generieren.

2. Erstellen des “Workflow Plans”. Der Name des Plans kann über den Parameter “name” angepasst werden.

3. Erstellen eines Dokumentenordners. In diesem werden die Dokumente für den Workflow gesammelt.

4. Per Upload das Dokument im Body im Parameter “document“ zum erstellten Dokumentenordner hinzufügen.

5. Nun werden die Workflowschritte angelegt. Dabei können beliebig viele Empfänger das Dokument parallel oder in einer bestimmten Reihenfolge bekommen. Es ist auch möglich, dass der Dokumentenordner abhängig vom Empfänger variiert. Vor der Ausführung sollten mindestens folgende Parameter angepasst werden, damit das Dokument beim richtigen Empfänger landet:

   1. Der Name des Empfängers kann über den Parameter “signerName” angegeben werden.

   2. Die E-Mail-Adresse, an die der Vorgang gesendet wird, wird im Parameter “signerEmail” angegeben.

   3. Um die Dokumente des Empfängers zusätzlich mit einem Kennwort zu schützen, kann dieses im Parameter “password” angegeben werden.

   4. Alternativ zum Passwort kann analog zum Sharingcase ein TAN-Empfänger mit dem Parameter “tanAddressee” angelegt werden.

6. Legt einen zweiten Workflowschritt an, der ausgeführt wird, nachdem der erste abgeschlossen wurde. Auch bei diesem Aufruf sollten mindestens “signerName” und “signerEmail” vor der Ausführung angepasst werden.

7. Startet den erstellten Workflow. Beim Start kann noch ein Name im Body Parameter “name” mitgegeben werden, dieser wird auch in der Benutzeroberfläche angezeigt und kann die Zuordnung vereinfachen. Mit dem erfolgreichen Start werden auch die Personen aus Schritt 1 per E-Mail benachrichtigt. Alle weiteren Schritte laufen anschließend automatisch.

Falls ein gestarteter Workflow-Prozess gelöscht werden soll, so kann dies über den Aufruf von “Delete Workflow” jederzeit erfolgen. Die zugehörigen Links werden ungültig, sodass bereits benachrichtigte Benutzer das Dokument nicht mehr aufrufen können.

Dokument herunterladen

In dem Ordner “Download a Document” sind alle API-Aufrufe vorhanden, mit denen ein Dokument wieder heruntergeladen und in signoSign/Universal gelöscht werden kann.

1. Login ausführen, um ein Instance-Token zu generieren.

2. Das Dokument aus dem System herunterladen.

3. Nach dem erfolgreichem Download sollte das Dokument von der Plattform entfernt werden.