Ticket-Eingang

Der Ticket-Eingang nimmt Meldungen von außerhalb an — aus dem Kontaktformular einer Kundenseite, aus einer App oder von einem Server. Alle drei Wege legen einen Vorgang im zugehörigen Projekt an, mit der Antwortfrist aus dem Vertrag des Kunden.

Dazu kommen E-Mail und Monitore — weiter unten.

Vor dem Einrichten: Wer über das Formular oder die App schreibt, gibt personenbezogene Daten an dich und damit an VentionDesk als Dienstleister. Richte den Eingang für eine Kundenseite erst ein, wenn der Vertrag zur Auftragsverarbeitung mit deinem Kunden steht, und weise auf der Seite darauf hin — der Formular-Code unten enthält dafür einen Satz mit Link auf die Datenschutzerklärung deines Kunden.

Öffentlichen Schlüssel und Herkünfte einrichten

In der Projektakte, Reiter Übersicht, Karte „Öffentlicher Ticket-Eingang" (nur Inhaber):

1. „Eingang einrichten" erzeugt den öffentlichen Schlüssel vd_pub_…. „Kopieren" legt ihn in die Zwischenablage.
2. Unter „Erlaubte Herkünfte" trägst du jede Adresse ein, von der Browser-Meldungen kommen dürfen — nur Schema, Host und Port, also https://kunde.de, ohne Pfad und ohne Schrägstrich am Ende. VentionDesk vergleicht wörtlich.
3. Ohne eingetragene Herkunft nimmt der Browser-Weg nichts an. Das HTML-Formular und der Server-Weg sind davon nicht betroffen.
4. „Eingang abschalten" entfernt den Schlüssel wieder.

Der öffentliche Schlüssel ist nicht geheim — er steht im Quelltext der Kundenseite. Er kann nur Vorgänge in genau diesem Projekt anlegen.

Weg 1: HTML-Formular

Ein gewöhnliches Formular, das an https://in.ventiondesk.com/f/<öffentlicher Schlüssel> sendet. Den fertigen Code kopierst du in VentionDesk unter Tickets › „?" › „Formular-Code kopieren":

<form method="post" action="https://in.ventiondesk.com/f/DEIN_PUBLIC_KEY">
  <input name="name" placeholder="Ihr Name" required />
  <input name="email" type="email" placeholder="Ihre E-Mail" required />
  <input name="subject" placeholder="Betreff" required />
  <textarea name="message" placeholder="Ihre Nachricht" required></textarea>
  <p>Mit dem Absenden werden Ihre Angaben zur Bearbeitung an unseren Dienstleister
    übermittelt. Mehr dazu in unserer <a href="DEINE_DATENSCHUTZERKLAERUNG">Datenschutzerklärung</a>.</p>
  <button type="submit">Absenden</button>
</form>

Ersetze DEIN_PUBLIC_KEY durch den öffentlichen Schlüssel und DEINE_DATENSCHUTZERKLAERUNG durch die Datenschutzerklärung der Kundenseite.

Optional:

• _redirect — eine absolute Adresse, auf die der Browser nach dem Absenden weitergeleitet wird (303). Ihre Herkunft muss unter „Erlaubte Herkünfte" stehen, sonst antwortet VentionDesk mit JSON.
• _hp — ein Honigtopf gegen Bots: ein verstecktes, leeres Feld. Ist es ausgefüllt, antwortet VentionDesk freundlich und legt nichts an.
• cf-turnstile-response — das Token von Cloudflare Turnstile, siehe unten.

Ohne _redirect antwortet VentionDesk mit 201 und { "ok": true, "ticket": { "id": "…", "key": "TK-1044" } }.

Weg 2: Meldung aus dem Browser

POST https://api.ventiondesk.com/v1/intake/reports mit dem öffentlichen Schlüssel im Kopf x-ventiondesk-key — aus einer Web-App, deren Herkunft unter „Erlaubte Herkünfte" steht:

await fetch('https://api.ventiondesk.com/v1/intake/reports', {
  method: 'POST',
  headers: { 'content-type': 'application/json', 'x-ventiondesk-key': 'vd_pub_…' },
  body: JSON.stringify({
    text: 'Speichern tut nichts',
    email: 'nutzer@kunde.de',
    screenshot: 'data:image/png;base64,…',
    meta: { url: location.origin + location.pathname, severity: 'high' },
  }),
});

• text (Pflicht): 5 bis 5.000 Zeichen. email: optional.
• screenshot: optional, als Data-URL (data:image/png, image/jpeg oder image/webp in Base64), unter 500 kB. Das Bild hängt am Vorgang.
• meta: optional — device, version, user, url und severity (low, normal, high, critical). critical setzt die Priorität des Vorgangs auf „Kritisch".
• turnstileToken: optional, siehe unten.

Das Paket @ventiondesk/sdk kapselt genau diesen Aufruf (ventiondesk.init({ publicKey }), dann ventiondesk.report({ text, screenshot })); es ist derzeit nicht auf npm veröffentlicht. Der fetch oben tut dasselbe.

Weg 3: Server zu Server

Hat die Kundenseite ein eigenes Backend, liefert es mit einem Eingangs-Schlüssel ein. Den legst du unter Einstellungen › Rollen & Zugänge › „Neuer Schlüssel" an: Art „Eingang", genau ein Projekt. Der Schlüssel ist geheim und gehört nur auf den Server, nie in den Browser.

curl -X POST https://api.ventiondesk.com/v1/intake/tickets \
  -H "Authorization: Bearer vd_intake_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Thomas Müller","email":"t.mueller@kunde.de","subject":"Login geht nicht","message":"Seit heute Morgen komme ich nicht mehr in mein Konto."}'

Die Felder sind dieselben wie beim Formular, dazu optional screenshot (wie oben) und meta (bis 20 einfache Werte). Ein Eingangs-Schlüssel kann nichts anderes als einliefern — keine Aufgaben lesen, keine Vorgänge sehen.

Turnstile gegen Bots

Ist auf VentionDesk-Seite Cloudflare Turnstile eingeschaltet, verlangen das Formular und der Browser-Weg ein Turnstile-Token (cf-turnstile-response bzw. turnstileToken). Fehlt es, antwortet VentionDesk mit 403. Antwortet Cloudflare selbst nicht, lässt VentionDesk die Meldung durch und markiert sie als ungeprüft — ein Ausfall bei Cloudflare soll keine Kundenanfrage kosten. Der Server-zu-Server-Weg braucht kein Turnstile.

Kontrolle: kommt etwas an?

Am öffentlichen Schlüssel in der Projektakte und an jedem Eingangs-Schlüssel unter „Rollen & Zugänge" steht „zuletzt Meldung vor …" oder „noch keine Meldung" — gemessen an echten Versuchen. Wurde der letzte Versuch abgelehnt, steht der Grund dabei:

Grenzen

Jeder Eingangsweg nimmt je IP-Adresse bis zu 10 Meldungen pro Minute an; eine Anfrage darf höchstens 1 MB groß sein.

E-Mail

Mails an das Postfach deines Betriebs werden zu Vorgängen; den Postfachnamen legst du unter Einstellungen › E-Mail-Absender fest. Antwortet ein Kunde auf eine Mail aus VentionDesk, landet die Antwort im selben Vorgang — erkannt an den Mail-Kopfzeilen, an der Ticketnummer in der Adresse (postfach+TK-1044@…) oder an [TK-1044] im Betreff. Unter „E-Mail-Eingang" in der Projektakte ordnest du Adressen einem Projekt zu; Adressen auf einer fremden Domain brauchen dort eine Weiterleitung.

Monitore

Im Reiter Analytics eines Projekts legst du Monitore an (Adresse, Art „Erreichbarkeit" oder „Zertifikat", Takt). Schlägt ein Monitor zweimal hintereinander fehl, öffnet VentionDesk einen Vorgang; ist er wieder erreichbar, wird der Vorgang gelöst.