====== Website-Formular anbinden ======

Mit der **Formular**-Verbindung (Gateway-Typ 8) kannst Du Eingaben von einer Website in einen Snapper-Ordner schreiben. Die Daten landen als lesbares JSON-Element (MIME ''snapper/form'') und lassen sich in der Base-Oberfläche öffnen.

**Wichtig:** Das API-Secret gehört **nur auf den Server** (Backend, Proxy, Cron). Niemals im HTML, JavaScript oder als verstecktes Formularfeld — jeder Besucher könnte es sonst auslesen.

===== Einrichtung in Snapper =====

  - Gehe zu **Verwaltung → Verbindungen** und lege eine Verbindung vom Typ **Formular** an.
  - Wähle den **Zielordner**, in dem Eingänge abgelegt werden sollen.
  - Optional: setze eine **IP-Whitelist** auf die IP(s) Deines Webservers (komma-separiert). Leer = alle IPs (dann schützt nur das Secret).
  - Nach dem Speichern erhältst Du ein **API-Secret** — einmalig anzeigen und sicher verwahren (z. B. in einer Config außerhalb des Webroots).
  - Endpoint: ''%%https://api.snapper.network/webhook/form%%''

===== Empfohlenes Muster =====

<code>
Browser  →  Deine Website (HTML-Formular, ohne Secret)
         →  PHP auf Deinem Server (Secret nur hier)
         →  POST https://api.snapper.network/webhook/form
</code>

===== HTML-Formular (ohne Secret) =====

Das Formular sendet nur an **Deine** Domain:

<code html>
<form method="post" action="/kontakt-senden.php">
  <!-- Honeypot: für Menschen unsichtbar, muss leer bleiben -->
  <input type="text" name="_hp" value="" style="display:none" tabindex="-1" autocomplete="off">

  <label>Name <input type="text" name="name" required></label>
  <label>E-Mail <input type="email" name="email" required></label>
  <label>Betreff <input type="text" name="subject"></label>
  <label>Nachricht <textarea name="message" required></textarea></label>
  <button type="submit">Senden</button>
</form>
</code>

===== Demo: PHP-Proxy auf Deinem Server =====

Beispiel ''kontakt-senden.php''. Das Secret kommt aus der Umgebung (oder einer Datei **außerhalb** des öffentlichen Webroots) — nicht aus dem Formular.

<code php>
<?php
/**
 * Demo: Kontaktformular → Snapper Formular-Webhook
 * Secret nur serverseitig; nie im HTML ausgeben.
 */

declare(strict_types=1);

// z. B. in der Server-Umgebung setzen, nicht in die Website-Dateien committen
$snapperSecret = getenv('SNAPPER_FORM_SECRET') ?: '';
$snapperEndpoint = 'https://api.snapper.network/webhook/form';

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit('Nur POST.');
}

// Honeypot: Bots füllen oft versteckte Felder
if (!empty($_POST['_hp'])) {
    header('Location: /danke.html'); // still OK nach außen
    exit;
}

$name = trim((string)($_POST['name'] ?? ''));
$email = trim((string)($_POST['email'] ?? ''));
$subject = trim((string)($_POST['subject'] ?? ''));
$message = trim((string)($_POST['message'] ?? ''));

if ($name === '' || $email === '' || $message === '') {
    http_response_code(400);
    exit('Bitte Pflichtfelder ausfüllen.');
}

if ($snapperSecret === '') {
    error_log('SNAPPER_FORM_SECRET fehlt');
    http_response_code(500);
    exit('Formular vorübergehend nicht verfügbar.');
}

$payload = [
    'name' => $name,
    'email' => $email,
    'subject' => $subject,
    'message' => $message,
];

$ch = curl_init($snapperEndpoint);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $snapperSecret,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
]);
$responseBody = curl_exec($ch);
$httpCode = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlErr = curl_error($ch);
curl_close($ch);

if ($responseBody === false || $httpCode < 200 || $httpCode >= 300) {
    error_log('Snapper Formular-Webhook fehlgeschlagen: HTTP ' . $httpCode . ' ' . $curlErr);
    http_response_code(502);
    exit('Senden fehlgeschlagen. Bitte später erneut versuchen.');
}

header('Location: /danke.html');
exit;
</code>

**Server-Umgebung (Beispiel):**

<code bash>
export SNAPPER_FORM_SECRET='dein-secret-hier'
</code>

Optional in Snapper die **IP-Whitelist** auf die ausgehende IP Deines Webservers setzen.

===== Übermittlung per curl (Server / Test) =====

<code bash>
curl -X POST 'https://api.snapper.network/webhook/form' \
  -H 'Authorization: Bearer DEIN_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Max Mustermann",
    "email": "max@example.com",
    "subject": "Anfrage",
    "message": "Hallo, ich habe eine Frage."
  }'
</code>

Alternativ Header ''X-Snapper-Form-Key: DEIN_SECRET''.

===== Hinweise =====

  * Secret **nie** im Browser, HTML oder Client-JavaScript.
  * Erfolgreiche Übermittlung an Snapper: HTTP **200** mit ''script.status = success''.
  * Felder mit HTML/Script-Inhalten werden von Snapper abgelehnt.
  * Das Honeypot-Feld ''_hp'' (oder ''website'') muss leer bleiben — sonst speichert Snapper nichts (stille Abwehr).
  * Der Titel des Snapper-Elements wird aus ''subject'', ''name'' oder ''email'' abgeleitet.
  * Details zur Gateway-API: [[api:gateways|Schnittstellen]] · Übersicht: [[integrations:gateways|Snapper Schnittstellen]]