deskhub/DeskHub-Webseite/tools/manual/handbuch/ch16.html

<h1>Integrationen und Schnittstellen</h1>

<h2>API-Schlüssel</h2>
<p>Ein API-Schlüssel erlaubt einem anderen System, Tickets in DeskHub anzulegen oder zu lesen (Adminportal → <b>API-Schlüssel</b>, nur echte Administratoren).</p>
<fig n="admin-api-schluessel">API-Schlüssel mit Rechten und IP-Beschränkung.</fig>
<ul>
  <li>Beim Erstellen wird der Schlüssel (Format <code>dh_</code> plus 48 Hexzeichen) <b>nur einmal</b> angezeigt – sofort notieren. In der Datenbank liegt nur eine Prüfsumme.</li>
  <li>Pro Schlüssel legt ihr die <b>Rechte</b> fest („Tickets anlegen“ und/oder „Tickets lesen“) und optional die <b>erlaubten IP-Adressen</b>.</li>
  <li>Schlüssel lassen sich jederzeit deaktivieren. Es gilt eine Begrenzung auf 60 über die API angelegte Tickets pro Minute (gemeinsam für alle Schlüssel).</li>
</ul>

<h2>Webhooks</h2>
<p>Webhooks melden Ereignisse sofort an eine Adresse eures Systems (Adminportal → <b>Webhooks</b>): Name, URL und gewünschte Ereignisse wählen; das <b>Secret</b> zur Signaturprüfung legt ihr selbst fest oder lasst es erzeugen (es wird nur verschlüsselt gespeichert).</p>
<fig n="admin-webhooks">Webhooks mit Zustellstatus.</fig>
<table>
  <tr><th>Ereignis</th><th>Wann</th></tr>
  <tr><td><code>ticket.created</code></td><td>Neues Ticket (Portal, E-Mail, Chat, Mitarbeiter oder API)</td></tr>
  <tr><td><code>ticket.replied</code></td><td>Antwort oder interne Notiz (Feld <code>author</code>, bei Mitarbeitern auch <code>internal</code>)</td></tr>
  <tr><td><code>ticket.status_changed</code></td><td>Status geändert (Feld <code>previousStatus</code>)</td></tr>
  <tr><td><code>ticket.assigned</code></td><td>Zuweisung geändert</td></tr>
</table>
<ul>
  <li><b>Anfrage:</b> <code>POST</code> mit JSON und den Headern <code>X-DeskHub-Event</code> und <code>X-DeskHub-Signature</code> (<code>sha256=</code> plus HMAC-SHA256 des rohen Körpers mit dem Secret). Gesendet werden nur Ticketdaten, nicht der Nachrichtentext.</li>
  <li><b>Zustellung:</b> Eure Adresse muss binnen 5 Sekunden mit <code>2xx</code> antworten. Es gibt <b>keine automatische Wiederholung</b>. Nach <b>10 Fehlern in Folge</b> wird der Webhook automatisch deaktiviert; Status, Fehlertext und Zeitpunkt stehen in der Liste.</li>
  <li>Erlaubt sind <code>http://</code> und <code>https://</code>, aber keine internen Ziele (localhost, private Netze). Nutzt <code>https://</code>.</li>
</ul>

<h2>Die Ticket-API für Entwickler</h2>
<p>Basis-Adresse: <code>https://support.example.de/api/public/v1/tickets.php</code> (Beispieladresse). Jeder Aufruf braucht einen Schlüssel im Header <code>X-API-Key</code> oder <code>Authorization: Bearer</code>. Anfragen und Antworten sind JSON.</p>
<table>
  <tr><th>Aufruf</th><th>Recht</th><th>Zweck</th></tr>
  <tr><td><code>POST /api/public/v1/tickets.php</code></td><td>Tickets anlegen</td><td>Ticket anlegen mit <code>name</code>, <code>email</code>, <code>subject</code>, <code>message</code> und optional <code>helpTopicId</code>, <code>departmentId</code>, <code>priorityId</code>, <code>fields</code> (Formularfelder) und <code>attachments</code> (bis 5 Dateien, Base64). Antwort <code>201</code> mit <code>{"number":"T-1042","status":"open"}</code></td></tr>
  <tr><td><code>GET …tickets.php?topics=1</code></td><td>Tickets anlegen</td><td>Öffentliche Hilfethemen</td></tr>
  <tr><td><code>GET …tickets.php?form=1&amp;helpTopicId=3</code></td><td>Tickets anlegen</td><td>Das Formular eines Themas oder einer Abteilung (Felder, Texte, Anhangsgrenzen)</td></tr>
  <tr><td><code>GET …tickets.php?number=T-1042&amp;email=…</code></td><td>Tickets lesen</td><td>Status und öffentliche Nachrichten (nie interne Notizen); falsche E-Mail ergibt 404</td></tr>
</table>
<p>Fehler haben immer die Form <code>{"error":{"code":"INVALID_EMAIL","message":"…"}}</code>. Wichtige Codes: <code>UNAUTHENTICATED</code> (401), <code>IP_NOT_ALLOWED</code> (401), <code>FORBIDDEN</code> (403), <code>BANNED</code>/<code>REJECTED</code> (403), <code>NOT_FOUND</code> (404), <code>TOO_LARGE</code> (413), <code>INVALID_*</code> (422), <code>RATE_LIMITED</code> (429), <code>NO_DEPARTMENT</code> (503). Das Anlegen hat keine Wiederholungssicherung: Zweimal gesendet ergibt zwei Tickets.</p>

<h2>WordPress-Plugin „DeskHub Tickets“</h2>
<p>Besucher einer WordPress-Seite legen damit Tickets in DeskHub an (<code>[deskhub_ticket]</code>) und fragen den Stand ab (<code>[deskhub_status]</code>). Das Plugin nutzt die öffentliche Ticket-API und braucht nur einen <b>API-Schlüssel</b> (Recht „Tickets anlegen“, für die Statusabfrage zusätzlich „Tickets lesen“).</p>
<ul>
  <li><b>Formular</b> mit den eigenen Feldern und Texten des Hilfethemas aus DeskHub (auch dem Formular der Abteilung), Einwilligungs-Kästchen, Anhänge (bis 5 Dateien, zusammen 10 MB).</li>
  <li><b>Statusabfrage</b> mit Verlauf.</li>
  <li><b>Spamschutz:</b> Falle-Feld, Mindestzeit, Mengenbegrenzung, optional Cloudflare Turnstile. Verbindungstest, Deutsch und Englisch.</li>
  <li><b>Design:</b> Farben übernimmt das Formular vom Theme; die Akzentfarbe lässt sich fest vorgeben.</li>
  <li><b>Sicherheit:</b> Der Schlüssel liegt nur auf dem WordPress-Server (oder in der <code>wp-config.php</code>), nie im Browser.</li>
</ul>
<div class="note">Das Plugin wurde mit einem Nachbau der WordPress-Funktionen und gegen einen echten DeskHub-Server getestet, noch nicht in einer echten WordPress-Installation.</div>

<h2>Minecraft-Plugin</h2>
<p>Eine Jar für <b>Spigot, Paper und BungeeCord</b>, die in DeskHub automatisch ein Ticket anlegt, wenn ein Minecraft-Server offline geht – und es nach der Rückkehr als gelöst markiert.</p>
<table>
  <tr><th>Wo es liegt</th><th>Erkennung</th><th>Ticket</th></tr>
  <tr><td>BungeeCord-Proxy (empfohlen)</td><td>Prüft die Server von außen per Ping alle 30 Sekunden</td><td>nach 3 Fehlschlägen in Folge und wenn der Server länger als die Schonfrist (5 Minuten) fehlt</td></tr>
  <tr><td>Spigot/Paper</td><td>Schreibt Lebenszeichen und markiert normales Beenden</td><td>beim nächsten Start nach einem Absturz oder harten Ende</td></tr>
</table>
<ul>
  <li><b>Installation:</b> API-Schlüssel mit Recht „Tickets anlegen“ (mit IP-Beschränkung auf den Minecraft-Server) erzeugen; Jar in den Ordner <code>plugins</code>; <code>config.yml</code> ausfüllen (<code>url</code>, <code>api-key</code>, <code>requester-email</code>, optional Abteilung und Priorität); <code>/deskhubmc reload</code>; mit <code>/deskhubmc test</code> ein Testticket anlegen.</li>
  <li><b>Befehle:</b> <code>/deskhubmc test</code>, <code>/deskhubmc status</code>, <code>/deskhubmc reload</code> (Alias <code>/dhmc</code>, Recht <code>deskhubmc.admin</code>).</li>
  <li><b>Geplante Neustarts</b> lassen sich dem Proxy signiert melden (längere Schonfrist, Standard 15 Minuten). Gegen Ticket-Fluten: pro Ausfall höchstens ein Ticket, pro Server frühestens nach 30 Minuten wieder eines.</li>
  <li>Betreff und Text der Tickets sind anpassbar (Platzhalter <code>{server}</code>, <code>{time}</code>, <code>{downtime}</code> u. a.).</li>
</ul>
<fig n="apps">Auf der Seite „Apps“ steht das Minecraft-Plugin bereit, wenn es unter Einstellungen → Allgemein eingeblendet ist.</fig>