sproof Sign: Erste Schritte (API)
Willkommen beim sproof Sign API Quick Start Guide!
Dieses Dokument legt die grundlegenden Voraussetzungen und Kernkonzepte dar, die Sie benötigen, um später erfolgreich mit der sproof Sign API zu interagieren. Es dient als Fundament für die detaillierten Anleitungen, die in den nachfolgenden Kapiteln der Academy folgen.
Zielgruppe: Dieser Guide richtet sich an Entwickler:innen, die grundlegende Programmierkenntnisse besitzen und mit Konzepten wie RESTful APIs, JSON und HTTP vertraut sind.
1. Voraussetzungen
Bevor Sie starten, stellen Sie sicher, dass Sie Folgendes haben:
sproof Sign Account: Ein aktiver sproof Sign Account (Erwerb eines Enterprise-Plans oder Testplans), idealerweise mit einer User+ Lizenz, freigeschaltener Fastlane und den benötigten Signaturarten/Kontingent, um den vollen Funktionsumfang nutzen zu können.
API-Schlüssel (
{{token}}): Dieser ist über Ihr sproof-Konto unter Einstellungen - API-Tokens ersichtlich. Jeder innerhalb Ihres Plans generierte API-Schlüssel ermöglicht es, Einladungen im Namen jeder im Plan registrierten E-Mail-Adresse zu erstellen. Nach dem Löschen kann dieser API-Schlüssel keine API-Anfragen mehr ausführen. Mit dem Rollenmanagement feature, können auch Personen mit bestimmten Berechtigungen ihren eigenen Token generieren, um dem Plan-Inhaber einen besseren Überblick über die Nutzung der API-Tokens durch die Teammitglieder zu ermöglichen.Absender-E-Mail: Eine E-Mail-Adresse, die zu einem Mitglied Ihres sproof Sign Plans gehört. Diese E-Mail-Adresse wird für die korrekte Zuordnung der versendeten Dokumente benötigt.
Testdokument: Ein Dokument das Sie unterschreiben lassen möchten als base64 codiert.
Grundlegendes technisches Verständnis: Sie sollten mit HTTP-Requests (POST, GET), dem JSON-Datenformat und der Kodierung von Daten (z.B. Base64) vertraut sein.
Optional: Eine
callbackUrl: Eine URL, an die wir Status-Updates Ihrer Dokumente senden können (z.B. webhook.site für Tests). Dies ist nicht zwingend erforderlich, wird aber für Echtzeit-Updates empfohlen.
2. Kernkonzepte
createSignatureRequest: Dies ist der Haupt-API-Aufruf, um eine Signaturanfrage zu erstellen. Er beinhaltetinviteDataundenvelopeDatazur Konfiguration der Einladung und des Dokuments.inviteData: Allgemeine Informationen zur Einladung (z.B. Absender:in, Empfänger:in, Betreff, Nachricht).envelopeData: Dokumentenspezifische Daten und Einstellungen (z.B. Dokument selbst, Signaturart, Signaturpositionen, Rollen).callbackUrl: Ihre Endpunkt-URL, an die wir Benachrichtigungen über Statusänderungen senden.
memberId: Sie ist eine eindeutige ID, die eine:n spezifische:n Empfänger:in für ein spezifisches Dokument innerhalb eines sproof Sign Signaturprozesses identifiziert und dessen individuelle Einladung sowie den Dokumentenstatus repräsentiert. Sie finden diese im Antwortobjekt für den:die spezifische:n Empfänger:in nach einem erfolgreichen Aufruf. Die memberId wird für das Abrufen des Dokumentstatus per Polling, zum Herunterladen des signierten Dokuments und zum Öffnen des Dokuments im sproof Sign Editor verwendet.Base64: Dokumente müssen vor dem Senden in dieses Format kodiert werden.
Fastlane: Die Fastlane ist eine optimierte Benutzeroberfläche, die entwickelt wurde, um den Prozess des Einholens von Signaturen und anderen erforderlichen Daten zu beschleunigen. Sie bietet einen geführten, schrittweisen Ablauf, der Effizienz und Benutzerfreundlichkeit für Ihre Empfänger gewährleistet. Dokumente können entweder per E-Mail, Link oder QR-Code geteilt werden.
Fastlane-Profile ermöglichen die Anpassung dieses Prozesses, sodass Sie den Signaturablauf an Ihre spezifischen Bedürfnisse anpassen können. So können Sie die im Signaturprozess möglichen Screens (welcome, document, provider, sign, end) und auch weitere Eigenschaften individuell konfigurieren. Alle erstellten Fastlane-Profile sind für jedes Mitglied Ihres Plans zugänglich, was die Verwaltung und Nutzung in Ihrer gesamten Organisation vereinfacht.
Workflow: Eine vordefinierte Abfolge von Schritten und Einstellungen für den Signaturprozess (z.B. Anzahl der Signierenden, Signaturpositionen am Dokument, E-Mail-Vorlagen).
Stapelsignatur: Die Stapelsignatur ermöglicht die API-gesteuerte Initiierung der gleichzeitigen Signatur mehrerer Dokumente. Dazu werden Dokumente einem Stapel zugewiesen und dessen Signatur ausgelöst. Dies erfordert eine einmalige Bestätigung auf dem Mobilgerät des Benutzers. Voraussetzung sind eine User+ Lizenz und eine erfolgreich verifizierte Identität des Anwenders. Die qualifizierte Stapelsignatur (QES) funktioniert ausschließlich mit der sproof QES (Swisscom); andere QES-Anbieter sind nicht kompatibel.
Signaturen prüfen: Sie können die Gültigkeit digitaler Signaturen in einem Dokument über die API überprüfen. Senden Sie dazu das Base64-kodierte Dokument an den Endpunkt
documents/verify. Die API liefert Ihnen dann im Antwortobjekt den Validierungsstatus der Signaturen. Unsere Signaturprüfung entspricht dem ETSI-Standard.Signing Widget: Durch das Signing Widget können Sie den Signaturprozess direkt in ihre eigene Website integrieren. Anstatt Nutzer:innen auf eine separate sproof Sign-Seite umzuleiten, können Dokumente nahtlos direkt innerhalb der Anwendung unterschrieben werden, was ein kontrolliertes Benutzererlebnis bietet. Es funktioniert durch die Integration eines Code-Snippets (per iframe) in Ihre Website, wodurch Nutzer über die für mobile Endgeräte optimierte Fastlane-Benutzeroberfläche direkt auf Ihrer Seite signieren können.
Nächste Schritte
Sie haben nun die grundlegenden Voraussetzungen und Kernkonzepte der sproof Sign API kennengelernt. Dies ist das Fundament, um Ihre digitalen Signaturprozesse zu automatisieren und nahtlos in Ihre Anwendungen zu integrieren.
Was kommt als Nächstes?
Um tiefer in die Materie einzutauchen und Ihre erste Integration umzusetzen, empfehlen wir Ihnen, die folgenden Bereiche der sproof Academy zu erkunden:
Erste Signaturanfrage senden: Lernen Sie anhand praktischer Beispiele, wie Sie Ihren ersten API-Call zum Versenden eines Dokuments zur Signatur konfigurieren und ausführen.
Status-Updates und Callbacks verarbeiten: Erfahren Sie, wie Sie unsere automatischen Callback-Benachrichtigungen empfangen und interpretieren, um den Signaturfortschritt in Echtzeit zu verfolgen und nachgelagerte Prozesse auszulösen.
Signierte Dokumente herunterladen: Entdecken Sie die verschiedenen Möglichkeiten, signierte Dokumente abzurufen und in Ihr System zu integrieren.
Arbeiten mit Workflows über die API: Optimieren Sie komplexe Signaturprozesse, indem Sie vordefinierte Workflows programmatisch nutzen oder anpassen.
Fastlane-Integration: Integrieren Sie die Fastlane-Benutzeroberfläche direkt in Ihre Website, um einen optimierten Signaturprozess für Ihre Endbenutzer zu ermöglichen.
Signing Widget einbetten: Nutze das Signing Widget, um ein Dokument direkt auf deiner Webseite signieren zu lassen, ohne dass deine Nutzer deine Seite verlassen müssen.
Stapelsignierung: Verarbeite eine große Anzahl von Dokumenten effizient in einem einzigen Aufruf.
Signaturprüfung: Bestätige die Gültigkeit von Signaturen in einem Dokument über die API, um die Authentizität zu garantieren.
Wir sind zuversichtlich, dass Sie mit diesen Ressourcen Ihre Integration schnell und erfolgreich umsetzen können. Bei spezifischen Fragen oder Herausforderungen steht Ihnen unser
Developer Support jederzeit zur Verfügung.
Starten Sie jetzt Ihre Integration und transformieren Sie Ihre Dokumenten-Workflows mit sproof Sign!