# 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`.

```sh
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:

```sh
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:

```sh
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:

| Ereignis | Bedeutung |
| --- | --- |
| `envelope.sent` | Der Vorgang wurde verschickt. |
| `recipient.notified` | Eine Person ist an der Reihe, die Einladung ist unterwegs. |
| `recipient.signed` | Eine Person hat unterschrieben. |
| `envelope.completed` | Alle sind fertig; das fertige PDF und das Nachweisprotokoll liegen bereit. |

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`:

```sh
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`.