Sites
Zu den Kernfunktionen der API gehört das Anlegen, Bearbeiten und Löschen von ONE Sites, ebenso das Abrufen von Site-Listen oder der Daten von einzelnen Sites.
Das Abrufen und Bearbeiten von Daten ist immer auf die ONE Sites beschränkt, die dem Provider zugeordnet sind, dessen API-Key für den Zugriff verwendet wird.
Endpunkte
GET https://api.immonex.one/wp-json/one-api/v2/sites
(Liste abrufen)GET https://api.immonex.one/wp-json/one-api/v2/sites/:id
(Details einer Site abrufen)POST https://api.immonex.one/wp-json/one-api/v2/sites
(Site anlegen)PATCH https://api.immonex.one/wp-json/one-api/v2/sites/:id
(Site aktualisieren)DELETE https://api.immonex.one/wp-json/one-api/v2/sites/:id
(Site löschen)
Attribute
Folgende Attribute können bei API-Anfragen zum Anlegen oder Aktualisieren von ONE Sites als Payload (Request-Body) übermittelt werden. Hierbei handelt es sich größtenteils um Kerndaten wie Kontaktdaten und rechtliche Angaben zum/zur Inhaber/in.
= Pflichtfeld beim Anlegen einer neuen ONE Site
Name/Typ | Beschreibung | Beispiel |
---|---|---|
site_slug String |
reine Subdomain ohne Protokoll und Basisdomain (Validierung/Verfügbarkeitsprüfung) | demo-immobilien |
custom_domain String |
benutzerdefinierte Domain, die anstatt der standardmäßigen Subdomain-URL zum Einsatz kommen soll (manuelle Einrichtung nach Übermittlung) | immobilienmakler-website.de |
status String |
mögliche Werte: ACTIVE (Site-Inhalte sind öffentlich verfügbar), INACTIVE (Site-Inhalte sind nicht verfügbar), PENDING_DELETE (Site ist zu löschen) |
|
group String |
Einem Provider können mehrere Gruppen (Sites/Kunden) zugewiesen sein, über die der Funktionsumfang einer ONE Site definiert wird. In diesem Fall kann beim Anlegen/Aktualisieren eine dieser Gruppen mit angegeben werden. | demosites1 |
company String |
Name des Unternehmens (komplette reguläre Firmierung inkl. Rechtsform) | Demo Immobilien GmbH |
company_display | alternative Bezeichnung des Unternehmens für die Ausgabe an Stellen, an denen keine vollständige Firmierung notwendig ist | Demo Immo |
owner_gender String |
Geschlecht der Inhaberin/des Inhabers mögliche Werte: f (weiblich), m (männlich), x (divers) |
m |
owner_name String |
Vor- und Nachname der Inhaberin/des Inhabers (bzw. Geschäftsführer/in) | Heinz Demo |
owner_title | Bezeichnung der Position der genannten Person im Unternehmen | Inhaber |
address String |
Straße und Hausnummer des Bürostandorts | Europa-Allee 1 |
address2 | Zusatzangabe zur Adresse | Industriepark |
zipcode String |
PLZ | 99123 |
city String |
Ort/Stadt | Demostadt |
countrycode | dreistelliger Ländercode (ISO-3166-1 ALPHA-3), möglicher Wert aktuell nur DEU |
DEU |
lat Float |
Breitengrad (Bürostandort) - automatische Geocodierung bei Übermittlung der Adresse | 49.8587840 |
lng Float |
Längengrad (Bürostandort) - automatische Geocodierung bei Übermittlung der Adresse | 6.7854410 |
phone String |
Telefonnummer inkl. nationaler Vorwahl | 0999 123456 |
fax String |
Faxnummer inkl. nationaler Vorwahl | 0999 123457 |
email String |
E-Mail-Adresse (Validierung/Verfügbarkeitsprüfung) | demo@immonex.one |
supervisory_authority String |
Aufsichtsbehörde gem. § 34c GewO, die aktuell für das Unternehmen zuständig ist, für das die ONE Site angelegt wird, inkl. Anschrift und ggfls. weiterer Kontaktdaten (mehrzeilige Angaben möglich) | Ordnungsamt Demostadt Am Brunnenhof 10 99123 Demostadt Fon: 0999 654321 |
vatin String |
Umsatzsteuer-Identifikationsnummer (USt-ID) | DE123456789 |
registry_court String |
Registergericht (Handelsregistereintrag) | Amtsgericht Demostadt |
trade_register_number String |
Handelsregisternummer | HR A 1234 |
cd_color String |
Hexwert der Grund-/Hauptfarbe des Corporate Designs | #E77805 |
about String |
Kurzbeschreibung des Unternehmens (max. zwei Sätze) für den Footer der ONE Site | Demo Immobilien ist Ihr freundlicher und kompetenter Partner für die Vermarktung von und die Suche nach Immobilien in Demostadt! |
memberships Array (String) |
Branchenverband-Mitgliedschaften als Array, das folgende mögliche Elemente enthalten kann: bvfi (BVFI - Bundesverband für die Immobilienwirtschaft), ivd (Immobilienverband Deutschland IVD), rdm (RDM - Ring Deutscher Makler (Regionalverband)) |
['bvfi', 'ivd'] |
Gruppen
Eine Gruppe beschreibt den Funktionumfang einer ONE Site und ist zudem die Grundlage für die Berechnung. Eine ONE Site stellt neben den Kernfunktionen…
- Immobiliendarstellung und -suche
- OpenImmo-Datenimport
…auch Zusatzfunktionen in Form von Modulen bereit, z. B.
- Referenzen
- Anlegen von eigene Seiten und Beiträgen
- Lead Generator
- Bildsets für den Startseiten-Fotoslider
Eine Gruppe stellt also eine beliebige Kombination dieser Module plus den Preis dar, der einem immonex-ONE-Partner monatlich für eine entsprechende ONE Site in Rechnung gestellt wird.
Beispiele
Gruppe partnerkunden_basis (interne Bezeichnung)
- Modul Referenzen
- Modul Lead Generator
monatliche Kosten: 10,00 €
Gruppe partnerkunden_premium
- Modul Referenzen
- Modul Lead Generator
- Modul eigene Seiten/Beiträge
- Modul Startseiten-Bildsets
monatliche Kosten: 15,00 €
Liste abrufen
Eine Liste aller Sites, die dem abfragenden Provider zugeordnet sind, enthält jeweils die wichtigsten Daten pro Site (ID, Status, Domain, Name des Unternehmens) sowie eine URL für den Abruf der Detaildaten.
Endpunkt/RequestGET https://api.immonex.one/wp-json/one-api/v2/sites
Response (Erfolg)200 OK
1 | { |
Details abrufen
Zum Abrufen der Daten einer bestimmten Site wird die entsprechende ID in der URL übermittelt. Hierzu gehören auch Daten, die nur im jeweiligen WordPress-Backend vom Site-Inhaber (gewerblicher Endkunde/Immobilienmakler) selbst, d. h. nicht per API, bearbeitet werden können.
Achtung! Die API-Antwort enhält im Regelfall sensible Informationen wie Zugangsdaten etc. Dieser Endpunkt darf daher nicht in öffentlich zugänglichen Web-Apps o. ä. genutzt werden. Hierfür ist die ONE API generell nicht vorgesehen.
EndpunktGET https://api.immonex.one/wp-json/one-api/v2/sites/:id
Request (Beispiel)GET https://api.immonex.one/wp-json/one-api/v2/sites/123
Response (Erfolg)200 OK
1 | { |
Site anlegen
Verfügbarkeit und Validität der Attribute site_slug
(Subdomain) und email
(E-Mail-Adresse des Site-Inhabers) sollten bereits vor dem Absenden des Requests zum Anlegen einer ONE Site geprüft werden. Hierfür stehen separate Endpunkte zur Verfügung:
Im Rahmen des Erstellungsvorgangs werden nur Textinhalte übertragen. Binärdaten wie Bilddateien können im Anschluss mit weiteren Requests ergänzt werden.
Wird eine individuelle Domain übermittelt (custom_domain
), ist die neue ONE Site nicht direkt hierüber erreichbar. Die Einrichtung erfolgt zeitnah und nach vorheriger Abstimmung der hierfür notwendigen DNS-Aktualisierung manuell.
Endpunkt/Request (Beispiel)POST https://api.immonex.one/wp-json/one-api/v2/sites
1 | { |
Konnte die neue ONE Site erfolgreich angelegt werden, wird ein kompletter Datensatz zurückgeliefert.
Response (Erfolg)200 OK
1 | { |
Response (Site-Slug/URL bereits vergeben)400 Bad Request
1 | { |
Site aktualisieren
Beim Aktualisieren von ONE Sites können die o. g. Attribute geändert werden. (Der jeweilige Inhaber hat die Möglichkeit, weitere Inhalte im WordPress-Backend seiner ONE Site zu erfassen.)
Bei einem PATCH
-Request werden nur die übermittelten Angaben aktualisiert, alle vorhandenen Werte bleiben unverändert.
EndpunktPATCH https://api.immonex.one/wp-json/one-api/v2/sites/:id
Request (Beispiel)PATCH https://api.immonex.one/wp-json/one-api/v2/sites/321
1 | { |
Bei Aktualisierung der Adresse werden die Koordinaten (
lat
undlng
) per Geocodierung automatisch neu ermittelt und müssen daher nicht explizit mit übertragen werden.
Nach einer erfolgreichen Aktualisierung wird wiederum ein kompletter Datensatz zurückgeliefert.
Response (Erfolg)200 OK
1 | { |
Site löschen
Die Löschung einer ONE Site per API führt nicht zu einer direkten Löschen, hierbei wird lediglich der Status in PENDING_DELETE
geändert. Die Site-Inhalte sind dann nicht mehr öffentlich verfügbar und werden im Regelfall zum Ende des laufenden Monats gelöscht.
Eine Löschanfrage dieser Art kann somit per PATCH
-Request rückgängig gemacht werden, bei dem als Wert des Attributs status
entweder ACTIVE
oder INACTIVE
übermittelt wird.
EndpunktDELETE https://api.immonex.one/wp-json/one-api/v2/sites/:id
Request (Beispiel)DELETE https://api.immonex.one/wp-json/one-api/v2/sites/321
Response (Erfolg)200 OK
1 | { |