sproof Sign: Einholen von Signaturen inkl. Workflow (API)

Hallo Entwickler:in,

wir freuen uns, Ihnen zu zeigen, wie Sie unsere Signatur-Lösung nahtlos in Ihre Anwendungen integrieren können.

Dieses Beispiel führt Sie durch den Prozess wie Sie einen neuen Workflow erstellen, Empfänger:innen zur Signatur von Dokumenten über diesen Workflow einladen, Status-Updates über einen Callback empfangen und schlussendlich das signierte Dokument herunterladen können.

1. Workflow via UI erstellen und WorkflowId erhalten

Zuerst können Sie einen Workflow bequem über unsere Benutzeroberfläche https://sign.sproof.com/#/dashboard erstellen:

Navigieren Sie zu Kontakte & Workflows → Workflows.
Klicken Sie auf Neuer Workflow erstellen.

Dokument: Dort laden Sie ein Platzhalter-Dokument hoch, um die verschiedenen Einstellungen treffen zu können. Beim Einholen von Signaturen mit dem Workflow kann entweder das hier im Workflow hinterlegte Dokument verwendet werden oder zum Zeitpunkt des Einladens ein anderes Dokument stattdessen im Request-Body mitgegeben werden. Signaturen mit Workflows einsammeln funktioniert aktuell nur für einzelne Dokumente (keine Dokumentenmappen).

Personen-Platzhalter: Personen-Platzhalter müssen definiert werden. Hier ist wichtig, dass dies der genauen Anzahl an Empfängern entspricht, die später eingeladen werden sollen. Für die Personen-Platzhalter kann die Signaturposition bestimmt werden (indem die Signaturkarte auf das Dokument gezogen wird – hier werden Daten wie Seite, Größe der Signaturkarte und Position gespeichert) und weitere Einstellungen wie Rolle am Dokument und Signaturtyp getroffen werden.

Weitere Einstellungen: Auch andere Einstellungen wie E-Mail-Einstellungen, Erinnerungen und Fälligkeit können hier einmalig definiert werden.

Nachdem der Workflow gespeichert wurde, kann die WorkflowId aus der URL herauskopiert werden. Diese entspricht dem hinteren Teil des Links:

https://sign.sproof.com/#/workflowEditor/bb03b2627660b90dd1152ea957f949c300703195adc519afe5550d4e0def638b81ed50

Diese WorkflowId (bb03b2627660b90dd1152ea957f949c300703195adc519afe5550d4e0def638b81ed50 im Beispiel) wird für die Einladung im nächsten Schritt benötigt.

2. Empfänger über den Workflow zur Signatur einladen

Verwenden Sie den folgenden Endpunkt, um Empfänger zu einem erstellten Workflow einzuladen:

Endpunkt: POST https://sign.sproof.com/api/v1/documents/invite-recipients-to-workflow

Beispiel-Body des Requests:

{
  "token": "{{token}}",
  "workflowId": "bb03b2627660b90dd1152ea957f949c300703195adc519afe5550d4e0def638b81ed50",
  "data": "{{pdf_im_base64_format}}",
  "callbackUrl": "https://webhook.site/ihre-eigene-callback-url",
  "fileName": "Wichtiger Vertrag",
  "sender": {
    "email": "{{email}}",
    "firstName": "sproof",
    "lastName": "Sender"
  },
  "recipients": [
    {
      "email": "max.mustermann@sproof.com",
      "firstName": "Max",
      "lastName": "Mustermann"
    }
  ]
}

token: Ihr API-Token.
workflowId: Die zuvor kopierte ID des Workflows.
data: Wie bereits beschrieben, kann zum Zeitpunkt der Einladung ein anderes Dokument (anstelle des im Workflow gespeicherten) mitgegeben werden. Dieses wird als Base64-String hier eingefügt.
callbackUrl: Eine notwendige Angabe, damit wir Status-Updates an diese URL senden können.
fileName: Der Dateiname des Dokuments.
sender: Informationen zum Absender der Einladung.
recipients: Eine Liste der Empfänger:innen, die zum Workflow eingeladen werden sollen.

3. Callback-Benachrichtigungen empfangen

Sobald ein Dokument signiert wird oder ein:e Empfänger:in es ablehnt, senden wir einen POST-Request an die von Ihnen in callbackUrl angegebene URL. Dieser Request enthält ein Objekt mit relevanten Informationen zum Status des Dokuments, einschließlich der memberId.

Beispiel für das Callback-Objekt:

{
  "name": "Wichtiger Vertrag",
  "id": "c95302c896a19179e61341740c19cbd4089600e0d83c3b4401b1e63414e55f336ba87a",
  "language": "en",
  "updatedAt": "2025-07-24T07:35:42.854Z",
  "createdAt": "2025-07-24T07:21:54.472Z",
  "signaturesTypes": [
    "qualified"
  ],
  "callbackUrl": "https://webhook.site/b27d2a2c-cb8b-42fd-b5a3-364af6f0bffe",
  "returnUrl": null,
  "returnBtnText": null,
  "inPersonSigning": false,
  "signingRound": 1,
  "member": {
    "id": "40e49b1ebaaaa8655ba531b5c86f3bab48d191723d8d3ac220ae8dcc12326e07695d98",
    "email": "sender@sproof.com",
    "firstName": "sproof",
    "lastName": "Sender",
    "lastActivityAt": "2025-07-24T07:21:54.482Z",
    "createdAt": "2025-07-24T07:21:54.482Z",
    "signed": false,
    "isAdmin": true,
    "isSigner": false,
    "signaturePosition": [],
    "signedAt": null,
    "signingOrder": 1,
    "declinedAt": null,
    "signatures": []
  },
  "boxes": [],
  "members": [
    {
      "id": "f30a1be1864f591f6720a423e64393bc274a679d9d80106dfee7f7d7c3279eb3c88368",
      "isSigner": true,
      "email": "max.mustermann@sproof.com",
      "firstName": "Max",
      "lastName": "Mustermann",
      "isAdmin": false,
      "signedAt": "2025-07-24T07:35:42.679Z",
      "declinedAt": null,
      "signingOrder": 1,
      "signaturePosition": null,
      "signed": true,
      "signatures": [
        {
          "signatureType": "qes_idaustria",
          "signedAt": "2025-07-24T07:35:42.679Z"
        }
      ]
    }
  ],
  "allSignersSigned": true,
  "allMembersSigned": false
}

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

4. Signiertes Dokument herunterladen

Mit der memberId, 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, die Sie im Callback untermember.id erhalten haben (40e49b1ebaaaa8655ba531b5c86f3bab48d191723d8d3ac220ae8dcc12326e07695d98 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.