Quickstart: Erster Vorgang mit zwei Unterzeichnern

In fünf Schritten verschicken Sie ein PDF an zwei Personen zur Unterschrift, erfahren per Webhook, wann beide fertig sind, und laden das unterschriebene Dokument herunter. Alle Beispiele nutzen einen Test-Schlüssel: Im Testmodus wird nichts berechnet, und mit den Adressen aus dem Guide „Sandbox-Szenarien“ unterschreiben die Empfänger sogar von selbst.

Grundlagen, die für jede Route gelten:

• Basis-URL: die Adresse der API (in den Beispielen $BASE_URL), Schlüssel als Authorization: Bearer $KEY.
• Antworten sind das Objekt selbst (mit object, z. B. envelope), Listen { data, hasMore, nextCursor }, Fehler { error: { code, type, message, details, requestId } }.
• Schreibende Aufrufe nehmen einen Idempotency-Key: Wiederholen Sie einen Aufruf mit demselben Schlüssel und demselben Body, bekommen Sie die gespeicherte Antwort statt eines zweiten Vorgangs.
• Zeitlimit Ihres Clients: mindestens 30 Sekunden. POST /v1/signatures antwortet in der Regel innerhalb von 25 Sekunden (gezählt ab Eingang; die Vorbereitung großer Dokumente zählt mit und wird nicht abgebrochen), fertig (200) oder mit 202 status: WAIT_SIGN und Retry-After; das Ergebnis kommt dann per Webhook oder GET /v1/signatures/{id} (Guide „QES mit Mitgliedern“, Abschnitt „Antwortzeit und Wiederholungen“).

1. Schlüssel prüfen

Legen Sie im Dashboard unter Entwickler → API-Schlüssel einen Test-Schlüssel an (qgw_test_…). Für diesen Guide braucht er die Scopes envelopes:read, envelopes:write und webhooks:manage.

curl "$BASE_URL/v1/me" -H "Authorization: Bearer $KEY"

GET /v1/me zeigt Organisation, Modus (TEST), Scopes und Rate-Limits des Schlüssels.

2. Webhook-Abo anlegen

Damit Sie nicht abfragen müssen, abonnieren Sie die Ereignisse der Vorgänge:

curl -X POST "$BASE_URL/v1/webhook-subscriptions" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: quickstart-abo-1' \
  -d '{ "url": "https://example.com/hooks/signatur", "events": ["envelope.*", "recipient.*"] }'

Die Antwort enthält secret (whsec_…) – nur dieses eine Mal. Speichern Sie es; damit prüfen Sie die Signatur jeder Zustellung (siehe Guide „Webhooks empfangen und prüfen“). Ein Test-Schlüssel legt ein Abo im Testmodus an, das nur Test-Ereignisse bekommt.

3. Vorgang anlegen und senden

Ein Vorgang bündelt Dokumente, Empfänger und Felder. Mit send: true wird er in einem Aufruf angelegt und verschickt:

curl -X POST "$BASE_URL/v1/envelopes" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: quickstart-vorgang-1' \
  -d '{
    "title": "Mietvertrag Musterstraße 1",
    "externalId": "crm-4711",
    "expiresInDays": 14,
    "signingOrder": "SEQUENTIAL",
    "documents": [{ "name": "Mietvertrag.pdf", "base64": "JVBERi0xLjcK…" }],
    "recipients": [
      { "recipientKey": "mieterin", "role": "SIGNER", "firstName": "Anna", "lastName": "Weber",
        "email": "anna.weber@example.com", "signatureLevel": "SES" },
      { "recipientKey": "vermieter", "role": "SIGNER", "firstName": "Jonas", "lastName": "Keller",
        "email": "jonas.keller@example.com", "signatureLevel": "SES" }
    ],
    "send": true
  }'

• base64 nimmt PDFs bis 11 MB (Länge des Base64-Texts). Größere Dateien laden Sie vorher mit POST /v1/documents hoch oder geben eine fileUrl an; dann steht im Dokument documentId bzw. fileUrl statt base64.
• Ohne Felder bekommt jeder Unterzeichner ein Unterschriftsfeld auf der letzten Seite. Eigene Felder setzen Sie mit fields (Seite und Rechteck in PDF-Punkten).
• signingOrder: SEQUENTIAL lädt die zweite Person erst ein, wenn die erste fertig ist; PARALLEL lädt beide sofort ein.
• signatureLevel ist hier die einfache elektronische Signatur (SES). In der Oberfläche heißen die Stufen EES (SES), FES (AES) und QES. AES (fortgeschritten) und QES (qualifiziert) wählen Sie je Empfänger; eine QES ist nur für Mitglieder Ihrer Organisation mit Zertifikat möglich (Guide „QES mit Mitgliedern und Freigabe-Link“). Die eigene einfache Signatur (Unterschrift mit Einmalcode direkt auf unserer Signierseite) steht derzeit nur im Testmodus zur Verfügung.

Wollen Sie vor dem Senden sehen, ob alles passt und was es kostet, senden Sie denselben Body an POST /v1/envelopes?dryRun=true: Die Antwort ist eine Vorschau (envelope_send_preview mit valid, errors, warnings und costPreview), es wird nichts angelegt.

Alternativ legen Sie zuerst einen Entwurf an (ohne send), ergänzen ihn mit POST /v1/envelopes/{id}/recipients, POST /v1/envelopes/{id}/documents und POST /v1/envelopes/{id}/fields und senden ihn dann mit POST /v1/envelopes/{id}/send.

4. Auf Ereignisse reagieren

Ihr Endpunkt bekommt nacheinander unter anderem:

Jedes Ereignis trägt in context die envelopeId und Ihre externalId, in data das Objekt wie bei GET /v1/envelopes/{id}. Antworten Sie schnell mit 2xx und verarbeiten Sie im Hintergrund. Den aktuellen Stand lesen Sie jederzeit mit GET /v1/envelopes/{id}, die Zeitleiste mit GET /v1/envelopes/{id}/events.

Ohne Webhook-Endpunkt (etwa beim Ausprobieren) fragen Sie GET /v1/events ab: Dort stehen die Ereignisse der letzten 30 Tage, neueste zuerst.

5. Ergebnis herunterladen

Nach envelope.completed:

curl -o Mietvertrag-signiert.pdf "$BASE_URL/v1/envelopes/$ENVELOPE_ID/documents/final" \
  -H "Authorization: Bearer $KEY"
curl -o Nachweis.pdf "$BASE_URL/v1/envelopes/$ENVELOPE_ID/audit-trail" \
  -H "Authorization: Bearer $KEY" -H 'Accept: application/pdf'

GET /v1/envelopes/{id}/documents/final liefert das fertige PDF (mit ?format=base64 als JSON-Objekt file), GET /v1/envelopes/{id}/audit-trail das Nachweisprotokoll als JSON oder, mit Accept: application/pdf, als PDF. Für Systeme ohne API-Schlüssel erzeugt POST /v1/envelopes/{id}/download-links Links, die 15 Minuten gelten.

Wie geht es weiter?

• Wiederkehrende Dokumente: Guide „Vorlage → Vorgang“.
• Testabläufe ohne echte Personen: Guide „Sandbox-Szenarien“.
• Kosten vorab: Guide „Kosten per API“.
• Alle Routen, Felder und Fehlercodes: die API-Referenz unter /docs.