← LumenSign API reference

QES für Plattformen mit vielen Signaturen je Person

Ihre Plattform lässt Personen mit eigenem qualifiziertem Zertifikat viele Dokumente signieren – Bestätigungen, Bescheinigungen, Verträge –, oft Dutzende am Tag und ohne dass die Person bei jeder Unterschrift vor dem Bildschirm sitzt. Dieser Guide beschreibt den Weg mit automatischen Zertifikaten: einmal einrichten, danach signiert Ihr System per API, und zwar nur im Rahmen der Einwilligung, die die Person selbst erteilt hat.

Grundlagen zu Mitgliedern, Zertifikaten und Freigabe-Links stehen im Guide „QES mit Mitgliedern und Freigabe-Link“. Mit einem Test-Schlüssel (qgw_test_…) läuft jeder Schritt im Testmodus, ohne Kosten.

Überblick

  1. Mitglied anlegen – die Person, die signiert.
  2. Automatisches Zertifikat bestellen; die Person identifiziert sich einmal.
  3. Einwilligung zum automatischen Signieren anfragen; die Person legt den Rahmen fest.
  4. Zugangsdaten hinterlegen und testen.
  5. Signieren mit certificateId – einzeln oder im Stapel.
  6. Ergebnis per Webhook empfangen, signiertes Dokument und Nachweis abrufen.

1. Mitglied anlegen

POST /v1/members
Authorization: Bearer qgw_test_…
Idempotency-Key: mitglied-0815
Content-Type: application/json

{ "firstName": "Erika", "lastName": "Mustermann", "email": "erika.mustermann@example.com", "externalId": "person-0815" }

externalId ist Ihre Kennung der Person, damit Sie sie später zuordnen. Scope members:manage.

2. Automatisches Zertifikat bestellen

POST /v1/certificates
Authorization: Bearer qgw_test_…
Idempotency-Key: zertifikat-0815
Content-Type: application/json

{ "memberId": "0192f1b0-0000-7000-8000-00000000010f", "kind": "AUTOMATIC" }

Scope certificates:purchase. Die Antwort enthält identificationUrl: Die Person identifiziert sich einmalig über diesen Link (sie bekommt ihn auch per E-Mail). Den Stand zeigt GET /v1/certificates/{id} (lifecycleState). Warten Sie hier nicht auf certificate.activated: Dieses Ereignis kommt erst nach dem erfolgreichen Test der Zugangsdaten in Schritt 4, der wiederum die Einwilligung aus Schritt 3 voraussetzt. Fragen Sie die Einwilligung gleich nach der Bestellung an.

3. Einwilligung anfragen

Ein automatisches Zertifikat signiert mit certificateId nur, wenn die Person zugestimmt hat. Ihre Plattform fragt die Einwilligung an, erteilen kann sie nur die Person selbst:

POST /v1/certificates/0192f1b0-0000-7000-8000-00000000010e/consent-request
Authorization: Bearer qgw_test_…
Idempotency-Key: einwilligung-0815
Content-Type: application/json

{ "scope": { "channels": ["API", "BATCH"], "apiKeyIds": ["0192f1b0-0000-7000-8000-000000000201"], "dailyLimit": 200, "validUntil": "2027-12-31T23:00:00Z" } }

Die Antwort ist immer 202 (object: automatic_consent_request). Die Person bekommt eine E-Mail mit einem persönlichen Link (72 Stunden gültig), erteilt oder lehnt dort ab und kann die Einwilligung jederzeit widerrufen oder sofort sperren. Änderungen meldet das Ereignis certificate.consent_changed (Scope certificates:read). Eine neue Anfrage ersetzt eine offene.

4. Zugangsdaten hinterlegen und testen

PUT /v1/certificates/{id}/credentials speichert Benutzername und PIN des Zertifikats verschlüsselt – nur, solange eine gültige Einwilligung besteht (sonst 403 / 9006 automatic_consent_missing). Danach prüft POST /v1/certificates/{id}/test die Zugangsdaten mit einer Testsignatur; ist der Test erfolgreich, ist das Zertifikat bereit und das Ereignis certificate.activated folgt. Im Testmodus hinterlegt POST /v1/certificates/{id}/sandbox-credentials die Zugangsdaten der Sandbox. Ab jetzt nennt Ihr System nur noch die certificateId; die PIN muss es nicht aufbewahren.

5. Signieren

Einzelnes Dokument

POST /v1/signatures
Authorization: Bearer qgw_test_…
Idempotency-Key: bestaetigung-0815
Content-Type: application/json

{
  "inputDocuments": [{ "sourceType": "base64", "payload": "<PDF als Base64>", "name": "bestaetigung-0815.pdf" }],
  "certificateId": "0192f1b0-0000-7000-8000-00000000010e",
  "signatureType": "pades",
  "options": { "level": "B" },
  "placement": { "page": 1, "x": 391, "y": 36, "width": 168, "height": 39 },
  "appearance": { "showDate": true, "reason": "Bestätigung 0815" },
  "externalId": "bestaetigung-0815",
  "metadata": { "vorgang": "0815" }
}

Ungültige Dokumente und Ablehnungen

Antwort, Wartezeit und Wiederholungen

Viele Dokumente auf einmal: Stapel

Laden Sie die Dokumente hoch (POST /v1/documents/import mit base64 oder fileUrl) und signieren Sie sie in einem Aufruf:

POST /v1/signature-batches
Authorization: Bearer qgw_test_…
Idempotency-Key: stapel-2026-11-03
Content-Type: application/json

{
  "certificateId": "0192f1b0-0000-7000-8000-00000000010e",
  "title": "Bescheinigungen 3. November",
  "placement": { "page": "last", "x": 380, "y": 60, "width": 168, "height": 39 },
  "appearance": { "showDate": true, "reason": "Bescheinigung" },
  "documents": [
    { "documentId": "0192f1b0-0000-7000-8000-000000000103", "title": "Bescheinigung 0815" },
    { "documentId": "0192f1b0-0000-7000-8000-000000000104", "title": "Bescheinigung 0816" }
  ]
}

Die Antwort kommt sofort (202) mit einer Signatur-ID je Dokument; signiert wird im Hintergrund. Ein Stapel ist der Kanal BATCH und zählt jedes Dokument gegen das Tageslimit der Einwilligung. Wenn alles fertig ist, kommt signature_batch.completed; GET /v1/signature-batches/{id}/archive liefert alle signierten Dokumente als ZIP. Stapel müssen für Ihre Organisation freigeschaltet sein (sonst 403 / 9023).

Bis zu 250 Dokumente mit einer Freigabe

Ein Stapel nimmt bis zu 250 Dokumente (die Grenze Ihres Tarifs; Standard 50, mehr auf Anfrage) und wird mit einem Aufruf freigegeben, im Dashboard mit einer Bestätigung. Mehr als die Grenze: 422 / 9012 batch_too_large mit details.max.

6. Ergebnis empfangen

Ein Webhook-Abo meldet jedes Ergebnis, ohne dass Ihre Plattform abfragt:

POST /v1/webhook-subscriptions
Authorization: Bearer qgw_test_…
Content-Type: application/json

{ "url": "https://example.com/hooks/signatures", "events": ["signature.completed", "signature.failed", "signature_batch.completed"] }

signature.completed enthält Ihre externalId und metadata sowie Links auf das signierte Dokument und den Nachweis. Abrufen können Sie beides auch direkt:

Wie Sie die Signatur der Webhooks prüfen, zeigt der Guide „Webhooks empfangen und prüfen“.

Hinweise