====== Website-Formular ins CRM ======

Mit einer **Formular-Verbindung** und dem Endpunkt ''/crm/form/submit'' landen Eingänge von Deiner Website **direkt im Snapper-CRM** — im **Posteingang** oder im **Kontakt-Thread**. Dein Team kann Anfragen wie Support-Tickets bearbeiten: zuordnen, per E-Mail antworten und optional eine Aufgabe anlegen.

**Wichtig:** Das API-Secret gehört **nur auf Deinen Server** (PHP, Node o. Ä.). Niemals im HTML, JavaScript oder als verstecktes Formularfeld.

Siehe auch: [[whitepaper:formular|Website-Formular (nur Ordner)]] · [[api:crm|CRM in Snapper]]

===== Kurzüberblick =====

<code>
Besucher (Website)
    → Dein Server (Secret nur hier)
    → POST https://api.snapper.network/crm/form/submit
    → Snapper-CRM
</code>

**Was Snapper automatisch macht:**

^ Situation ^ Ergebnis ^
| E-Mail ist **einem Kontakt** zugeordnet | Nachricht erscheint im **Kontakt-Thread** |
| E-Mail ist **neu** | Kontakt wird **angelegt**, dann Thread |
| E-Mail passt zu **mehreren Kontakten** | Nachricht landet im **Posteingang** zur manuellen Zuordnung |

Optional legt Snapper zusätzlich eine **Archiv-Kopie** im Zielordner Deiner Formular-Verbindung ab.

===== Checkliste — Schritt für Schritt =====

**1 — Vorbereiten**

  - [ ] Snapper-Account mit CRM ([[https://base.snapper.network/crm/|CRM öffnen]])
  - [ ] **SMTP-Verbindung** anlegen (Profil → Verbindungen → SMTP) und in den **CRM-Einstellungen** (Zahnrad) auswählen — für Antworten an Kunden
  - [ ] Optional: Ordner für Formular-Archiv (Roh-Eingänge)

**2 — Formular-Verbindung anlegen**

  - [ ] Profil → **Verbindungen** → Typ **Formular**
  - [ ] **Zielordner** wählen (Archiv der Eingänge)
  - [ ] **Secret** einmalig sichern — danach nicht mehr einsehbar; bei Verlust **Secret neu generieren**
  - [ ] Optional: **IP-Whitelist** (IP Deines Webservers, komma-separiert)
  - [ ] Endpunkt notieren: ''%%https://api.snapper.network/crm/form/submit%%''

**3 — Website anbinden**

  - [ ] Kontaktformular auf Deiner Website (z. B. Name, E-Mail, Betreff, Nachricht)
  - [ ] Unsichtbares **Honeypot-Feld** ''_hp'' (muss leer bleiben)
  - [ ] Formular sendet an **Deinen** Server (z. B. ''/kontakt-senden.php'')
  - [ ] Server leitet per POST an Snapper weiter (Beispiel unten)
  - [ ] Test: Eingang in **CRM → Posteingang** oder **Kontakt-Thread**

**4 — Anfragen bearbeiten**

  - [ ] **Posteingang** prüfen (unzugeordnete Nachrichten)
  - [ ] Kontakt zuordnen oder Thread öffnen
  - [ ] **E-Mail an Kunden** senden (Composer im CRM)
  - [ ] Optional: **Aufgabe** aus der Nachricht anlegen

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

<code>
Browser  →  Deine Website (ohne Secret)
         →  PHP auf Deinem Server
         →  POST https://api.snapper.network/crm/form/submit
</code>

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

<code html>
<form method="post" action="/kontakt-senden.php">
  <input type="text" name="_hp" value="" style="display:none" tabindex="-1" autocomplete="off" aria-hidden="true">

  <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>

===== Beispiel: PHP auf Deinem Server =====

<code php>
<?php
declare(strict_types=1);

$snapperSecret = getenv('SNAPPER_CRM_FORM_SECRET') ?: '';
$snapperEndpoint = 'https://api.snapper.network/crm/form/submit';

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

// Honeypot: leer lassen — sonst wird nichts gespeichert (stille Abwehr)
if (!empty($_POST['_hp'])) {
    header('Location: /danke.html');
    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_CRM_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);
curl_close($ch);

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

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

Secret z. B. in der Server-Umgebung (nicht in Git committen):

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

Optional: In den Formular-Verbindungs-Einstellungen die **IP-Whitelist** auf die ausgehende IP Deines Servers setzen.

===== Test mit curl (vom Server) =====

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

Bei Erfolg: HTTP **200** und ''"status": "success"'' in der Antwort. Danach Eingang im CRM prüfen.

===== Technische Details (API) =====

**Endpunkt:** ''POST https://api.snapper.network/crm/form/submit''

**Anmeldung:** Formular-Secret (kein Snapper-Login nötig)

^ Variante ^ Verwendung ^
| ''Authorization: Bearer <secret>'' | empfohlen |
| ''X-Snapper-Form-Key: <secret>'' | Alternative |

**Pflichtfelder im JSON-Body:**

^ Feld ^ Beschreibung ^
| ''email'' | E-Mail des Absenders |
| ''message'' | Nachrichtentext |

**Optionale Felder:** ''name'', ''subject'', ''category'' (z. B. ''support'', ''sales'', ''other'')

**Format:** JSON empfohlen; max. 128 KB gesamt, einzelne Texte max. 8000 Zeichen. Kein HTML oder Script in Feldwerten.

**Typische Fehler:**

^ Code ^ Bedeutung ^
| 400 | Pflichtfeld fehlt oder ungültiger Inhalt |
| 403 | Secret ungültig oder IP nicht erlaubt |
| 429 | Zu viele Anfragen — später erneut versuchen |
| 503 | CRM oder Formular derzeit nicht verfügbar |

**Schutz:** ca. 30 Anfragen pro Minute pro Server-IP; Honeypot-Feld ''_hp'' muss leer bleiben.

===== Nur Ordner, ohne CRM? =====

Wenn Eingänge **nur in einem Ordner** gespeichert werden sollen (ohne CRM), nutze den Endpunkt ''/webhook/form'' — Anleitung: [[whitepaper:formular|Website-Formular anbinden]].

Für **Support und Kundenanfragen im CRM** immer ''/crm/form/submit'' (dieses Whitepaper).

===== Hinweise =====

  * Secret **nie** im Browser oder öffentlich im Quellcode der Website.
  * Auf Deiner Website eine eigene **Danke-Seite** nach erfolgreichem Senden anzeigen.
  * Antworten an Besucher: im CRM **E-Mail an Kunden** (SMTP-Verbindung muss eingerichtet sein).
  * Details zu Verbindungen: [[api:connections|Verbindungen]] · CRM-Oberfläche: [[api:crm|CRM]]