Sessions

Session erstellen – der erste Schritt zur Formulareinbettung.

Eine Session kapselt alle Einstellungen (Vorlage, Webhooks, Redirect, E-Mail, eigene Kennung) und gibt eine sichere Session-ID zurück.

Session erstellen

POST /api/embed/sessions

Request-Body

{
  "token": "sk_dev_abc123...",
  "orgId": "550e8400-e29b-41d4-a716-...",
  "templateIdentifier": "anoXYZ1234",
  "config": {
    "rnummer": "auftrag-456",
    "draftKey": "kunde-789",
    "webhookUrl": "https://hook.example.com",
    "redirectUrl": "https://example.com/danke",
    "email": "team@firma.de"
  },
  "expiresInHours": 24
}

Feld	Typ	Pflicht	Beschreibung
`token`	`string`	Ja	API-Token aus dem Dashboard
`orgId`	`string`	Ja	Organisations-UUID
`templateIdentifier`	`string`	Ja	Vorlage-ID
`config.rnummer`	`string`	Nein	Eigene Kennung für den Vorgang
`config.draftKey`	`string`	Nein	Schlüssel zum Wiederherstellen eines Entwurfs
`config.webhookUrl`	`string`	Nein	Webhook-URL für diese Session
`config.redirectUrl`	`string`	Nein	Weiterleitung nach Absenden
`config.email`	`string`	Nein	E-Mail-Benachrichtigung bei fertigem Formular
`expiresInHours`	`number`	Nein	Ablaufzeit in Stunden (Standard: kein Ablauf)

Erfolgs-Antwort (201)

{
  "sessionId": "a1b2c3d4-...",
  "embedUrl": "https://app.de/embed/form?s=a1b2c3d4-...",
  "embedCode": "<iframe src=\"https://app.de/embed/form?s=a1b2c3d4-...\" ...></iframe>",
  "createdAt": "2026-02-23T14:00:00.000Z",
  "expiresAt": "2026-02-24T14:00:00.000Z"
}

embedCode kann direkt in HTML eingefügt werden
embedUrl ist die reine iframe-URL
expiresAt ist null, wenn kein Ablauf gesetzt wurde

Fehlerfälle

Code	Bedeutung
`400`	Fehlende Pflichtfelder oder ungültige Werte
`401`	Token ungültig oder passt nicht zur `orgId`
`404`	Vorlage mit dieser `templateIdentifier` nicht gefunden

Feldtypen-Referenz iframe-Einbettung