# Vorlagen per API

Eine **Vorlage** enthält Dokumente, Rollen, Felder und Platzhalter für wiederkehrende Vorgänge – zum Beispiel einen Mietvertrag mit den Rollen „Mieter“ und „Vermieter“. Aus einer veröffentlichten Version entsteht mit einem Aufruf ein Vorgang. Vorlagen haben keinen Modus: Test- und Live-Schlüssel nutzen dieselben Vorlagen; der Vorgang entsteht im Modus des Schlüssels.

Scopes: `templates:read` zum Lesen, `templates:write` zum Ändern (beide Standard an). Für Vorgänge aus Vorlagen brauchen Sie zusätzlich `envelopes:write`.

## 1. Vorlage anlegen

```http
POST /v1/templates
Authorization: Bearer qgw_test_…
Idempotency-Key: 7c2e…
Content-Type: application/json

{
  "name": "Mietvertrag Wohnung",
  "category": "REAL_ESTATE",
  "title": "Mietvertrag {{wohnung}}",
  "documents": [{ "documentId": "0192f1b0-…" }]
}
```

Die Antwort ist das Objekt `template` mit `state: "DRAFT"` und `draftVersionId` (Version 1 als Entwurf). Dokumente kommen wie bei Vorgängen als `documentId` (Upload von `POST /v1/documents`), `base64` oder `fileUrl`; sie werden als eigene Vorlagen-Dokumente gespeichert. Statt `documents` geht auch `fromEnvelopeId` („In Vorlage umwandeln“: Dokumente, Empfänger als Rollen und Felder eines Vorgangs, nie die eingegebenen Werte).

### Startvorlagen (Galerie)

Mit `galleryKey` statt `documents` entsteht eine Vorlage aus einer Startvorlage: Version 1 bringt Rollen, Felder, Platzhalter, Standardwerte und die Formvorschrift des Signatur-Checks mit, dazu ein neutrales **Musterdokument** („Musterdokument – bitte durch Ihren geprüften Text ersetzen“). Das Musterdokument enthält keinen Vertrags- oder Rechtstext; ersetzen Sie es vor dem Veröffentlichen durch Ihren geprüften Text.

```http
POST /v1/templates
Content-Type: application/json

{ "name": "Mietvertrag", "galleryKey": "residential_lease" }
```

Schlüssel: `residential_lease` (Immobilien), `nda` (Recht), `employment_contract` (Personal), `power_of_attorney` und `consent_media` (Verwaltung) sowie die Kategorie `HEALTHCARE` mit `health_information`, `health_consent`, `health_service_agreement`, `health_statement` und `health_private_order` (Aufbewahrung der Vorgänge 3650 Tage). Ein unbekannter Schlüssel ergibt 422 / 9012 mit `details.reason = gallery_key_unknown`. Die Liste mit Kategorie, Rollenanzahl und Formvorschrift zeigt das Dashboard unter „Vorlagen → Galerie“; eine eigene v1-Route dafür gibt es nicht.

## 2. Rollen, Platzhalter und Felder im Entwurf

Alle Änderungen gehen an den Entwurf: `/v1/templates/{id}/versions/{versionId}/…`

```http
POST /v1/templates/{id}/versions/{versionId}/roles
{ "key": "mieter", "label": "Mieter", "recipientRole": "SIGNER", "stage": 1, "position": 0 }

POST /v1/templates/{id}/versions/{versionId}/variables
{ "key": "wohnung", "label": "Wohnung", "type": "TEXT" }

PUT /v1/templates/{id}/versions/{versionId}/fields
{
  "revision": 3,
  "fields": [
    { "type": "SIGNATURE", "name": "unterschrift_mieter", "roleKey": "mieter",
      "documentIndex": 0, "page": 2, "x": 72, "y": 72, "width": 180, "height": 50 }
  ]
}
```

- Der Rollen-Schlüssel wird im Vorgang zum `recipientKey`.
- `PUT …/fields` ersetzt alle Felder. Senden Sie die `revision` der Version, die Sie zuletzt gelesen haben; hat sich der Entwurf inzwischen geändert, antwortet die API 409 / 9032 `version_conflict` mit `details.currentRevision`.
- Platzhalter schreiben Sie als `{{schlüssel}}` in Titel, Betreff, Nachricht oder Standardwerte von Textfeldern.

## 3. Version veröffentlichen

```http
POST /v1/templates/{id}/versions/{versionId}/publish
{ "revision": 5 }
```

Die API prüft die Vollständigkeit: jede Unterschreiben-Rolle hat ein Signaturfeld, alle Platzhalter sind bekannt, alle Felder liegen auf ihren Seiten. Fehlt etwas, kommt 422 / 9035 `TEMPLATE_INCOMPLETE` mit `details.missingRoles`, `unknownVariables` und `invalidFields` (nur Namen). Danach ist die Version unveränderlich; Änderungen beginnen mit einem neuen Entwurf (`POST /v1/templates/{id}/versions`). Die Antwort enthält `warnings`: Regeln, die beim Senden scheitern könnten (`source: "engine"`), und Hinweise des Signatur-Checks (`source: "legal"`). Es entsteht das Ereignis `template.version_published`.

## 4. Eingaben für Integrationen

`GET /v1/templates/{id}/schema` beschreibt, was ein Vorgang aus dieser Vorlage braucht: Rollen (feste Rollen nehmen keine Eingabe), Platzhalter, vorbelegbare Felder und `jsonSchema` – ein JSON Schema des Bodys von `POST …/envelopes`, erzeugt aus demselben Schema, mit dem die API den Body prüft. Werkzeuge wie Zapier oder Make bauen daraus ihre Eingabefelder.

## 5. Vorgang aus der Vorlage – erst prüfen, dann senden

```http
POST /v1/templates/{id}/envelopes?dryRun=true
Idempotency-Key: 41b9…

{
  "recipients": {
    "mieter": { "firstName": "Anna", "lastName": "Weber", "email": "anna.weber@example.com" }
  },
  "variables": { "wohnung": "Musterstraße 1" },
  "send": true
}
```

Mit `dryRun=true` antwortet die API mit `envelope_send_preview` (Prüfung und `costPreview`); es entsteht nichts. Ohne `dryRun` entsteht der Vorgang (`send: true` sendet sofort) und das Ereignis `envelope.created` mit `context.templateId`.

- Fehlt eine Pflichtrolle oder ein Pflicht-Platzhalter: 422 / 9035 mit `details.missingRoles` bzw. `missingVariables`.
- Rollen mit `useSender` brauchen per API ein Mitglied (`{ "memberId": "…" }`).
- **Signatur-Check** (Formvorschrift der Vorlage, keine Rechtsberatung): Verlangt die Form eine qualifizierte Signatur aller Unterzeichnenden, steht in der Vorschau die Warnung `legal_form_requires_qes`. Die Vorschau mit `dryRun` braucht keine Bestätigung und zeigt nur die Warnung. Senden Sie dann bewusst mit `"legalAcknowledged": true`; ohne Bestätigung antwortet die API bei `send: true` mit 422 / 9035 `legal_acknowledgement_required`. Vorlagen, deren Form elektronisch ausgeschlossen ist, ergeben immer 422 / 9035 `form_not_electronic`.

## 6. Archivieren

`DELETE /v1/templates/{id}` archiviert die Vorlage: keine neuen Vorgänge, laufende Vorgänge gehen weiter. Es entsteht einmal `template.archived`.