Scope-Beschreibung für ISV-Ökosystem-Anwendungsschnittstellen
1. Übersicht
Dieses Dokument stellt Entwicklern von Ökosystem-Partnern die Scope-Bereiche (Berechtigungsbereiche) im eSignGlobal-Autorisierungssystem vor. Bei der Integration der App-Autorisierung müssen Entwickler die jeweiligen Scopes entsprechend den tatsächlichen Geschäftsanforderungen anfordern. Jeder Scope listet die darin zulässigen OpenAPI-Aufrufe auf. Die Plattform regelt die Zugriffsrechte der Anwendung auf die entsprechenden Ressourcen strikt anhand der autorisierten Scopes.
Basis-Authentifizierungsschnittstelle
Bevor die Ökosystem-App die Schnittstellen offiziell aufruft, muss zunächst über den Autorisierungsendpunkt ein Zugangs-Token abgerufen werden:
Schnittstellenname
Schnittstellenpfad
Schnittstellenbeschreibung
AccessToken abrufen
POST /esignglobal/v1/oauth2/accessToken
Über appid und appsecret einen authentifizierten access_token abrufen, der zur Anfrage bei der eSignGlobal API im Namen eines bestimmten Benutzers dient. Die Gültigkeit des Tokens beträgt 24 Stunden.
Die derzeit im eSignGlobal-Ökosystem freigegebenen Scope-Berechtigungsbereiche umfassen hauptsächlich:
signature: Kernservice für elektronische Signaturen
stamp: Service zur Stempelverwaltung
comparisons: Service zum Vertragsvergleich
2. Scope-Details und Schnittstellenliste
2.1 Scope: signature (E-Signaturdienst)
Dieser Scope ist der grundlegendste und am häufigsten verwendete Berechtigungsbereich und enthält die Kernschnittstellen des gesamten E-Signatur-Geschäftsprozesses. Nach der Autorisierung dieses Scopes kann die Anwendung Vorlagen, Unterlageungsdateien (einschließlich Anhänge), Teilnehmer sowie den zentralen Envelope-Workflow verwalten und bearbeiten.
Modul 1: Vorlagendienst
Schnittstellenname
Schnittstellenbeschreibung
Details zu Vorlagensteuerelementen des Unterzeichners abrufen
Vorlagensteuerelementinformationen des angegebenen Unterzeichners sowie deren entsprechende Attributkonfiguration abrufen
Details zur Vorlage abrufen
Vollständige Informationen zu einer bestimmten Vorlage abrufen, einschließlich Felder und Dateistrukturdetails
Datei aus ausgefüllter Vorlage generieren
Geschäftsdaten basierend auf der angegebenen Vorlage ausfüllen und automatisch eine PDF-Datei erstellen
Vorlagenliste abfragen
Verfügbare Vorlagenliste für das aktuelle Konto paginiert oder nach bestimmten Filterkriterien abfragen
Details zum Dateierstellungsauftrag abrufen
Abfrage des endgültigen Ausführungsergebnisses einer durch eine Vorlage generierten Datei über die asynchrone Aufgaben-ID
Modul 2: Dateiverwaltung
Schnittstellenname
Schnittstellenbeschreibung
Datei hochladen
Hochladen bestimmter lokaler Dateien oder Workflow-Dateien auf die Plattform zur nachfolgenden Unterzeichnung
Koordinaten basierend auf Schlüsselwörtern ermitteln
Textsuche in hochgeladenen Dokumenten durchführen und die Positionskoordinaten der Treffer zurückgeben
Datei herunterladen
Herunterladen spezifischer fertiggestellter unterzeichneter Dokumente, Quelldateien oder weiterer geschäftsrelevanter Anhangsdateien
Unterzeichnungsdatei hinzufügen
Zuvor erfolgreich hochgeladene Dateien einem konkreten Unterzeichnungs-Umschlag oder Prozess zuordnen
Unterzeichnungsdatei löschen
Falsch hochgeladene oder vorübergehend nicht benötigte Dateien aus dem Umschlagprozess entfernen
Anhang hinzufügen
Ergänzende erläuternde Anhänge im Umschlag- oder Signaturprozess hinzufügen
Anhang löschen
Bestimmte Anhangsdokumente aus dem Umschlag- oder Signaturprozess entfernen
Modul 3: Verwaltung der Beteiligten
Schnittstellenname
Schnittstellenbeschreibung
Unterzeichner hinzufügen
Unterzeichner im bestimmten Umschlagprozess hinzufügen, der die Signaturaktion ausführen muss
Unterzeichner löschen
Nicht mehr benötigte Unterzeichnerpartei aus dem bestimmten Umschlagprozess entfernen
Kopieempfänger hinzufügen
Kopieempfängerrolle hinzufügen, die nur Fortschrittsbenachrichtigungen empfängt und das endgültig unterzeichnete Dokument einsehen kann
Kopieempfänger löschen
Bestimmte Kopieempfängerrolle entfernen
Modul 4: Umschlagverwaltung
Schnittstellenname
Schnittstellenbeschreibung
Schnelles Initiieren des Umschlags
Wenn die anzubindende Plattform diesen Schnittstellenaufruf zur Erstellung eines Umschlags verwendet und das System nach Abschluss der Unterschrift den Schließvorgang automatisch verarbeitet, muss „Umschlag schließen“ nicht manuell aufgerufen werden.
Umschlag erstellen
Zum Erstellen eines Umschlags im Entwurfsstatus; unterstützt die Konfiguration von Parametern wie Signaturthema und Unterzeichnereinstellungen.
Umschlag freigeben
Nach Bestätigung, dass alle Dokumente und Unterzeichner korrekt sind, wird die Unterschriftsaufgabe offiziell an die nachgelagerten Systeme weitergeleitet.
Umschlag schließen
Manuelles Schließen des Umschlags. Vor dem Schließen müssen alle Unterzeichner ihre Unterschriften geleistet haben. Nach Prozessabschluss sind keine Änderungen mehr möglich.
Signaturadresse abrufen
Abrufen des exklusiven Shortlinks oder der direkt aufrufbaren URL der Signierseite für einen bestimmten Unterzeichner.
Umschlagdetails abfragen
Abrufen der Gesamtinformationen des Umschlags, der verknüpften Dateien, der Beteiligten sowie des aktuellen Workflow-Status.
Umschlag widerrufen
Ein vom Initiator zurückgezogenes Signatur-Envelope, das noch nicht vollständig signiert wurde.
Erinnerung an den Signatur-Envelope
Wenn der Envelope noch nicht vollständig signiert ist, kann eine Erinnerungsbenachrichtigung an die aktuell erforderlichen, aber noch nicht unterzeichneten Unterzeichner gesendet werden. Das Erinnerungsintervall beträgt 30 Minuten.
Adresse der Vorschau-Signaturseite abrufen
Nach Aktivierung des Envelopes kann über diese Schnittstelle die Adresse der Vorschau-Signaturseite abgerufen werden. Dies dient hauptsächlich dazu, innerhalb der integrierten Plattform Nicht-Teilnehmern des Envelopes die Möglichkeit zu bieten, die Signaturdateien und den Fortschritt einzusehen.
Sendeansicht des Envelopes erstellen
Erstellen Sie die Absenderansicht des Envelopes anhand der Envelope-ID. Bei im Rahmen dieser Ansicht gestarteten Signaturprozessen werden die Informationen des Initiators mit den aus dem OAuth Access Token extrahierten Benutzerdaten gefüllt.
2.2 Scope: stamp (Siegelverwaltungsdienst)
Dieser Scope dient speziell der Verwaltungsautorisation für Unternehmensstempel oder persönliche Namensstempel. Er eignet sich für Drittsystemlandschaften, die lediglich die Pflege einer einheitlichen Unternehmens-Siegelbibliothek (Erstellung, Löschung, Änderung und Suche von Siegeln) benötigen, ohne direkt in den Startprozess von Signaturen einzugreifen.
Schnittstellenname
Schnittstellenbeschreibung
Siebelliste abfragen
Rufen Sie die Daten der Siegelressourcenliste mit einer AppID ab, die über die entsprechenden Berechtigungen zur Siegelabfrage verfügt.
Siegel erstellen
Erstellen Sie ein Siegel mit einer berechtigten AppID durch einen Base64-codierten String des hochgeladenen Bilds (unterstützt PNG, Größe 18 mm–100 mm).
Stempel bearbeiten
Ändern von Informationen wie Name und Bild für bereits erstellte Stempel
Stempel löschen
Vollständiges Entfernen von angegebenen Stempelressourcen, die keine geschäftlichen Verbindungen mehr aufweisen
2.3 Scope: comparisons (Vertragsvergleichsdienst)
Dieser Scope ist ausschließlich für den Funktionsbereich der intelligenten Vertragsrechtsfunktionen vorgesehen. Er ermöglicht es Anwendungen von Ökosystem-Partnern, in ihren eigenen Prozessen zur Vertragsprüfung und rechtlichen Bewertung flexibel Vergleichsfunktionen für Texte und Versionen zu nutzen, um Abweichungen vor und nach Vertragsüberarbeitungen schnell zu erfassen.
Schnittstellenname
Schnittstellenbeschreibung
Seite mit den Ergebnissen des Vertragsvergleichs abrufen
Adresse der visuellen Seite abrufen, die die Ergebnisse der Vergleichsdifferenzen anzeigt
Details zum Vertragsvergleich abfragen
Abrufen der Vertragsvergleichsergebnisse über die geschäftliche ID des Vertragsvergleichs, einschließlich der Anzahl der Unterschiede (Hinzufügungen, Löschungen, Änderungen) sowie detaillierter Vergleichsdifferenzinhalte (Detaillokalisierung).
