Formular → Eingang → Vorgang

Mit Formularen sammeln Sie Angaben über einen Link oder eine eingebettete Seite – etwa einen Antrag oder eine Kündigung. Jede abgesendete Antwort ist ein Eingang (form_submission). Aus einem Eingang wird auf Wunsch ein Vorgang, in dem die Person das Ergebnis unterschreibt.

Scopes: forms:read und forms:write für Formulare, submissions:read für Eingänge, envelopes:write für das Weiterleiten in einen Vorgang.

1. Formular anlegen und veröffentlichen

Die Felder eines Formulars bauen Sie am bequemsten im Dashboard im Formular-Editor. Per API geht es so:

POST /v1/forms
Authorization: Bearer qgw_test_…
Idempotency-Key: 3f1c…
Content-Type: application/json

{ "name": "Antrag Anwohnerparkausweis", "slug": "anwohnerparkausweis", "externalId": "antrag-12" }

Ohne schema entsteht ein Entwurf mit einer leeren Seite; das vollständige Formular-Schema (Seiten, Eingaben, Bedingungen) beschreibt die API-Referenz bei POST /v1/forms. Änderungen gehen an die Entwurfsversion (PATCH /v1/forms/{id}/versions/{versionId}).

Veröffentlichen:

POST /v1/forms/{id}/publish?dryRun=true

Mit dryRun=true sehen Sie die Prüfung (form_publish_preview), ohne etwas zu ändern. Im Live-Modus braucht ein Formular einen Link zu Datenschutz und Impressum (aus dem Formular, dem Markenprofil oder der Organisation). Ohne dryRun wird das Formular veröffentlicht (PUBLISHED), und das Ereignis form.published folgt.

Den Link und den Code zum Einbetten liefert GET /v1/forms/{id}/embed; vorbelegte Links erzeugt POST /v1/forms/{id}/prefill-links (Details im Guide „Formular einbetten und vorausfüllen“).

2. Eingänge empfangen

Abonnieren Sie die Ereignisse der Eingänge (Webhook-Abo mit submission.*, Scope submissions:read):

Ereignis	Bedeutung
`submission.started`	Jemand hat begonnen, das Formular auszufüllen.
`submission.submitted`	Der Eingang wurde abgesendet.
`submission.completed`	Der Eingang ist fertig: PDF erzeugt, unterschrieben, wenn das Formular eine Unterschrift verlangt.
`submission.cancelled`	Die Unterschrift wurde abgelehnt, abgebrochen oder ist gescheitert.
`submission.expired`	Der Eingang ist verfallen.

Die eingegebenen Werte stehen nicht im Ereignis. Lesen Sie den Eingang mit GET /v1/submissions/{id} (Feld values); jedes Lesen mit Werten steht im Aktivitätsprotokoll Ihrer Organisation. Listen gibt es mit GET /v1/submissions (alle Formulare) und GET /v1/forms/{id}/submissions (ein Formular, mit Filtern auf Auswahlfelder). Das Schema der Werte für Ihre Integration liefert GET /v1/forms/{id}/schema (valuesJsonSchema).

Dateien und Nachweise:

GET /v1/submissions/{id}/pdf – das PDF des Eingangs,
GET /v1/submissions/{id}/files/{fileId}/content – eine hochgeladene Datei,
GET /v1/submissions/{id}/evidence – der Nachweis des Eingangs.

3. Aus dem Eingang einen Vorgang machen

Soll die Person das Ergebnis unterschreiben, gibt es zwei Wege:

Automatisch: Im Formular legen Sie eine Vorlage für die Unterschrift fest (settings.signature). Nach dem Absenden entsteht der Vorgang von selbst; submission.completed kommt, wenn unterschrieben ist.
Per Aufruf: Sie leiten einen abgesendeten Eingang selbst weiter – etwa erst nach einer Prüfung durch Ihr Team:

POST /v1/submissions/{id}/envelope
Authorization: Bearer qgw_test_…
Idempotency-Key: 9a4d…
Content-Type: application/json

{
  "templateVersionId": "0192f1b0-0000-7000-8000-000000000105",
  "roles": [
    { "roleKey": "antragsteller", "source": "SUBMITTER", "emailFieldKey": "email", "nameFieldKeys": ["vorname", "nachname"] },
    { "roleKey": "sachbearbeitung", "source": "MEMBER", "memberId": "0192f1b0-0000-7000-8000-00000000010f" }
  ],
  "variables": { "kennzeichen": "kennzeichen" },
  "level": "SES"
}

templateVersionId ist eine veröffentlichte Version einer Vorlage (Guide „Vorlage → Vorgang“).
roles ordnet jede Rolle der Vorlage zu: der Person, die das Formular ausgefüllt hat (SUBMITTER, Name und E-Mail aus den Eingaben), einem Mitglied (MEMBER) oder einer festen Person (FIXED).
variables füllt Platzhalter der Vorlage mit Eingaben des Formulars.
Die ausfüllende Person unterschreibt mit SES oder AES; eine qualifizierte Signatur ist für sie nicht möglich (422 / 9027).
Mit ?dryRun=true sehen Sie Prüfung und Kosten, ohne dass etwas entsteht. Fehlt eine Zuordnung, antwortet die API mit 422 / 9035 und nennt Rollen und Platzhalter.

Der neue Vorgang ist ein ganz normaler Vorgang: Er schickt die Ereignisse envelope.* und recipient.*, und envelopeId steht danach im Eingang.