Référence de l'API de l'interface headless

PLUS L’interface headless fait partie de l’API REST de WordPress et répond sous l’espace de noms immomakler-headless/v1. L’URL de base est donc

https://votre-adresse-wordpress.fr/wp-json/immomakler-headless/v1/

Tous les endpoints ne répondent qu’une fois l’interface activée dans le back end de votre site (wp-admin) sous WP-ImmoMakler → Intégrations → Headless ; voir Mode headless avec votre propre front end.

Authentification

Les endpoints de lecture sont publics par défaut. Si vous avez activé l’option Exiger la clé API également pour les requêtes en lecture, chaque requête doit envoyer la clé d’API, soit dans l’en-tête dédié, soit comme jeton Bearer :

curl -H "X-ImmoMakler-Key: VOTRE-CLE-API" https://votre-adresse-wordpress.fr/wp-json/immomakler-headless/v1/properties

curl -H "Authorization: Bearer VOTRE-CLE-API" https://votre-adresse-wordpress.fr/wp-json/immomakler-headless/v1/properties

Si la clé est absente ou incorrecte, l’interface répond par 401 avec le code d’erreur headless_unauthorized.

Paramètres communs

Paramètre	Signification
page, per_page	Page et taille de page d’une liste. per_page est limité à 100, et à 1000 pour l’aperçu /properties/manifest.
fields	summary fournit la forme abrégée pour les listes (données de la vue en liste, image principale, statut, adresse, liens), full le bien complet pour la vue détaillée. Les listes fournissent summary par défaut, la requête individuelle full.
status	open affiche les biens de la liste des biens, reference uniquement les biens de référence, all les deux. Les listes fournissent open par défaut, la requête individuelle all.
modified_since	Uniquement les biens modifiés depuis cette date (ISO 8601, par exemple 2026-10-11T08:00:00Z).
locale	Langue des libellés et des noms de catégories, par exemple de_DE ou en. Sur les sites multilingues avec WPML ou Polylang, le paramètre change aussi la langue des biens.

Les listes répondent avec une enveloppe :

{
  "items": [],
  "total": 42,
  "total_pages": 3,
  "page": 1,
  "per_page": 20,
  "generated_at": "2026-10-11T08:15:00+00:00"
}

Les listes comportent en outre les en-têtes X-WP-Total, X-WP-TotalPages et un en-tête Link avec rel="next" et rel="prev".

Mise en cache

Les réponses de lecture comportent Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=600 et un ETag. Si vous renvoyez l’ETag dans l’en-tête If-None-Match lors de la requête suivante, l’interface répond par 304 Not Modified tant que les données n’ont pas changé. Dans le navigateur, le cache HTTP du navigateur s’en charge de lui-même ; si un front end envoie lui-même If-None-Match, son code reçoit une réponse vide tant que les données n’ont pas changé et doit alors utiliser les données chargées précédemment. Après chaque transfert de votre logiciel CRM et chaque modification d’un bien, WP-ImmoMakler vide son cache, de sorte que la requête suivante fournit les données à jour.

Endpoints

GET /site

Décrit le site web une fois par build : l’adresse de WordPress et du front end, les modèles de chemins, les langues disponibles (locales et, sous languages, le code, le locale, le nom, la langue par défaut et le répertoire front end prefix de chacune), la devise, les fonctionnalités (PDF, liste de favoris, alertes de recherche, recherche par rayon), toutes les catégories avec variable de requête et chemin d’URL, les champs de données choisis dans vos paramètres (keys.archive, keys.single, keys.single_areas, keys.single_prices, keys.epass, keys.contact), les tailles d’image enregistrées et, sous search, la structure de votre formulaire de recherche : les catégories affichées, les plages avec slug, unité, pas et valeur maximale, les tris avec leur libellé, le tri par défaut, la recherche par rayon avec ses rayons et, sous search.places, l’auto-complétion des adresses de la recherche par rayon si vous avez configuré un fournisseur pour cela (voir ci-dessous).

GET /properties

La liste des biens, les derniers modifiés en premier. Prend en charge page, per_page, fields, status, modified_since et locale.

GET /properties/manifest

L’aperçu compact de tous les biens visibles, pour la synchronisation lors du build d’un front end statique. Chaque entrée indique objektnr_extern, post_id, slug, language, modified_gmt, public_since, is_reference, is_project, is_project_unit et frontend_url. Prend en charge page, per_page (jusqu’à 1000), status et locale.

GET /properties/{objektnr_extern}

Un bien, adressé par son numéro d’objet. Le numéro d’objet est transmis encodé en URL (A%2F1 pour A/1) ; la casse n’a pas d’importance. Un bien que la liste des biens n’affiche pas répond par 404 avec le code d’erreur headless_not_found. Prend en charge fields, status et locale.

GET /search

La recherche de biens avec les filtres de votre site. Les paramètres portent les mêmes noms que dans la recherche de votre site WordPress, de sorte qu’une adresse filtrée de la liste des biens et une requête de recherche signifient la même chose :

• Les catégories via leur variable de requête (typ, vermarktungsart, nutzungsart, ort, land, ausstattung) avec des slugs de termes ; la catégorie de statut s’appelle ici objektstatus, car status choisit, comme pour /properties, entre biens ouverts, références et tous. Séparez plusieurs termes par une virgule si l’un d’eux doit correspondre (typ=wohnung,haus), ou par un plus si tous doivent correspondre (ausstattung=balkon+garten). Pour les équipements, une liste (ausstattung[]=balkon&ausstattung[]=garten) signifie aussi “tous”.
• Les plages via von-{slug} et bis-{slug}, par exemple von-kaufpreis=200000&bis-kaufpreis=500000 ou von-zimmer=3. Les plages existantes et leur étendue sont indiquées par site.search.ranges. Les plages s’appliquent exactement comme dans la recherche de votre site ; un prix d’achat de 0 (sur demande) n’est pas exclu, comme là-bas.
• objekt-id : numéro d’objet ou son début.
• center et radius (km) pour la recherche par rayon (à partir de PLUS, avec la recherche par rayon activée) ; radius est facultatif. Un filtre ort est alors ignoré, comme sur le site. Sous radius, la réponse indique l’adresse trouvée ou l’erreur si le lieu n’a pas pu être déterminé.
• bounds=sud,ouest,nord,est pour la zone visible de la carte en degrés décimaux.
• order avec une clé de site.search.orders ; sans indication, le tri par défaut de votre site s’applique.
• facets=1 ajoute sous facets, pour chaque catégorie, les termes du résultat avec leur nombre, les plus fréquents d’abord, pour des compteurs à côté des filtres.
• Ainsi que page, per_page, fields, status et locale comme pour /properties.

Outre les biens, la réponse contient sous applied les filtres tels que l’interface les a compris, de sorte qu’un front end puisse en restaurer l’état de son formulaire. Les mêmes règles de visibilité s’appliquent que pour la liste des biens.

Suggestions d’adresses pour la recherche par rayon

Si un fournisseur d’auto-complétion des adresses est configuré sous WP-ImmoMakler → Intégrations → Services de géolocalisation, site.search.places décrit comment un front end récupère des suggestions pendant qu’un visiteur saisit du texte dans le champ de la recherche par rayon ; sans fournisseur, places vaut null. Le déroulement est le même que dans le formulaire de recherche de votre site, et la clé du fournisseur reste sur votre serveur :

1. GET sur places.token_url renvoie un token valable 15 minutes et, sous proxy_url, l’adresse du proxy Fast-API, qui répond sans WordPress ; proxy_url est vide si le proxy est désactivé ou si le fournisseur n’est pas Google.
2. Chaque saisie est envoyée en POST avec le corps JSON { "q": "Hambu", "session": "…", "languageCode": "de" } et l’en-tête X-ImmoMakler-Sign: <token> à proxy_url ou, à défaut, à places.suggest_url. La réponse est { "suggestions": [ { "label": "Hambourg, Allemagne", "placeId": "…" } ] }.
3. Le front end transmet le label choisi à /search comme center.

Les deux endpoints figurent aussi dans le document OpenAPI et dans llms.txt, avec leur propre espace de noms immomakler/v1 comme serveur. sessions indique si le fournisseur facture par séquence de saisie ; dans ce cas, un front end utilise la même valeur aléatoire session pour une suite de saisies et en commence une nouvelle après une sélection ou une pause de trois minutes. min_length, max_results et debounce_ms sont les valeurs de votre site. Appelez les endpoints depuis le navigateur, pas depuis un serveur : les limites (90 requêtes par minute et par visiteur sur le proxy, 600 requêtes par heure non servies depuis le cache) s’appliquent par visiteur. Le proxy accepte les requêtes provenant de l’adresse de votre front end et des origines autorisées ; il prend en compte une modification de ces paramètres lors de l’enregistrement suivant.

GET /properties/{objektnr_extern}/similar

Des biens similaires, tels que votre site les affiche sous un bien : même type de bien et même type de commercialisation à proximité, assouplis progressivement jusqu’à ce que quelque chose corresponde, dans un ordre aléatoire. count limite le nombre (par défaut : votre réglage, 12 au maximum). Les unités du même projet de construction sont exclues si votre site les affiche dans son propre tableau.

GET /properties/{objektnr_extern}/units

Les unités d’un projet de construction, telles que le tableau “Autres unités dans ce projet” les affiche : toutes les unités par numéro d’objet, y compris les unités vendues et louées que la liste des biens ne contient plus. Pour un bien qui n’est pas un projet de construction, l’interface répond par 404.

GET /taxonomies

Toutes les catégories (type de bien, type de commercialisation, type d’utilisation, localité, pays, équipements, statut) avec leurs termes : term_id, slug, name, parent, count, description et source_slug, le slug du terme indépendant de la langue. Avec hide_empty=false, les termes sans bien apparaissent aussi. Le nombre inclut tous les biens d’un terme, y compris ceux que la liste des biens masque.

GET /contacts et GET /contacts/{post_id}

Les personnes de contact publiées avec leur nom, leur description, leur portrait, les champs de contact de vos paramètres et le nombre de leurs biens.

GET /content/pages et GET /content/pages/{chemin}

Les pages publiées de votre site, sans les pages de modèle de WP-ImmoMakler. La liste indique pour chaque page le chemin hiérarchique (a-propos/equipe), la page parente, l’ordre, le modèle de page, s’il s’agit de la page d’accueil et son adresse sur le front end. La requête individuelle par chemin renvoie la page sous forme de structure de blocs : chaque bloc porte son nom (core/paragraph, immomakler/single-data, …), ses attributs, son HTML interne, ses sous-blocs et, sous rendered, le HTML que WordPress produirait pour lui. Les blocs de WP-ImmoMakler n’ont pas de rendered ; un front end les affiche à partir des données du bien. S’y ajoutent content_html, l’ensemble du contenu sous forme de fragment HTML, et seo avec le titre et la description de Yoast SEO ou de Rank Math, s’ils y sont renseignés. Les liens vers votre site WordPress pointent déjà vers le front end dans les deux versions ; les images et les documents restent sur WordPress.

GET /content/posts et GET /content/posts/{slug}

Les articles publiés, les plus récents d’abord, avec catégories, mots-clés, extrait et image mise en avant ; prend en charge modified_since. La requête individuelle renvoie la même structure de blocs que pour les pages.

GET /spam/token, POST /enquiries et POST /widerruf

Les routes de formulaires : le jeton de la protection anti-spam, les demandes de contact et les rétractations depuis un front end distinct. Elles n’acceptent des requêtes que des origines autorisées ou avec la clé d’API, et ne sont jamais mises en cache. La page Formulaires via l’interface headless décrit la structure des documents, les codes d’erreur et l’interaction avec la protection anti-spam ; site.forms indique les champs, les champs obligatoires et les textes de consentement de vos formulaires.

Webhook

L’interface signale d’elle-même à votre front end les modifications de vos biens immobiliers ; la page Webhook, liens et redirection décrit la structure, la signature et la répétition du message.

Menus et branding dans /site

site.menus contient les trois emplacements de menu que WP-ImmoMakler enregistre pour votre front end et que vous renseignez dans le backend de votre site (wp-admin) sous Apparence → Menus : primary (navigation principale), footer et legal (mentions légales, protection des données). Chaque entrée porte le titre, l’adresse enregistrée dans WordPress, sous frontend_url l’adresse sur le front end, la cible, les classes CSS, le type de la cible et ses sous-entrées.

site.branding fournit les consignes de design des sections Identité visuelle et Starter Astro des paramètres headless : le modèle de design (preset), le nom et le slogan du site, le logo et la vignette par défaut dans toutes les tailles d’image, la couleur principale et la couleur d’accent sous forme de valeurs hexadécimales, l’association de polices (sans, serif-headlines, humanist, system) et l’arrondi des coins (none, small, medium, large). Un front end écrit ces valeurs dans ses design tokens, de sorte que vous modifiez l’apparence dans WordPress sans toucher au front end.

Structure d’un bien

La forme complète (fields=full) d’un bien, abrégée :

{
  "objektnr_extern": "A-1234",
  "openimmo_obid": "7f3c…",
  "post_id": 4711,
  "slug": "wohnung-kaufen-in-hamburg-a-1234",
  "language": "de",
  "published_gmt": "2026-09-01T10:00:00+00:00",
  "modified_gmt": "2026-10-10T08:15:00+00:00",
  "title": "3-Zimmer-Wohnung in Hamburg-Altona, 85 m²",
  "object_title": "Helle Stadtwohnung mit Blick aufs Wasser",
  "subtitle": "Hamburg-Altona · Wohnung · Kauf",
  "excerpt": "…",
  "status": {
    "terms": [ { "slug": "offen", "name": "offen" } ],
    "is_open": true,
    "is_reserved": false,
    "is_reference": false,
    "archived": false,
    "is_project": false,
    "is_project_unit": false,
    "is_hidden_project": false,
    "project_id": null,
    "public_since": "2026-09-01T10:00:00+00:00"
  },
  "marketing": { "vermarktungsart": "kauf", "nutzungsart": "wohnen", "objektart": [ "wohnung" ] },
  "taxonomies": { "immomakler_object_type": [ { "term_id": 12, "slug": "wohnung", "name": "Wohnung", "parent": 0, "source_slug": "wohnung" } ] },
  "address": { "street": "Elbchaussee", "house_number": "1", "zip": "22763", "city": "Hamburg", "district": "Altona", "state": "Hamburg", "country": "DEU", "country_name": "Deutschland" },
  "geo": { "lat": 53.55, "lng": 9.93, "exact": true, "radius_m": null },
  "fields": {
    "property": [ { "key": "rooms", "source_key": "anzahl_zimmer", "label": "Zimmer", "value": "3", "text": "3 Zimmer", "raw": 3 } ],
    "areas": [ { "key": "living_area", "source_key": "wohnflaeche", "label": "Wohnfläche ca.", "value": "85 m²", "text": "Wohnfläche ca. 85 m²", "raw": 85 } ],
    "prices": [ { "key": "purchase_price", "source_key": "kaufpreis", "label": "Kaufpreis", "value": "350.000 €", "text": "Kaufpreis 350.000 €", "raw": 350000 } ],
    "epass": []
  },
  "descriptions": {
    "objektbeschreibung": { "label": "Beschreibung", "html": "<p>…</p>", "text": "…" }
  },
  "media": {
    "featured": { "id": 99, "alt": "", "title": "Wohnzimmer", "mime": "image/jpeg", "sizes": { "immomakler-archive-thumb": { "url": "…", "width": 400, "height": 267 }, "full": { "url": "…", "width": 2000, "height": 1333 } } },
    "images_count": 12,
    "floorplans_count": 1,
    "images": [],
    "floorplans": [],
    "downloads": [ { "id": 101, "title": "Exposé", "url": "…", "filename": "expose.pdf", "is_pdf": true, "is_floorplan": false } ],
    "links": [],
    "videos": [ { "type": "embed", "url": "https://www.youtube.com/watch?v=…", "embeddable": true } ],
    "virtual_tours": []
  },
  "contact": { "post_id": 7, "name": "Erika Mustermann", "slug": "erika-mustermann", "wp_url": "…", "photo": { "…": "…" }, "fields": [ { "key": "kontaktperson_fullname", "label": "Ansprechpartner", "value": "Erika Mustermann" } ] },
  "seo": { "title": "…", "description": "…", "canonical": "https://ihr-frontend.de/immobilien/wohnung-kaufen-in-hamburg-a-1234/", "og_image_url": "…" },
  "json_ld": [ { "@context": "https://schema.org", "@type": [ "Product" ] } ],
  "links": {
    "frontend_url": "https://ihr-frontend.de/immobilien/wohnung-kaufen-in-hamburg-a-1234/",
    "wp_url": "https://ihre-wordpress-adresse.de/immobilien/wohnung-kaufen-in-hamburg-a-1234/",
    "archive_frontend_url": "https://ihr-frontend.de/immobilien/",
    "og_image_url": "…/og-image/1/",
    "pdf_url": "…?pdf",
    "qr_url": "…?qrcode"
  }
}

seo contient le titre SEO et la description du bien, tels que WP-ImmoMakler les a générés lors de l’import ou que les textes d’IA les ont rédigés ; si vous avez saisi pour le bien un titre ou une description propres dans Yoast SEO ou Rank Math, ceux-ci priment. Les modèles contenant des espaces réservés comme %%title%% sont laissés au plugin SEO et ne sont pas pris en compte ici.

Chaque champ de données porte un key anglais, identique sur chaque site, et, sous source_key, le nom qu’utilisent WordPress et OpenImmo. Il comprend en outre le libellé (label) et le texte d’affichage (value) dans la langue du site, réunis en un segment de phrase (text) comme dans la forme texte des balises Elementor, par exemple « 3,5 pièces » ou « 2 places de stationnement », ainsi que la valeur brute (raw) sous forme de nombre ou de chaîne de caractères. Si un texte d’affichage contient du HTML, par exemple un lien, html fournit en plus la version non modifiée. La forme abrégée (fields=summary) remplace les groupes property, areas, prices et epass par archive et archive_prices, c’est-à-dire les champs de la vue en liste, et omet descriptions, json_ld ainsi que les listes d’images, de documents et de vidéos.

Coordonnées et adresse

Si le propriétaire n’a pas autorisé l’adresse, street et house_number restent vides et geo.exact vaut false. Représentez alors la position comme une zone, et non comme un point ; geo.radius_m indique le rayon si votre logiciel CRM l’a transmis.

Description lisible par machine

L’interface se décrit elle-même. Les deux endpoints sont toujours publics, même si vous exigez la clé d’API pour les requêtes de lecture, car ils ne fournissent aucune donnée de bien.

GET /openapi.json

Un document OpenAPI 3.1 avec tous les endpoints, paramètres, schémas de réponse et les deux modes d’authentification. Les outils de développement comme Postman, Insomnia ou les générateurs de clients typés le lisent directement ; les paramètres proviennent des routes enregistrées, de sorte que le document reste à jour à chaque extension de l’interface. Sous webhooks, il décrit les messages que votre site web envoie au front-end, avec les en-têtes, la signature et la structure ; l’introduction indique les codes d’erreur et la règle pour les formulaires qu’un serveur transmet.

GET /llms.txt et GET /llms-full.txt

Une courte description au format texte selon la convention llms.txt : finalité de l’interface, URL de base, authentification, la règle d’identifier les biens par le numéro d’objet, les codes d’erreur, le webhook et la liste des endpoints avec des liens. La variante llms-full.txt ajoute pour chaque endpoint les paramètres et les champs de la réponse.

Pour les créateurs de sites web avec IA

Les outils assistés par IA qui génèrent du code à partir d’une description s’en sortent avec ces deux fichiers sans explication supplémentaire :

• Lovable, Bolt, v0, Replit : indiquez dans le prompt l’adresse de llms.txt ou de openapi.json, par exemple “Crée une liste de biens avec l’API à l’adresse https://votre-adresse-wordpress.fr/wp-json/immomakler-headless/v1/llms.txt”. Les requêtes de lecture fonctionnent directement depuis le navigateur, car WordPress autorise l’API REST pour toutes les origines.
• Base44 : enregistrez l’adresse de openapi.json comme intégration OpenAPI personnalisée. Si vous exigez la clé d’API pour les requêtes de lecture, enregistrez-la-y comme secret ; Base44 appelle alors l’interface depuis une fonction backend.

Le code généré devrait toujours identifier les biens par objektnr_extern et utiliser les liens de links.frontend_url ; les deux figurent ainsi dans llms.txt.

Codes d’erreur

Statut HTTP	Code	Signification
401	headless_unauthorized	La clé d’API est absente ou incorrecte alors qu’elle est exigée pour les requêtes de lecture.
404	headless_not_found	Le bien ou la personne de contact n’existe pas ou n’est pas affiché publiquement.
404	rest_no_route	L’interface n’est pas activée.
400	headless_invalid_modified_since	Le paramètre modified_since n’est pas une date valide.
403	headless_forbidden	Une route de formulaire a été appelée ni depuis une origine autorisée ni avec la clé d’API.
422	headless_validation_failed	Des champs obligatoires manquent ou sont invalides ; data.errors les indique.
422	headless_unknown_property	Un numéro d’objet de properties ne correspond à aucun bien publié.
422	headless_spam_rejected	L’envoi a été rejeté comme spam.
429	headless_rate_limited	Trop de requêtes pendant cette heure.
502	headless_delivery_failed	La demande est enregistrée, mais n’a pas pu être remise à tous les destinataires.

Filtres pour les développeurs

• immomakler_headless_frontend_url modifie une URL que l’interface émet vers le front end. Paramètres : l’URL, l’ID WordPress du bien (0 pour la liste des biens) et le type (property ou archive).
• immomakler_headless_property modifie le document JSON d’un bien avant qu’il soit émis et mis en cache. Paramètres : le document, l’ID WordPress et la forme (summary ou full).
• immomakler_headless_presets détermine quels modèles de design la section Starter Astro propose au choix. Paramètre : un tableau composé du slug et du libellé du modèle.
• immomakler_headless_webhook_payload modifie le message du webhook avant qu’il ne soit signé et envoyé. Paramètres : le message sous forme de tableau et le nom de l’événement (properties.changed ou ping).
• immomakler_contact_property_url modifie l’adresse d’un bien dans l’e-mail d’une demande de contact. Avec l’interface activée et une adresse de front end renseignée, elle pointe vers le front end. Paramètres : l’URL et l’ID WordPress du bien.

Cela pourrait aussi vous intéresser

• Mode headless avec votre propre front end
• Taxonomies et catégories
• Hooks de filtre et d’action
• Effectuer des personnalisations compatibles avec les mises à jour