sproof Sign: Einholen von Signaturen (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 des Versendens eines Dokuments zur Signatur, das Empfangen von Status-Updates über einen Callback und das Herunterladen des signierten Dokuments.

1. Dokument zur Signatur senden

Um ein oder mehrere Dokumente zur Signatur zu versenden, verwenden Sie einen POST-Request an unseren signature-Endpunkt. Dieser setzt sich aus inviteData (allgemeine Informationen zur Einladung) und envelopeData (relevanten Daten pro Dokument) zusammen.

Wenn Sie mehrere Dokumente versenden, ist die Angabe des folderName notwendig, um die Dokumente in einer Dokumentenmappe zusammenzufassen. Da jedes Dokument unterschiedliche Konfigurationen haben kann, wie die Rolle des:der Empfänger:in im Dokument und die Signaturposition, ist es erforderlich, dass der:die gleiche Empfänger:in sowohl in inviteData.recipients mit den allgemeinen Einstellungen wie useFastlane oder doNotSendEmails als auch in envelopeData.documentDataArray.recipientDetails mit spezifischen Einstellungen angegeben wird. Jedes Dokument muss im Base64-Format vorliegen und wird in envelopeData.documentDataArray.data eingefügt.

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

Beispiel-Body des Requests für ein Dokument:

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

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.
Die callbackUrl ist Ihre URL, an die wir Status-Updates senden werden.

2. Callback-Benachrichtigungen empfangen

Sobald ein Dokument signiert wird oder ein:eine 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": "important_contract",
  "id": "8925b941ea322b82a246a19c6f5d29d3ee457a83cb679eaa008c2c7707a574a8cd1937",
  "language": "en",
  "updatedAt": "2025-07-23T14:03:02.854Z",
  "createdAt": "2025-07-23T14:02:41.082Z",
  "signaturesTypes": [],
  "callbackUrl": "https://webhook.site/ihre-eigene-callback-url",
  "returnUrl": null,
  "returnBtnText": null,
  "inPersonSigning": false,
  "signingRound": 1,
  "member": {
    "id": "32106bfe541f3a99525097e956eb9624f0852cb3b4d3201ae2d647c9b5fe4b131de626",
    "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": "3f14fd13d6e4f7981b86a9b476426a97ede88ee6921f24b221e7d97bfce660f2430b8d",
      "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.

3. Signiertes Dokument herunterladen

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