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.

Mit diesem Endpoint können Sie Signaturanfragen versenden, bei denen ein dynamisches Dokument mit einem vorkonfigurierten Workflow zusammengeführt wird.

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 mit diesem Endpoint nur für einzelne Dokumente. Für Dokumentenmappen steht ein separater Endpoint zu Verfügung.

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. Einstellungen für die Personen-Platzhalter wie Rolle am Dokument, Signaturtyp oder Reihenfolge können hier getroffen werden. Jedem Platzhalter wird ein Index zugewiesen (beginnend bei 1). Wenn Sie den API-Request senden, verweist index: 1 auf den ersten Personen-Platzhalter, den Sie in der Benutzeroberfläche erstellt haben. Die Signaturposition wird dynamisch im Dokument selbst definiert (siehe Schritt 2).

Weitere Einstellungen: Auch andere Einstellungen wie E-Mail-Einstellungen, Erinnerungen und Fälligkeit können hier im Workflow 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 dritten Schritt benötigt.

2. Dynamisches Dokument vorbereiten

Bevor Sie den API-Request senden, müssen Sie das PDF-Dokument vorbereiten, das unterzeichnet werden soll. Anstatt mit festen Koordinaten zu arbeiten, nutzt unser System sogenannte Text-Anker.

Platzhalter-Text: Platzieren Sie eine eindeutige Textzeichenfolge an der Stelle, an der die Signatur erscheinen soll (z. B. {{signer1}}).
Formatierung: Sie können die Textfarbe auf Weiß setzen oder die Schriftgröße minimieren, um den Platzhalter unsichtbar zu machen. Wichtig ist jedoch, dass der Text im PDF weiterhin „auswählbar“ (technisch lesbar) bleibt.
Dynamische Erstellung: Sie können diese Dokumente „on the fly“ generieren und den Platzhalter-Text {{signer1}} an jeder beliebigen Stelle platzieren.

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

Sobald Sie Ihre workflowId und das vorbereitete Dokument bereit haben, können Sie die Signaturanfrage starten. Je nachdem, ob Sie die Einladungen sofort versenden möchten oder das Dokument zuerst im sproof UI als Entwurf bearbeiten wollen, stehen Ihnen zwei verschiedene Endpunkte zur Verfügung:

Die Wahl des richtigen Endpunkts

Sofortiger Versand: Verwenden Sie /invite-recipients-with-workflow, wenn die Einladungs-E-Mails direkt nach dem API-Call an alle Empfänger (entsprechend der Workflow-Reihenfolge) versandt werden sollen.
Vorbereitung als Entwurf: Verwenden Sie /prepare-recipients-with-workflow, wenn das Dokument lediglich vorbereitet werden soll. Das Dokument erscheint dann im sproof Dashboard des Users als Entwurf. Zusätzlich können Sie die in der API-Response gelieferte editorUrl nutzen, um den User direkt in den Editor zu leiten. So können im UI noch letzte Anpassungen vorgenommen und der Versand manuell gestartet werden.

Die Merging-Logik

Dieser Prozess führt einen Drei-Wege-Merge aus: Er kombiniert Ihre API-Empfängerdaten, die Signaturpositionen im Dokument und die Einstellungen aus Ihrem Workflow. Jedes Objekt im recipients-Array verknüpft diese Komponenten über zwei Identifikatoren:

Die Dokument-Verknüpfung (placeholderText): Ordnet den Empfänger einer spezifischen Textzeichenfolge (z. B. {{signer1}}) in Ihrem PDF zu, um die Signaturposition festzulegen.
Die Workflow-Verknüpfung (index): Verknüpft den Empfänger mit einem „Personen-Platzhalter“ aus Ihrem UI-Workflow. Dadurch wird sichergestellt, dass der Empfänger die korrekte Rolle, Reihenfolge und den richtigen Signaturtyp erbt.

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

oder

Endpunkt: POST https://sign.sproof.com/api/v1/documents/prepare-recipients-with-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",
      "placeholderText": "{{signer1}}",
      "index": 1
    }
  ]
}

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.
- placeholderText: Der Text-Identifikator, mit dem dieser Empfänger der im Dokument festgelegten Signaturposition zugeordnet wird (z. B. {{signer1}}).
- index: Der Positions-Index des Platzhalters im Workflow (beginnend bei 1). Dies stellt sicher, dass der Empfänger die im UI definierten Einstellungen (Rolle, Signaturtyp etc.) erhält.

4. 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.

5. 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.