Mode headless avec votre propre front end

PLUS WP-ImmoMakler peut non seulement afficher lui-même vos biens immobiliers, mais aussi les confier à un site web distinct. En mode headless, WordPress avec WP-ImmoMakler reste le back end : il reçoit les transferts de votre logiciel CRM, gère les images et les personnes de contact et traite les demandes de contact. L’affichage est assuré par un front end distinct, par exemple un site web créé avec Astro ou avec un créateur de sites web avec IA, qui lit les données via une interface JSON.

À quoi sert le mode headless

Des sites web rapides et adaptés aux moteurs de recherche. Un front end généré de façon statique ou rendu en périphérie du réseau fournit des pages HTML prêtes à l’emploi, sans passer par PHP et la base de données.
Créer le front end avec l’IA. Avec des créateurs de sites web avec IA tels que Lovable, Bolt, v0 ou Base44, vous décrivez votre site web avec vos propres mots et le créateur génère le front end. WP-ImmoMakler fournit la base technique : l’import depuis votre logiciel CRM, les données des biens immobiliers via l’interface, les demandes de contact avec protection anti-spam et leur transmission à votre logiciel CRM. La manière de connecter un créateur de sites web avec IA à l’interface est décrite dans la référence de l’API.
Un design libre, sans les limites d’un thème. Le front end conçoit librement la liste et la vue détaillée ; WP-ImmoMakler fournit les données dans l’ordre et avec les libellés de vos paramètres.
WordPress reste l’outil d’administration. Votre équipe continue de gérer textes, pages et articles dans le back end habituel ; les importations, la protection anti-spam et la transmission des demandes à votre logiciel CRM fonctionnent sans changement.

Ce que fournit l’interface

L’interface fournit les mêmes biens immobiliers que votre site WordPress. Les biens de référence, les biens archivés, les biens masqués au-delà de la limite de la licence et les projets de construction masqués sont exclus, sauf demande explicite. Chaque bien comprend :

les champs de données, les surfaces, les prix et le diagnostic de performance énergétique, avec libellé, texte d’affichage et valeur brute, dans l’ordre de vos paramètres du Customizer,
les textes descriptifs en HTML et en texte brut,
les images et plans dans toutes les tailles d’image, les documents, les vidéos et les visites virtuelles,
le statut, le type de commercialisation, le type de bien et toutes les autres catégories,
l’adresse et les coordonnées, dans la mesure où elles sont autorisées,
la personne de contact avec les champs de vos paramètres,
le titre SEO, la méta-description et les données schema.org de la vue détaillée,
les liens vers le bien sur votre front end ainsi que vers la vue d’impression PDF et le code QR sur WordPress.

S’y ajoutent vos pages et articles de l’éditeur de blocs sous forme de structure de blocs, trois emplacements de menu pour le front end et les consignes de branding issues des paramètres.

Vous trouverez la description complète de tous les endpoints dans la référence de l’API.

Prérequis

WP-ImmoMakler PLUS ou supérieur
Une installation WordPress qui reste accessible à sa propre adresse, même si les visiteurs voient désormais les biens sur le front end
Un front end qui lit l’interface JSON, par exemple un site web Astro ou un site web créé avec un créateur de sites web avec IA

Configuration

Dans le back end de votre site (wp-admin), sous WP-ImmoMakler → Intégrations → Headless :

Activez Activer l’interface headless et enregistrez. Les endpoints ne répondent qu’ensuite.
Notez l’URL de base de l’interface et la clé d’API de la section “Identifiants d’accès”. La clé est nécessaire aux applications serveur qui appellent l’interface ; avec le bouton “Générer une nouvelle clé API”, vous invalidez la clé précédente.
Sous Adresse de votre frontend, saisissez l’adresse publique du site web qui affiche vos biens. Tous les liens émis par l’interface pointent alors vers ce front end.
Si nécessaire, adaptez Chemin d’un bien et Chemin de la liste des biens à la structure d’URL de votre front end. Les espaces réservés {archive_slug}, {slug}, {objektnr_extern}, {post_id} et {locale} sont disponibles.
Sous Origines autorisées (Origins), saisissez les adresses depuis lesquelles les formulaires de votre front end pourront envoyer des demandes de contact. L’adresse du front end est automatiquement autorisée.

Outre les biens, votre front end a besoin de vos pages, de vos menus et de votre apparence :

Pages et articles : vous continuez à les gérer dans l’éditeur de blocs. L’interface les fournit sous forme de structure de blocs, à l’exception des pages de modèle de WP-ImmoMakler.
Menus : dans le backend de votre site (wp-admin), sous Apparence → Menus, affectez vos menus aux trois emplacements “Headless-Frontend: Hauptnavigation”, “Headless-Frontend: Footer” et “Headless-Frontend: Rechtliches” (libellés en allemand, pas encore traduits). La section Navigation de l’onglet headless indique quel emplacement est déjà affecté.
Branding : dans la section Identité visuelle de l’onglet headless, renseignez le nom, le slogan, le logo, la vignette par défaut, la couleur principale et la couleur d’accent ; l’interface les transmet à tout front end. Pour le starter Astro, choisissez en plus le modèle de design, l’association de polices et l’arrondi des coins dans la section Starter Astro ; un autre front end ne les utilise que si son développeur le prévoit. Votre front end reprend les valeurs lors du prochain build.

Sécuriser les requêtes de lecture

Les endpoints de lecture sont publics par défaut, car ils ne fournissent que des données que votre site affiche de toute façon à chaque visiteur. Tant que votre site n’est pas encore public, ou si vous souhaitez limiter l’accès à votre propre front end, activez Exiger la clé API également pour les requêtes en lecture. Votre front end envoie alors la clé dans l’en-tête HTTP X-ImmoMakler-Key ou comme jeton Bearer dans l’en-tête Authorization.

Comment un front end utilise l’interface

Un front end généré de façon statique commence, lors du build, par récupérer l’aperçu à l’adresse /properties/manifest. Il indique pour chaque bien visible le numéro d’objet, le nom du permalien et la date de la dernière modification. La comparaison avec le build précédent montre quelles pages de détail doivent être régénérées et lesquelles disparaissent. Les données d’un bien sont fournies par /properties/{objektnr_extern} ; la liste des biens et les pages de catégories sont créées à partir de /properties et /taxonomies.

Utilisez toujours le numéro d’objet (objektnr_extern) comme identifiant d’un bien. L’ID WordPress d’un bien change à chaque mise à jour par votre logiciel CRM, car l’importation recrée le bien.

Pour les sites web multilingues avec WPML ou Polylang, chaque bien indique sa langue sous locale et, sous translations, le numéro d’objet, l’ID WordPress, le nom du permalien et l’adresse du front end du même bien dans les autres langues, de sorte qu’un front end peut en construire des liens hreflang et des sélecteurs de langue. /site répertorie sous languages toutes les langues avec code, locale, nom et le répertoire sous lequel le front end sert la langue (prefix : / pour la langue par défaut, /en/ pour une autre). Le répertoire reflète les URL de langue de WordPress : si la page d’accueil anglaise de votre site WordPress se trouve sous /en/, l’adresse front end de chaque bien, catégorie ou page en anglais commence aussi par /en/, et la liste des biens en anglais se trouve sous /en/immobilien/. Une langue sans répertoire propre dans WordPress (un domaine par langue, langue en paramètre) reçoit son code comme répertoire. Si le modèle de chemin d’un bien contient le paramètre substituable {locale}, il reste inchangé, car vous définissez alors vous-même la structure des langues.

Le paramètre locale renvoie les libellés, les noms de catégories et les formats dans une autre langue, par exemple locale=en_GB. Cela suppose que la langue soit installée dans WordPress et sélectionnable dans le backend de votre site web (wp-admin) sous Réglages → Général → Langue du site ; WordPress ne bascule que vers une langue installée, sinon la réponse reste dans la langue du site web. WP-ImmoMakler fournit ses propres traductions pour l’anglais, l’espagnol et le français.

L’interface se décrit elle-même : à l’adresse /openapi.json, elle fournit un document OpenAPI pour les outils de développement et, à l’adresse /llms.txt, une courte description pour les créateurs de sites web assistés par IA, voir Description lisible par machine.

Les réponses aux requêtes de lecture comportent un ETag et des en-têtes de cache. Un front end qui renvoie l’ETag dans l’en-tête If-None-Match lors de la requête suivante reçoit un 304 Not Modified si rien n’a changé. Pour un front end exécuté dans le navigateur, le mieux est de laisser faire le cache du navigateur.