Formulaires via l'interface headless

PLUS

Un front end distinct affiche lui-même ses formulaires. Ce qu’un visiteur y saisit est reçu par WP-ImmoMakler via l’interface headless et traité exactement comme une saisie dans le formulaire de contact de votre site WordPress : les mêmes champs obligatoires, la même protection anti-spam, le même chemin vers la personne de contact, vers votre logiciel CRM et vers la liste des demandes dans le back end.

Ce que le site définit

GET /site décrit sous forms la structure de vos formulaires, afin qu’un front end les reproduise au lieu de les inventer :

forms.enquiry.fields : tous les champs du formulaire de contact avec leur libellé et les indications précisant si le champ est affiché (enabled) et s’il doit être rempli (mandatory), tels que vous les avez définis dans le back end de votre site (wp-admin) sous WP-ImmoMakler → Paramètres → Formulaire de contact.
forms.enquiry.texts : les textes des consentements (CGV, protection des données, information sur la rétractation, mention de commission, case à cocher personnalisée) et des champs de sélection « Visite souhaitée » et « Je possède déjà un bien immobilier » au format HTML.
forms.enquiry.withdrawal_always : si l’information sur la rétractation doit être confirmée pour chaque bien ou seulement pour les biens avec commission.
forms.withdrawal : les champs et consentements du formulaire de rétractation, les textes d’introduction et de confirmation et l’adresse de la politique de confidentialité.
forms.spam : comment la protection anti-spam est utilisée, voir ci-dessous.

Protection anti-spam

Chaque formulaire de votre site porte un jeton signé, un champ invisible et, si vous en avez configuré un, un captcha. Un front end récupère ces informations lorsqu’il affiche un formulaire :

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

La réponse indique sous token le jeton, sous honeypot_field le nom du champ invisible, sous min_fill_seconds le nombre minimal de secondes qui doivent s’écouler entre l’affichage et l’envoi, et sous captcha le fournisseur, le nom du champ et la clé publique du captcha (pour ALTCHA, sous challenge_url l’adresse à laquelle le widget récupère sa tâche, sous algorithm l’algorithme de la tâche et, s’il s’agit de ARGON2ID, sous worker_url le worker Argon2id ; pour Friendly Captcha dans la région UE, sous endpoint la valeur pour data-api-endpoint ou data-puzzle-endpoint du widget). À l’envoi, le jeton est renvoyé sous spam.token, le champ invisible vide sous spam.honeypot et la solution du captcha sous spam.captcha.

Si votre site utilise ALTCHA, WP-ImmoMakler émet sur chaque serveur disposant de l’extension PHP Sodium des tâches selon l’algorithme Argon2id. Le paquet ALTCHA ne résout de lui-même que PBKDF2 et SHA ; votre front end doit enregistrer le worker Argon2id auprès du widget avant de résoudre une tâche, sinon chaque tâche échoue avec « Unsupported algorithm ». Avec le paquet npm altcha et un bundler comme Vite :

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

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

Sans bundler, enregistrez le worker depuis worker_url. Un worker doit provenir de la même adresse que la page, donc via un blob qui charge le script : new Worker(URL.createObjectURL(new Blob(['importScripts(' + JSON.stringify(workerUrl) + ')']))). Le widget lui-même reçoit challenge_url dans l’attribut challenge ; la route répond aux requêtes de n’importe quelle adresse.

Le fait qu’un expéditeur suspect soit rejeté ou que la demande soit seulement remise avec un marquage est déterminé, comme sur le site, par le paramètre sous WP-ImmoMakler → Paramètres → Protection anti-spam. La limitation du nombre de requêtes par heure et par visiteur s’applique également.

Si ce n’est pas le navigateur du visiteur, mais le serveur de votre front end qui envoie les formulaires à l’interface, tous les visiteurs ressemblent à un seul pour WP-ImmoMakler. Dans ce cas, saisissez les adresses IP de ces serveurs comme adresses de proxy de confiance dans le back end de votre site (wp-admin) sous WP-ImmoMakler → Intégrations → Headless ; WP-ImmoMakler lit alors l’adresse du visiteur dans l’en-tête X-Forwarded-For que votre serveur transmet.

Si votre front end est hébergé chez un fournisseur comme Cloudflare, Vercel ou Netlify, les serveurs de celui-ci n’ont pas d’adresse fixe. Saisissez alors les plages d’adresses que le fournisseur publie, en notation CIDR, une par ligne, par exemple 173.245.48.0/20 ou 2400:cb00::/32 ; pour Cloudflare, elles figurent sur cloudflare.com/ips. Un visiteur ne peut pas falsifier l’en-tête à son avantage : WP-ImmoMakler retient la dernière adresse de l’en-tête qui n’appartient pas elle-même à une plage de confiance, et c’est celle que le fournisseur a lui-même inscrite.

Qui peut envoyer

Les routes de formulaires n’acceptent des requêtes que des origines autorisées, c’est-à-dire depuis un navigateur sur l’adresse de votre front end ou l’une des adresses saisies sous Origines autorisées (Origins), ou avec la clé d’API dans l’en-tête X-ImmoMakler-Key lorsque c’est le serveur de votre front end qui envoie. Tout le reste reçoit la réponse 403 avec le code d’erreur headless_forbidden.

Envoyer une demande de contact

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 indique les numéros d’objet des biens concernés ; sans properties, il s’agit d’une prise de contact générale à l’adresse renseignée dans les paramètres. fields contient les saisies avec les noms de champs anglais de forms.enquiry.fields (key ; source_key indique le nom du champ dans les paramètres WordPress), consents les consentements (terms, privacy, withdrawal, commission, custom) et origin la page d’où provient la demande ; elle est mentionnée dans l’e-mail.

En cas de succès, l’interface répond par 201 et indique le numéro de l’entrée enregistrée sous WP-ImmoMakler → Demandes de contact (enquiry_id) ainsi que si la demande a été remise marquée comme suspecte (spam_suspected). Les liens vers les biens dans l’e-mail pointent vers votre front end.

Si des champs obligatoires manquent ou si une adresse e-mail est invalide, elle répond par 422 avec le code d’erreur headless_validation_failed ; data.errors liste les champs concernés (email, privacy, …). Un numéro d’objet inconnu est signalé par headless_unknown_property, une demande rejetée comme spam par headless_spam_rejected, un trop grand nombre de requêtes en une heure par 429 avec headless_rate_limited. Si un e-mail n’a pas pu être remis, elle répond par 502 et headless_delivery_failed ; la demande est alors tout de même enregistrée sous WP-ImmoMakler → Demandes de contact.

Envoyer une rétractation

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": "" }
}

Tous les champs et les deux consentements sont obligatoires. WP-ImmoMakler envoie la rétractation à l’adresse configurée, la classe dans les archives et envoie au visiteur un accusé de réception, tant que l’envoi n’est pas suspecté d’être du spam. La réponse 201 indique sous submitted_at le moment de la réception. Les informations manquantes sont signalées par 422 avec headless_validation_failed, et data.errors indique les champs (contract_identification, withdrawal, privacy, …).

Créer une alerte de recherche

Une alerte de recherche enregistre une recherche pour une adresse e-mail ; WP-ImmoMakler envoie ensuite par e-mail les nouveaux résultats à l’abonné, une fois qu’il a activé l’alerte via le lien de l’e-mail de confirmation (double opt-in). /site indique sous forms.search_agent.active si votre site propose des alertes de recherche ; on y trouve aussi les textes des deux consentements (texts.contact, texts.privacy), le texte d’accroche et du formulaire, si l’option des e-mails au format texte est proposée (plaintext_option) et, sous page_url, la page de votre front end vers laquelle pointent les liens des e-mails.

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 accepte les mêmes paramètres que /search (les noms du formulaire de recherche de votre site valent comme alias) ; un objet vide enregistre « tous les biens immobiliers ». Les deux consentements sont obligatoires. La réponse (201) indique sous status la valeur pending et sous message l’information que vous affichez au visiteur ; 422 signale des consentements manquants, une adresse invalide ou des critères peu plausibles, 429 un trop grand nombre d’alertes de recherche en une heure.

L’e-mail de confirmation mène à page_url avec ?callback=confirm_searchagent&confirm=<hash>, le lien de désinscription de chaque notification à page_url avec ?callback=delete_searchagent&delete=<hash>. La page de votre front end lit l’alerte de recherche avec GET /search-agents/<hash> (statut, adresse, critères sous forme de paires libellé/valeur, lien vers la liste de résultats) et n’agit qu’après un clic du visiteur : POST /search-agents/<hash>/confirm active l’alerte, DELETE /search-agents/<hash> la supprime. N’agissez jamais dès l’ouverture du lien : les contrôles de sécurité des services de messagerie ouvrent chaque lien d’un e-mail. Vous définissez le chemin de la page dans le back end de votre site (wp-admin) sous WP-ImmoMakler → Intégrations → Headless via Chemin de la page de l’alerte de recherche ; sans front end renseigné, les liens mènent comme auparavant à la liste des biens de WordPress.