sproof Sign: Vorbereiten von Signaturanfragen (API)

Hallo Entwickler:in,

oftmals ist es notwendig, Dokumente programmatisch vorzubereiten, ohne sie sofort an die Empfänger:innen zu versenden. In diesem Modul lernen Sie, wie Sie Dokumente vorab erstellen, während diese sicher im Entwurfsstatus verbleiben. Dies ermöglicht es Ihnen oder Ihren Nutzer:innen, in der sproof UI den letzten Schliff vorzunehmen, bevor die Einladungen final versendet werden.

1. Dokumente vorbereiten (ohne Versand)

Wenn Sie diesen Endpunkt ansprechen, wird das Dokument erstellt und alle übergebenen Daten werden hinterlegt. Der Prozess pausiert jedoch im Status "Entwurf". Es werden zu diesem Zeitpunkt keine E-Mails an die Empfänger:innen versendet.

Flexibilität bei der Signaturplatzierung: Sie können die signaturePositions bereits im API-Request definieren oder das Feld als leeres Array [] übergeben. Letzteres ist ideal, wenn die Signaturpositionen oder zusätzliche Formularfelder erst nachträglich durch einen User visuell in der sproof UI platziert werden sollen.

Endpunkt: POST https://sign.sproof.com/api/v1/documents/prepare

Beispiel-Body des Requests (gleich wie bei documents/signature Endpunkt):

JSON

{
  "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}
            ]
          }
        }
      }
    ]
  }
}

2. Nahtloser Übergang in die sproof UI

Nach dem erfolgreichen Request erhalten Sie eine Antwort im gleichen Format wie beim /signature-Endpunkt. Da sich das Dokument im Entwurfsstatus befindet und noch keine aktiven Einladungen an die Empfänger:innen versendet wurden, ist das Array members (die Liste der eingeladenen Personen) leer.

Das Dokument wurde in diesem Schritt exklusiv für den Sender erstellt. Das zurückgegebene member-Objekt enthält die Identität des Senders, die Sie benötigen, um das Dokument für die weitere Bearbeitung anzusprechen.

Beispiel für das Response-Objekt:

{
    "documents": [
        {
            "id": "c4507aa87823fc1bc9ae181c24a27ccc9a20a04c3373bd0a745e63b8d4bdbb4885a148",
            "name": "wichtiger_vertrag",
            //...additional properties truncated
            "members": [],
            "member": {
                "id": "a395ae0985350956ffae7ce01f09e292bb5d5474f65c60f22d915823aaea5c17f71bdd",
                "documentId": "c4507aa87823fc1bc9ae181c24a27ccc9a20a04c3373bd0a745e63b8d4bdbb4885a148",
                "email": "sender@sproof.com",
                "firstName": "sproof",
                "lastName": "Sender",
                "isAdmin": true,
                //...additional properties truncated
            }
        }
    ]
}

Dashboard-Ansicht: Das Dokument erscheint im sproof-Dashboard des senders. Hier können Sie es jederzeit manuell öffnen.
Direkte Weiterleitung: Nutzen Sie die member.id aus der API-Antwort, um Ihre Nutzer:innen direkt aus Ihrer eigenen Anwendung in den sproof-Editor zu leiten. Der Link dafür folgt diesem Schema: https://sign.sproof.com/editor/{{memberId}}
Manuelle Veredelung: Im Editor können nun letzte Anpassungen vorgenommen werden – wie das Platzieren von Formularfeldern oder das Verschieben von Signaturpositionen – bevor das Dokument mit einem Klick auf "Einladung senden" final freigegeben wird.
Finaler Versand: Sobald das Dokument in der UI final ausgesendet wird, löst sproof den E-Mail-Versand an alle Empfänger:innen aus. Falls Sie im ursprünglichen Request eine callbackUrl definiert haben, erhalten Sie ab diesem Moment wie gewohnt Status-Updates über den Fortschritt der Signaturen.

Wir wünschen Ihnen viel Erfolg bei der Integration!