sproof Sign: Stapelsignatur (API)

Hallo Entwickler:in,

wir freuen uns, Ihnen eine nahtlose Integration unserer Signaturlösung in Ihre Anwendungen zu demonstrieren.

Dieser Anwendungsfall ermöglicht es Ihnen, den gesamten Signaturprozess innerhalb Ihres Systems zu steuern, wobei der:die Endbenutzer:in lediglich die finale Unterschrift auf seinem:ihrem Mobilgerät bestätigen muss und somit alle zuvor auf den Stapel gelegte Dokumente auf einmal unterzeichnen kann. Dies erreichen Sie durch die Kombination unserer plans/planmembers/, /documents/signature, /user/pendingSignatures und /documents/user/signBatch API-Endpunkte.

Für die Stapelsignatur ist es notwendig, dass der:die Anwender:in eine User+ Lizenz besitzt und seine:ihre Identität erfolgreich verifiziert wurde.

Um den Status eines:einer Benutzer:in zu überprüfen, können Sie den GET /plans/planmembers Endpunkt verwenden. Dieser Endpunkt liefert eine Liste aller Planmitglieder und deren Lizenzstatus sowie Identifikationsstatus.

1. Identifikationsstatus der Planmitglieder überprüfen

Endpunkt: GET https://sign.sproof.com/api/v1/plans/planmembers/list

Beispiel-Request:

GET https://sign.sproof.com/api/v1/plans/planmembers/list?token={{token}}

Erwartete Response-Struktur:

{
  "data": [
       {
      "email": "max.mustermann@sproof.com",
      "firstName": "Max",
      "lastName": "Mustermann",
      "identification": {
        "identifiedAt": "2025-07-30T12:12:33.844Z",
        "identificationStarted": true,
        "isIdentified": true
      },
      "blockedAt": null,
      "isPending": false,
      "userPlus": true,
      "lastLoginAt": "2025-07-31T12:36:28.844Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "lastPage": 1,
    "perPage": 1,
    "to": 1,
    "total": 1
  },
  "all": 1,
  "userPlus": 1,
  "user": 1
}

Um den Lizenz- und Identifikationsstatus eines:r spezifischen Benutzer:in zu überprüfen, durchsuchen Sie die zurückgegebene Liste nach der email des:der Benutzer:in. Stellen Sie sicher, dass userPlus und isIdentified auf true gesetzt sind.

Wenn die Prüfung erfolgreich ist, können Sie den:die Benutzer:in (in diesem Fall Max Mustermann) nahtlos durch den Prozess führen. Ist dies nicht der Fall, können Sie dem:der Benutzer:in entsprechende Hinweise geben (z.B. "Bitte schließen Sie den Identifikationsprozess ab").

2. Signaturanfrage erstellen (`createSignatureRequest`)

Zuerst erstellen Sie eine Signaturanfrage. Dies ist der erste Schritt, um ein Dokument für die Signatur vorzubereiten und grundlegende Informationen wie Absender und Empfänger zu definieren.

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

Beispiel-Body des Requests für ein Dokument:

{
  "token": "{{token}}",
  "inviteData": {
    "sender": {
      "email": "{{sender}}",
      "firstName": "{{sender_firstName}}",
      "lastName": "{{sender_lastName}}"
    },
    "recipients": [
      {
        "email": "max.mustermann@sproof.com",
        "firstName": "Max",
        "lastName": "Mustermann"
      }
    ],
  },
  "envelopeData": {
    "documentDataArray": [
      {
        "data": "{{pdf_im_base64_format}}",
        "fileName": "Ihr_Vertragsdokument.pdf",
        "recipientDetails": {
          "max.mustermann@sproof.com": {
            "role": "signer",
            "signaturePositions": [
              {"page": 0, "x": 0.57489, "y": 0.8455, "width": 0.35, "height": 0.1}
            ]
          }
        }
      }
    ]
  }
}

Wichtige Hinweise zum Request Body:

token: Ihr API-Token zur Authentifizierung.
sender.email: Die E-Mail-Adresse des:der Absender:in, die zu Ihrem Plan gehören muss.
recipients: Ein Array von Empfänger:innen. Für diesen Usecase ist es wichtig, dass der:die Empfänger:in mit der Rolle "signer" definiert wird.
envelopeData.documentDataArray.data: Ihr PDF-Dokument im Base64-Format.
envelopeData.documentDataArray.recipientDetails: Definiert die spezifischen Details pro Dokument für die Empfänger:innen, einschließlich der Signaturpositionen (wichtig für diesen Usecase).
callbackUrl: Ihre URL, an die sproof sign Status-Updates zum Dokument sendet. Dies ist essenziell für die asynchrone Verarbeitung.

Die Response auf diesen Request enthält wichtige IDs wie die memberId des:der zu Signierenden, die Sie für die weiteren Schritte benötigen.

3. Dokument zum Stapel hinzufügen (`addDocumentToStack`)

Nachdem die Signaturanfrage erstellt wurde, können Sie das Dokument zum Signaturstapel des:der Benutzer:in (in diesem Beispiel Max Mustermann) hinzufügen. Dieser User muss sich im selben Userplan befinden. Der Stapel ist eine temporäre Sammlung von Dokumenten, die ein Benutzer gesammelt signieren kann.

Endpunkt: POST https://sign.sproof.com/api/v1/user/pendingSignatures

Beispiel-Body des Requests:

{
  "token": "{{token}}",
  "memberId": "{{memberId_von_Max_Mustermann}}",
  "signatureType": "qes_sproof"
}

Wichtige Hinweise:

memberId: Die ID des zu signierenden Members, die Sie im vorherigen Schritt von createSignatureRequest erhalten haben (Max Mustermann in diesem Beispiel).
signatureType: qes_sproof: Die Stapelsignatur über die API funktioniert nur für QES-Unterschriften.

Nachdem das Dokument zum Stapel hinzugefügt wurde, wartet es auf die finale Unterschrift durch den Benutzer.

4. Stapelsignatur auslösen (`signBatch`)

Dieser Schritt ist der Kern des Usecases: Sie lösen die Signatur des gesamten Stapels des:der Benutzer:in aus. Dies führt dazu, dass der:die Benutzer:in auf seinem:ihrem Mobilgerät eine Benachrichtigung erhält, um die Unterschrift mit einem Klick zu bestätigen – alles andere wird im Hintergrund von sproof sign abgewickelt.

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

Beispiel-Body des Requests:

{
  "token": "{{token}}",
  "email": "max.mustermann@sproof.com"
}

Wichtige Hinweise:

Dieser Aufruf initiiert den Signaturprozess für alle Dokumente, die sich im Stapel des:der Benutzer:in (Max Mustermann in diesem Beispiel) befinden.
Der:die Benutzer:in erhält eine Push-Benachrichtigung auf seinem:ihrem Mobilgerät zur finalen Bestätigung.
Der callbackUrl, den Sie in createSignatureRequest angegeben haben, wird über den Status der Signatur informieren.

5. Callback-Benachrichtigungen empfangen und Dokument herunterladen

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": "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": "qes_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.

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