Headless-Betrieb mit eigenem Frontend

PLUS WP-ImmoMakler kann Ihre Immobilien nicht nur selbst darstellen, sondern sie auch einer eigenen Website überlassen. Im Headless-Betrieb bleibt WordPress mit WP-ImmoMakler das Backend: Es empfängt die Übertragungen Ihrer Maklersoftware, verwaltet Bilder und Kontaktpersonen und beantwortet Kontaktanfragen. Die Darstellung übernimmt ein eigenes Frontend, etwa eine mit Astro gebaute oder mit einem KI-Website-Builder erstellte Website, das die Daten über eine JSON-Schnittstelle liest.

Wofür der Headless-Betrieb gedacht ist

Schnelle, suchmaschinenfreundliche Websites. Ein statisch gebautes oder am Netzwerkrand gerendertes Frontend liefert fertige HTML-Seiten ohne den Umweg über PHP und Datenbank.
Frontend mit KI erstellen. Mit KI-Website-Buildern wie Lovable, Bolt, v0 oder Base44 beschreiben Sie Ihre Website in eigenen Worten, und der Builder erstellt das Frontend. WP-ImmoMakler liefert die technische Grundlage: den Import aus Ihrer Maklersoftware, die Immobiliendaten über die Schnittstelle, Kontaktanfragen mit Spam-Schutz und deren Weiterleitung an Ihre Maklersoftware. Wie Sie einen KI-Website-Builder mit der Schnittstelle verbinden, steht in der API-Referenz.
Eigenes Design ohne Theme-Grenzen. Das Frontend gestaltet Immobilienliste und Detailansicht frei; WP-ImmoMakler liefert die Daten in der Reihenfolge und mit den Bezeichnungen aus Ihren Einstellungen.
WordPress bleibt die Verwaltung. Ihr Team pflegt Texte, Seiten und Beiträge weiter im gewohnten Backend; Importe, Spam-Schutz und die Weiterleitung von Anfragen an Ihre Maklersoftware laufen unverändert.

Was die Schnittstelle liefert

Die Schnittstelle gibt dieselben Immobilien aus wie Ihre WordPress-Website. Referenzobjekte, archivierte Immobilien, über das Lizenzlimit hinaus ausgeblendete Immobilien und versteckte Bauprojekte bleiben außen vor, sofern Sie sie nicht ausdrücklich anfordern. Zu jeder Immobilie gehören:

die Datenfelder, Flächen, Preise und der Energieausweis mit Bezeichnung, Anzeigetext und Rohwert, in der Reihenfolge Ihrer Customizer-Einstellungen,
die Beschreibungstexte als HTML und als reiner Text,
Bilder und Grundrisse in allen Bildgrößen, Dokumente, Videos und virtuelle Rundgänge,
Status, Vermarktungsart, Objektart und alle weiteren Kategorien,
Adresse und Koordinaten, so weit sie freigegeben sind,
die Kontaktperson mit den Feldern aus Ihren Einstellungen,
SEO-Titel, Meta-Beschreibung und die schema.org-Daten der Detailansicht,
die Links zur Immobilie auf Ihrem Frontend sowie zur PDF-Druckansicht und zum QR-Code auf WordPress.

Dazu kommen Ihre Seiten und Beiträge aus dem Block-Editor als Block-Struktur, drei Menüpositionen für das Frontend und die Branding-Vorgaben aus den Einstellungen.

Die vollständige Beschreibung aller Endpunkte finden Sie in der API-Referenz.

Voraussetzungen

WP-ImmoMakler PLUS oder höher
Eine WordPress-Installation, die unter ihrer eigenen Adresse erreichbar bleibt, auch wenn Besucher die Immobilien künftig auf dem Frontend sehen
Ein Frontend, das die JSON-Schnittstelle liest, zum Beispiel eine Astro-Website oder eine mit einem KI-Website-Builder erstellte Website

Einrichtung

Im Backend Ihrer Website (wp-admin) unter WP-ImmoMakler → Integrationen → Headless:

Aktivieren Sie “Headless-Schnittstelle aktivieren” und speichern Sie. Erst danach antworten die Endpunkte.
Notieren Sie sich die Basis-URL der Schnittstelle und den API-Key aus dem Abschnitt “Zugangsdaten”. Den Key brauchen Server-Anwendungen, die die Schnittstelle aufrufen; über den Button “Neuen API-Key erzeugen” machen Sie den bisherigen Key ungültig.
Tragen Sie unter “Adresse Ihres Frontends” die öffentliche Adresse der Website ein, die Ihre Immobilien darstellt. Alle Links, die die Schnittstelle ausgibt, zeigen dann auf dieses Frontend.
Passen Sie bei Bedarf “Pfad einer Immobilie” und “Pfad der Immobilienliste” an die URL-Struktur Ihres Frontends an. Die Platzhalter {archive_slug}, {slug}, {object_number}, {post_id} und {locale} stehen zur Verfügung.
Tragen Sie unter “Erlaubte Ursprünge (Origins)” die Adressen ein, von denen Formulare Ihres Frontends später Kontaktanfragen senden dürfen. Die Adresse des Frontends ist automatisch erlaubt.

Ihr Frontend braucht neben den Immobilien auch Ihre Seiten, Menüs und Ihr Erscheinungsbild:

Seiten und Beiträge pflegen Sie weiter im Block-Editor. Die Schnittstelle liefert sie als Block-Struktur aus, Vorlagenseiten von WP-ImmoMakler ausgenommen.
Menüs: Belegen Sie im Backend Ihrer Website (wp-admin) unter Design → Menüs die drei Positionen “Headless-Frontend: Hauptnavigation”, “Headless-Frontend: Footer” und “Headless-Frontend: Rechtliches” mit Ihren Menüs. Der Abschnitt “Navigation” im Headless-Tab zeigt, welche Position bereits belegt ist.
Branding: Hinterlegen Sie im Abschnitt “Branding” des Headless-Tabs Namen, Claim, Logo, Standard-Vorschaubild, Primär- und Akzentfarbe; die Schnittstelle liefert sie an jedes Frontend. Für den Astro-Starter wählen Sie im Abschnitt “Astro-Starter” außerdem Gestaltungsvorlage, Schriftkombination und Eckenrundung; ein anderes Frontend nutzt sie nur, wenn sein Entwickler das vorsieht. Ihr Frontend übernimmt die Werte beim nächsten Build.

Lesende Anfragen absichern

Die lesenden Endpunkte sind standardmäßig öffentlich, denn sie liefern nur Daten, die Ihre Website ohnehin jedem Besucher zeigt. Solange Ihre Website noch nicht öffentlich ist oder Sie den Zugriff auf Ihr eigenes Frontend beschränken möchten, aktivieren Sie “API-Key auch für lesende Anfragen verlangen”. Ihr Frontend sendet den Key dann im HTTP-Header X-ImmoMakler-Key oder als Bearer-Token im Header Authorization.

Wie ein Frontend die Schnittstelle nutzt

Ein statisch gebautes Frontend ruft beim Bauen zuerst die Übersicht unter /properties/manifest ab. Sie nennt zu jeder sichtbaren Immobilie die Objektnummer, den Permalink-Namen und den Zeitpunkt der letzten Änderung. Aus dem Vergleich mit dem vorigen Build ergibt sich, welche Detailseiten neu zu rendern sind und welche entfallen. Die Daten einer Immobilie liefert /properties/{object_number}; die Immobilienliste und die Kategorieseiten entstehen aus /properties und /taxonomies.

Verwenden Sie als Kennung einer Immobilie immer die Objektnummer (object_number). Die WordPress-ID einer Immobilie ändert sich bei jeder Aktualisierung durch Ihre Maklersoftware, weil der Import die Immobilie neu anlegt.

Alle Keys der Schnittstelle sind englisch und auf jeder Website gleich, unabhängig von der Sprache der Website und davon, aus welcher Maklersoftware die Immobilien stammen: purchase_price statt kaufpreis, living_area statt wohnflaeche, rooms statt anzahl_zimmer. Jedes Datenfeld nennt unter source_key zusätzlich den Namen, den WordPress und das OpenImmo-Format verwenden und den Sie aus den Einstellungen und dem Customizer kennen. Auch die Suchparameter sind englisch (type, location, price_min); die Parameter des Suchformulars Ihrer WordPress-Website (typ, ort, von-kaufpreis) nimmt die Suche als Aliasse weiter an, sodass eine gefilterte Adresse der Immobilienliste unverändert funktioniert.

Für mehrsprachige Websites mit WPML oder Polylang nennt jede Immobilie unter locale ihre Sprache und unter translations die Objektnummer, WordPress-ID, den Permalink-Namen und die Frontend-Adresse derselben Immobilie in den anderen Sprachen, sodass ein Frontend hreflang-Links und Sprachumschalter daraus baut. /site listet unter languages alle Sprachen mit Code, Locale, Name und dem Verzeichnis, unter dem das Frontend die Sprache ausliefert (prefix: / für die Standardsprache, /en/ für eine weitere). Das Verzeichnis spiegelt die Sprach-URLs von WordPress: Liegt die englische Startseite Ihrer WordPress-Website unter /en/, beginnt auch jede Frontend-Adresse einer englischen Immobilie, Kategorie oder Seite mit /en/, und die englische Immobilienliste liegt unter /en/immobilien/. Eine Sprache ohne eigenes Verzeichnis in WordPress (eigene Domain je Sprache, Sprache als Parameter) erhält ihren Code als Verzeichnis. Enthält das Pfadmuster einer Immobilie den Platzhalter {locale}, bleibt es unverändert, weil Sie die Sprachstruktur dann selbst festlegen.

Der Parameter locale liefert Bezeichnungen, Kategorienamen und Formatierungen in einer anderen Sprache, zum Beispiel locale=en_GB. Das setzt voraus, dass die Sprache in WordPress installiert ist, im Backend Ihrer Website (wp-admin) unter Einstellungen → Allgemein → Sprache der Website auswählbar; WordPress wechselt nur in eine installierte Sprache, andernfalls bleibt die Antwort in der Sprache der Website. WP-ImmoMakler bringt seine eigenen Übersetzungen für Englisch, Spanisch und Französisch mit.

Die Schnittstelle beschreibt sich selbst: Unter /openapi.json liefert sie ein OpenAPI-Dokument für Entwicklungswerkzeuge, unter /llms.txt eine Kurzbeschreibung für KI-gestützte Website-Builder, siehe Maschinenlesbare Beschreibung.

Antworten auf lesende Anfragen tragen einen ETag und Cache-Header. Ein Frontend, das den ETag beim nächsten Abruf im Header If-None-Match zurückschickt, erhält ein 304 Not Modified, wenn sich nichts geändert hat. Ein Frontend im Browser überlässt das am besten dem Browser-Cache.