sproof Widget: Signaturen einbetten (API)

Hallo Entwickler:in,

Wir freuen uns, Ihnen unser Signing Widget vorzustellen, mit dem Sie den Signaturprozess nahtlos in Ihre eigene Website integrieren können.

Anstatt Ihre Nutzer auf eine separate Seite umzuleiten, ermöglicht Ihnen ein einfaches Code-Snippet per iframe, Dokumente direkt in Ihrer Anwendung signieren zu lassen. Das Ergebnis: ein reibungsloses und kontrolliertes Benutzer:innenerlebnis.

Erfahren Sie mehr in diesem kurzen Video: https://drive.google.com/file/d/1GaUzoNgE0Az6MRXlMJ7_YZwZnavJJh4u/view

Für die Fastlane ist es notwendig, dass Ihr Userplan dafür freigeschalten wurde.

So funktioniert die Integration

Das nachstehende Beispiel führt Sie durch den Prozess:

Erstellung eines Fastlane-Profils
Versenden eines Dokuments zur Signatur unter Verwendung der Fastlane
Einbettung via iframe in Ihr System
Empfangen von Status-Updates über einen Callback.

Schritt 1: Fastlane-Profil erstellen

Um die während des Signaturprozesses anzuzeigenden Screens (welcome, document, provider, sign, end) und auch weitere Eigenschaften individuell zu konfigurieren, erstellen wir in diesem Schritt ein Fastlane Profil. In unser Beispiel wollen wir nur den sign screen anzeigen und alle anderen screens und zusätzliche Informationen ausblenden (showHeader: false, showProgressBar: false, showAppbar: false, sendEmail: false). Die backgroundColor könnte der Farbe Ihrer Website entsprechen um den signing screen bestmöglich in Ihre Website zu integrieren.

API-Call: POST https://sign.sproof.com/api/v1/fastlane?token={{token}}

Dokumentation: Fastlane Profiles

{
  "name": "Most Minimal Fastlane Profile",
  "screens": {
    "welcome": {
      "enabled": false    
      },
    "document": {
        "enabled": false
      },
    "provider": {
      "enabled": false
    },
    "sign": {
        "signOnDisplay": true,
        "previewDocumentButton": false, 
        "signatureCard": false
    },
    "end": {
      "enabled": false
    }
  },
  "successEmail": {
    "sendEmail": false
  },
    "backgroundColor": "#e1e1e1",
    "showAppbar": false,
    "showProgressBar": false,
    "showHeader": false
}

Die Antwort auf diesen Aufruf enthält die id des Fastlane-Profiles (in diesem Beispiel b1f15495-8b48-4317-b279-1afee0d96e6e), die wir im nächsten Schritt benötigen.

{
    "id": "b1f15495-8b48-4317-b279-1afee0d96e6e",
    "name": "Most Minimal Fastlane Profile",
    
  // ... weitere Profilinformationen
}

Schritt 2: Signaturanfrage mit Fastlane-Profil erstellen

Jetzt erstellen wir die eigentliche Signaturanfrage und nutzen die id des Profils aus Schritt 1, um das Fastlane-Profil für die Empfänger:innen (in unserem Beispiel Max Mustermann) zu verwenden. Das useFastlane-Flag muss auf true gesetzt werden. Für dieses Beispiel geben wir auch eine callbackUrl für den Erhalt von Status Updates an und eine returnUrl an auf die nach erfolgter Signatur retourniert werden soll.

API-Call: POST https://sign.sproof.com/api/v1/documents/signature

Dokumentation: Signature Requests

{
  "token": "{{token}}",
  "inviteData": {
    "sender": {
      "email": "{{email}}",
      "firstName": "sproof",
      "lastName": "Sender"
    },
    "recipients": [
      {
        "email": "max.mustermann@sproof.com",
        "firstName": "Max",
        "lastName": "Mustermann"
      }
    ]
  },
  "envelopeData": {
    "documentDataArray": [
      {
        "data": "{{pdf_im_base64_format}}",
        "fileName": "wichtiger_vertrag.pdf",
        "recipientDetails": {
          "max.mustermann@sproof.com": {
            "role": "signer",
            "signaturePositions": [
              {"page": 0, "x": 0.57489, "y": 0.8455, "width": 0.35, "height": 0.1}
            ]
          }
        }
      }
    ],
    "callbackUrl": "https://webhook.site/ihre-eigene-callback-url",
    "returnUrl": "https://deine-website.com/returnurl",
    "useFastlane": true,
    "fastlaneProfileId": "b1f15495-8b48-4317-b279-1afee0d96e6e"
  }
}

Ersetzen Sie {{token}} durch Ihren API-Token.
{{email}} ist die E-Mail-Adresse des Absenders (muss ein Mitglied vom selben Plan sein).
{{pdf_im_base64_format}} sollte das Base64-kodierte PDF-Dokument enthalten das Sie unterschreiben möchten.
callbacks: Definiert die Callback-URL, an die sproof Status-Updates sendet.
returnUrl: Der Link auf welchen nach erfolgreichen Abschluss des Signaturvorgangs retourniert wird.
useFastlane: true um den:die Empfänger:in über die Fastlane einzuladen.
fastlaneProfileId: Fügen Sie hier die Id Ihres in Schritt 1 erstellten Fastlane Profiles ein.

Die Antwort auf diesen Aufruf enthält unter anderem ein member Object (= sender) und einen members Array in dem der/die Eingeladene/n angeführt sind. Die memberId für unseren Empfänger Max Mustermann, (in diesem Beispiel 46d4f5fcc35780634cd7ce2c4a85057fc7952007192ad066067ed09bccb89e63788db0) verwenden wir für den nächsten Schritt.

//Beispielhafter Auszug der Response:
{
    "documents": [
        {
            "id": "4583383b341ec93147f805d528776872d5eda52ba406875370042b026973eef424801f",
            "name": "wichtiger_vertrag",
            "callbackUrl": "https://webhook.site/ihre-eigene-callback-url",
            "returnUrl": "https://deine-website.com/returnurl",
            "returnBtnText": null,
            "state": "pending",
            "fastlaneProfileId": "b1f15495-8b48-4317-b279-1afee0d96e6e",
            "members": [
                {
                    "id": "46d4f5fcc35780634cd7ce2c4a85057fc7952007192ad066067ed09bccb89e63788db0",
                    "documentId": "4583383b341ec93147f805d528776872d5eda52ba406875370042b026973eef424801f",
                    "email": "max.mustermann@sproof.com",
                    "firstName": "Max",
                    "lastName": "Mustermann",
                    "signaturePosition": [
                        {
                            "page": 0,
                            "x": 0.57489,
                            "y": 0.8455,
                            "width": 0.35,
                            "height": 0.1
                        }
                    ],
                    "useFastlane": true
                }
            ],
            "member": {
                "id": "a91cff2e7fff38a2c4ed823612487197ca23c5a0abedd4e9cf515accf255d0b164ad79",
                "documentId": "4583383b341ec93147f805d528776872d5eda52ba406875370042b026973eef424801f",
                "email": "sender@sproof.com",
                "firstName": "sproof",
                "lastName": "Sender",
                "isAdmin": true,
            }
        }
    ]
}
//weitere Daten der response wurden einfachhalber für dieses Beispiel entfernt

Schritt 3: Signatur-URL erstellen und einbetten

Um den Signaturprozess zu starten, muss der:die Unterzeichner:in auf seine individuelle Signatur-URL zugreifen.

Diese kann wie folgt zusammengebaut und anschließend verwendet werden um das Dokument zu öffnen:

https://sign.sproof.com/#/fastlane/{memberId}

Setzen Sie dafür in {memberId}die memberId des Empfängers (in diesem Fall Max Mustermann) ein, damit dieser mit diesem Link das Dokument unterzeichnen kann.

Diese URL betten Sie nun in einen <iframe> auf Ihrer Website ein.

<iframe
  src="https://sign.sproof.com/#/fastlane/46d4f5fcc35780634cd7ce2c4a85057fc7952007192ad066067ed09bccb89e63788db0"
  style="width:100%; height:100%; border:none;"
></iframe>

Durch die Einbettung der URL kann der:die Unterzeichner:in den Signaturprozess direkt in Ihrer Anwendung durchführen. Nach erfolgreichem Abschluss (diese Information erhalten Sie wie in Schritt 4 beschrieben über den Callback) wird der:die User:in auf die von Ihnen definierte returnUrl retourniert.

Schritt 4: Status-Updates über Callbacks erhalten

Sobald ein Ereignis eintritt (z.B. eine Signatur ist abgeschlossen), sendet sproof einen POST-Request an die von Ihnen in Schritt 2 in callbackUrl angegebene URL.

Beispiel für das Callback-Objekt - Max Mustermann hat signiert:

{
  "name": "wichtiger_vertrag",
  "id": "8925b941ea322b82a246a19c6f5d29d3ee457a83cb679eaa008c2c7707a574a8cd1937",
  "language": "de",
  "updatedAt": "2025-07-23T14:03:02.854Z",
  "createdAt": "2025-07-23T14:02:41.082Z",
  "signaturesTypes": [],
  "callbackUrl": "https://webhook.site/ihre-eigene-callback-url",
  "returnUrl": "https://deine-website.com/returnurl",
  "returnBtnText": null,
  "inPersonSigning": false,
  "signingRound": 1,
  "member": {
    "id": "a91cff2e7fff38a2c4ed823612487197ca23c5a0abedd4e9cf515accf255d0b164ad79",
    "email": "sender@sproof.com",
    "firstName": "sproof",
    "lastName": "Sender",
    "lastActivityAt": "2025-07-23T14:02:41.091Z",
    "createdAt": "2025-07-23T14:02:41.091Z",
    "signed": false,
    "isAdmin": true,
    "isSigner": false,
    "signaturePosition": [],
    "signedAt": null,
    "signingOrder": 1,
    "declinedAt": null,
    "signatures": []
  },
  "boxes": [],
  "members": [
    {
      "id": "46d4f5fcc35780634cd7ce2c4a85057fc7952007192ad066067ed09bccb89e63788db0",
      "isSigner": true,
      "email": "max.mustermann@sproof.com",
      "firstName": "Max",
      "lastName": "Mustermann",
      "isAdmin": false,
      "signedAt": "2025-07-23T14:03:02.657Z",
      "declinedAt": null,
      "signingOrder": 1,
      "signaturePosition": null,
      "signed": true,
      "signatures": [
        {
          "signatureType": "aes_sproof",
          "signedAt": "2025-07-23T14:03:02.657Z"
        }
      ]
    }
  ],
  "allSignersSigned": true,
  "allMembersSigned": false
}

Wichtiger Hinweis: Bei einem Fehlschlag ist ein Wiederholungsmechanismus implementiert, um sicherzustellen, dass der Request erneut versucht wird.

5. Signiertes Dokument herunterladen

Mit der memberId des senders (http://member.id ) die Sie im Callback-Objekt erhalten, können Sie das signierte Dokument als binary PDF oder als Base64-kodierte Datei herunterladen.

Endpunkt: GET https://sign.sproof.com/api/v1/documents/download/{{memberId}}?token={{token}}

Ersetzen Sie {{memberId}} durch die id des senders (sender@sproof.com), die Sie im Callback untermember.id erhalten haben (a91cff2e7fff38a2c4ed823612487197ca23c5a0abedd4e9cf515accf255d0b164ad79 in diesem Beispiel).
Ersetzen Sie {{token}} erneut durch Ihren API-Token.

Wir hoffen, dieses Beispiel hilft Ihnen beim Start Ihrer Integration!

Bei Fragen stehen wir Ihnen gerne zur Verfügung.