Formulare über die Headless-Schnittstelle

PLUS

Ein eigenes Frontend zeigt seine Formulare selbst. Was ein Besucher darin eingibt, nimmt WP-ImmoMakler über die Headless-Schnittstelle entgegen und behandelt es genau wie eine Eingabe im Kontaktformular Ihrer WordPress-Website: dieselben Pflichtfelder, derselbe Spam-Schutz, derselbe Weg zur Kontaktperson, in Ihre Maklersoftware und in die Liste der Anfragen im Backend.

Was die Website vorgibt

GET /site beschreibt unter forms, wie Ihre Formulare aufgebaut sind, damit ein Frontend sie nachbaut, statt sie zu erfinden:

forms.enquiry.fields: alle Felder des Kontaktformulars mit Beschriftung und den Angaben, ob das Feld angezeigt wird (enabled) und ob es ausgefüllt sein muss (mandatory), so wie Sie es im Backend Ihrer Website (wp-admin) unter WP-ImmoMakler → Einstellungen → Kontaktformular festgelegt haben.
forms.enquiry.texts: die Texte der Zustimmungen (AGB, Datenschutz, Widerrufsbelehrung, Provisionshinweis, individuelle Checkbox) und der Auswahlfelder “Besichtigungstermin erwünscht” und “Ich habe bereits Immobilien-Eigentum” als HTML.
forms.enquiry.withdrawal_always: ob die Widerrufsbelehrung bei jeder Immobilie bestätigt werden muss oder nur bei Immobilien mit Provision.
forms.withdrawal: die Felder und Zustimmungen des Widerrufsformulars, Einleitungs- und Bestätigungstext und die Adresse der Datenschutzerklärung.
forms.spam: wie der Spam-Schutz bedient wird, siehe unten.

Spam-Schutz

Jedes Formular Ihrer Website trägt ein signiertes Token, ein unsichtbares Feld und, wenn Sie eines eingerichtet haben, ein Captcha. Ein Frontend holt sich diese Angaben, wenn es ein Formular anzeigt:

GET /wp-json/immomakler-headless/v1/spam/token

Die Antwort nennt unter token das Token, unter honeypot_field den Namen des unsichtbaren Felds, unter min_fill_seconds, wie viele Sekunden zwischen Anzeigen und Absenden mindestens vergehen müssen, und unter captcha den Anbieter, den Feldnamen und den öffentlichen Key des Captchas (bei ALTCHA unter challenge_url die Adresse, von der das Widget seine Aufgabe holt, unter algorithm das Verfahren der Aufgabe und, wenn das ARGON2ID ist, unter worker_url den Argon2id-Worker; bei Friendly Captcha in der EU-Region unter endpoint den Wert für data-api-endpoint beziehungsweise data-puzzle-endpoint des Widgets). Das Token wird beim Absenden unter spam.token zurückgeschickt, das unsichtbare Feld leer unter spam.honeypot, die Lösung des Captchas unter spam.captcha.

Nutzt Ihre Website ALTCHA, stellt WP-ImmoMakler auf jedem Server mit der PHP-Erweiterung Sodium Aufgaben nach dem Verfahren Argon2id. Das ALTCHA-Paket löst von sich aus nur PBKDF2 und SHA; Ihr Frontend muss den Argon2id-Worker beim Widget registrieren, bevor es eine Aufgabe löst, sonst scheitert jede Aufgabe mit “Unsupported algorithm”. Mit dem npm-Paket altcha und einem Bundler wie Vite:

import 'altcha';
import Argon2idWorker from 'altcha/workers/argon2id?worker';

globalThis.$altcha.algorithms.set('ARGON2ID', () => new Argon2idWorker());

Ohne Bundler registrieren Sie den Worker aus worker_url. Ein Worker muss von derselben Adresse wie die Seite stammen, deshalb über einen Blob, der das Skript nachlädt: new Worker(URL.createObjectURL(new Blob(['importScripts(' + JSON.stringify(workerUrl) + ')']))). Das Widget selbst bekommt challenge_url im Attribut challenge; die Route beantwortet Anfragen von jeder Adresse.

Ob ein verdächtiger Absender abgewiesen oder die Anfrage nur markiert zugestellt wird, bestimmt wie auf der Website die Einstellung unter WP-ImmoMakler → Einstellungen → Spam-Schutz. Die Begrenzung der Anfragen pro Stunde und Besucher gilt ebenfalls.

Sendet nicht der Browser des Besuchers, sondern der Server Ihres Frontends die Formulare an die Schnittstelle, sehen alle Besucher für WP-ImmoMakler wie ein einziger aus. Tragen Sie dann die IP-Adressen dieser Server im Backend Ihrer Website (wp-admin) unter WP-ImmoMakler → Integrationen → Headless als vertrauenswürdige Proxy-Adressen ein; WP-ImmoMakler liest die Adresse des Besuchers dann aus dem Header X-Forwarded-For, den Ihr Server mitschickt.

Läuft Ihr Frontend bei einem Anbieter wie Cloudflare, Vercel oder Netlify, haben dessen Server keine feste Adresse. Tragen Sie dann die Adressbereiche ein, die der Anbieter veröffentlicht, in CIDR-Schreibweise, eine pro Zeile, zum Beispiel 173.245.48.0/20 oder 2400:cb00::/32; für Cloudflare stehen sie unter cloudflare.com/ips. Ein Besucher kann den Header nicht zu seinen Gunsten fälschen: WP-ImmoMakler nimmt die letzte Adresse im Header, die nicht selbst zu einem vertrauenswürdigen Bereich gehört, und das ist die, die der Anbieter selbst eingetragen hat.

Wer senden darf

Die Formularrouten nehmen Anfragen nur von den erlaubten Ursprüngen entgegen, also aus einem Browser auf der Adresse Ihres Frontends oder einer der unter Erlaubte Ursprünge eingetragenen Adressen, oder mit dem API-Key im Header X-ImmoMakler-Key, wenn der Server Ihres Frontends sendet. Alles andere antwortet mit 403 und dem Fehlercode headless_forbidden.

Kontaktanfrage senden

POST /wp-json/immomakler-headless/v1/enquiries
Content-Type: application/json

{
  "properties": ["WP1235"],
  "fields": {
    "salutation": "Frau",
    "first_name": "Erika",
    "last_name": "Muster",
    "email": "erika@example.com",
    "phone": "+49 40 123456",
    "message": "Ich interessiere mich für die Wohnung.",
    "appointment_requested": true
  },
  "consents": { "privacy": true, "withdrawal": true },
  "spam": { "token": "…", "honeypot": "" },
  "origin": "https://www.ihre-domain.de/immobilien/wohnung-in-hamburg/"
}

properties nennt die Objektnummern der angefragten Immobilien; ohne properties ist es eine allgemeine Kontaktaufnahme an die in den Einstellungen hinterlegte Adresse. fields enthält die Eingaben mit den englischen Feldnamen aus forms.enquiry.fields (key; source_key nennt den Namen des Feldes in den WordPress-Einstellungen), consents die Zustimmungen (terms, privacy, withdrawal, commission, custom), origin die Seite, von der die Anfrage kam; sie wird in der E-Mail genannt.

Bei Erfolg antwortet die Schnittstelle mit 201 und nennt die Nummer des gespeicherten Eintrags unter WP-ImmoMakler → Anfragen (enquiry_id) sowie, ob die Anfrage als verdächtig markiert zugestellt wurde (spam_suspected). Links auf die Immobilien in der E-Mail zeigen auf Ihr Frontend.

Fehlen Pflichtfelder oder ist eine E-Mail-Adresse ungültig, antwortet sie mit 422 und dem Fehlercode headless_validation_failed; data.errors listet die betroffenen Felder (email, privacy, …). Eine unbekannte Objektnummer meldet headless_unknown_property, eine als Spam abgewiesene Anfrage headless_spam_rejected, zu viele Anfragen in einer Stunde 429 mit headless_rate_limited. Konnte eine E-Mail nicht zugestellt werden, antwortet sie mit 502 und headless_delivery_failed; die Anfrage ist dann trotzdem unter WP-ImmoMakler → Anfragen gespeichert.

Widerruf senden

POST /wp-json/immomakler-headless/v1/withdrawal
Content-Type: application/json

{
  "fields": {
    "first_name": "Erika",
    "last_name": "Muster",
    "email": "erika@example.com",
    "contract_identification": "Maklervertrag vom 1. Oktober 2026"
  },
  "consents": { "withdrawal": true, "privacy": true },
  "property": "WP1235",
  "source_url": "https://www.ihre-domain.de/widerruf/",
  "spam": { "token": "…", "honeypot": "" }
}

Alle Felder und beide Zustimmungen sind Pflicht. WP-ImmoMakler schickt den Widerruf an die eingestellte Adresse, legt ihn im Archiv ab und schickt dem Besucher eine Eingangsbestätigung, sofern die Eingabe nicht als Spam verdächtig ist. Die Antwort 201 nennt unter submitted_at den Zeitpunkt des Eingangs. Fehlende Angaben melden 422 mit headless_validation_failed, data.errors nennt die Felder (contract_identification, withdrawal, privacy, …).

Suchauftrag anlegen

Ein Suchauftrag speichert eine Suche für eine E-Mail-Adresse; WP-ImmoMakler schickt dem Abonnenten danach neue Treffer per E-Mail, nachdem er den Suchauftrag über den Link in der Bestätigungs-E-Mail aktiviert hat (Double-Opt-In). Ob Ihre Website Suchaufträge anbietet, sagt /site unter forms.search_agent.active; dort stehen auch die Texte der beiden Einwilligungen (texts.contact, texts.privacy), der Teaser- und Formulartext, ob die Option für Text-E-Mails angeboten wird (plaintext_option) und unter page_url die Seite Ihres Frontends, auf die die Links in den E-Mails zeigen.

POST /wp-json/immomakler-headless/v1/search-agents
Content-Type: application/json

{
  "email": "erika@example.com",
  "criteria": { "marketing": "kauf", "type": "wohnung", "location": "hamburg", "price_max": 500000, "rooms_min": 3 },
  "consents": { "contact": true, "privacy": true },
  "notification": { "plaintext": false },
  "spam": { "token": "…", "honeypot": "" }
}

criteria nimmt dieselben Parameter wie /search (die Namen des Suchformulars Ihrer Website gelten als Aliasse); ein leeres Objekt speichert “alle Immobilien”. Beide Einwilligungen sind Pflicht. Die Antwort (201) nennt unter status den Wert pending und unter message den Hinweis, den Sie dem Besucher zeigen; 422 nennt fehlende Einwilligungen, eine ungültige Adresse oder unplausible Kriterien, 429 zu viele Suchaufträge in einer Stunde.

Die Bestätigungs-E-Mail führt auf page_url mit ?callback=confirm_searchagent&confirm=<hash>, der Abmeldelink in jeder Benachrichtigung auf page_url mit ?callback=delete_searchagent&delete=<hash>. Die Seite Ihres Frontends liest den Suchauftrag mit GET /search-agents/<hash> (Status, Adresse, Kriterien als Bezeichnung/Wert-Paare, Link zur Trefferliste) und handelt erst auf einen Klick des Besuchers: POST /search-agents/<hash>/confirm aktiviert den Suchauftrag, DELETE /search-agents/<hash> löscht ihn. Handeln Sie nie schon beim Öffnen des Links: Sicherheitsprüfungen von E-Mail-Diensten rufen jeden Link einer E-Mail auf. Den Pfad der Seite legen Sie im Backend Ihrer Website (wp-admin) unter WP-ImmoMakler → Integrationen → Headless als “Pfad der Suchauftrag-Seite” fest; ohne eingetragenes Frontend führen die Links wie bisher auf die Immobilienliste von WordPress.