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

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.

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}/…

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

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

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.