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…

…auch Zusatzfunktionen in Form von Modulen bereit, z. B.

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)

monatliche Kosten: 10,00 €

Gruppe partnerkunden_premium

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/Request
GET https://api.immonex.one/wp-json/one-api/v2/sites

Response (Erfolg)
200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
"data": [
{
"site_id": "128",
"status": "ACTIVE",
"domain": "demo-x.immonex.one",
"name": "Demo X Immobilien",
"link": "https://api.immonex.one/wp-json/one-api/v2/sites/128"
},
{
"site_id": "144",
"status": "ACTIVE",
"domain": "demo-y.immonex.one",
"name": "Demo Y",
"link": "https://api.immonex.one/wp-json/one-api/v2/sites/144"
},
{
"site_id": "196",
"status": "PENDING_DELETE",
"domain": "immobilienmakler-website.de",
"name": "ZZZ Immo",
"link": "https://api.immonex.one/wp-json/one-api/v2/sites/196"
},
...
]
}

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.

Endpunkt
GET 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
"data": {
"site_id": 123,
"url": "https://x-demo-immo.immonex.one",
"admin_url": "https://x-demo-immo.immonex.one/bearbeiten",
"site_domain": "x-demo-immo.immonex.one",
"pending_custom_domain": "www.x-demo-immobilien.de",
"status": "ACTIVE",
"group": "early_birds",
"booked_extra_modules": [],
"home_slider_imageset": "default",
"company": "X Demo Immobilien",
"company_display": "X Demo Immo",
"address": "Teststraße 1",
"address2": "",
"zipcode": "99123",
"city": "Demostadt",
"countrycode": "DEU",
"lat": 49.8587840,
"lng": 6.7854410,
"phone": "0999 123456",
"fax": "",
"email": "x-demo@immonex.one",
"www": "https://x-demo-immo.immonex.one",
"vatin": "DE123456789",
"registry_court": "Amtsgericht Demostadt",
"trade_register_number": "HR A 1234",
"supervisory_authority": "Ordnungsamt Demostadt\r\nAm Brunnenhof 10\r\n99123 Demostadt",
"cd_color": "#E77805",
"logo_url": "httpd://assets.immonex.one/wp-content/uploads/sites/123/branding/logo-x-demo-immobilien-large.png",
"owner_gender": "f",
"owner_name": "Linda Demo",
"owner_title": "Inhaberin",
"owner_photo_url": "https://assets.immonex.one/wp-content/uploads/sites/123/branding/owner-photo-x-demo-immobilien-large.jpg",
"about": "<strong>X Demo Immo</strong> ist Ihr freundlicher und kompetenter Partner für die Vermarktung von und die Suche nach Immobilien in <strong>Demostadt</strong>!",
"memberships": ['bvfi'],
"rating_embed_code_1": "",
"rating_embed_code_2": "",
"rating_embed_code_3": "",
"rating_embed_code_4": "",
"wp": {
"user_login": "redaktion-XXXX",
"user_pass": "***"
},
"oi_import": {
"ftp_host": "import.immonex.one",
"ftp_user": "import-XXXX",
"ftp_pwd": "***",
"customer_no": XXXX
}
}
}

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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"site_slug": "xyz-immo",
"custom_domain": "www.abc-xyz.immo",
"company": "XYZ Immobilien GmbH",
"company_display": "XYZ IMMO",
"address": "Demostraße 14",
"zipcode": "99123",
"city": "Demostadt",
"phone": "0999 5671234",
"email": "info@abc-xyz.immo",
"owner_gender": "f",
"owner_name": "Lisa X. Ample",
"supervisory_authority": "Ordnungsamt Demostadt\r\nAm Brunnenhof 10\r\n99123 Demostadt",
"cd_color": "#011CD0"
}

Konnte die neue ONE Site erfolgreich angelegt werden, wird ein kompletter Datensatz zurückgeliefert.

Response (Erfolg)
200 OK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
"data": {
"site_id": 321,
"url": "https://xyz-immo.immonex.one",
"admin_url": "https://xyz-immo.immonex.one/bearbeiten",
"site_domain": "xyz-immo.immonex.one",
"pending_custom_domain": "www.abc-xyz.immo",
"status": "ACTIVE",
"group": "partnerkunden1",
"booked_extra_modules": [],
"home_slider_imageset": "default",
"company": "XYZ Immmobilien GmbH",
"company_display": "XYZ IMMO",
"address": "Demostraße 14",
"address2": "",
"zipcode": "99123",
"city": "Demostadt",
"countrycode": "DEU",
"lat": 49.8587840,
"lng": 6.7854410,
"phone": "0999 5671234",
"fax": "",
"email": "info@abc-xyz.immo",
"www": "https://xyz-immo.immonex.one",
"vatin": "",
"registry_court": "",
"trade_register_number": "",
"supervisory_authority": "Ordnungsamt Demostadt\r\nAm Brunnenhof 10\r\n99123 Demostadt",
"cd_color": "#011CD0",
"logo_url": "httpd://assets.immonex.one/wp-content/uploads/sites/123/branding/logo-xyz-immo-large.png",
"owner_gender": "f",
"owner_name": "Lisa X. Ample",
"owner_title": "Inhaberin",
"owner_photo_url": "https://assets.immonex.one/wp-content/uploads/sites/123/branding/owner-photo-xyz-immo-large.jpg",
"about": "<strong>XYZ IMMO</strong> ist Ihr freundlicher und kompetenter Partner für die Vermarktung von und die Suche nach Immobilien in <strong>Demostadt</strong>!",
"memberships": [],
"rating_embed_code_1": "",
"rating_embed_code_2": "",
"rating_embed_code_3": "",
"rating_embed_code_4": "",
"wp": {
"user_login": "redaktion-XXXX",
"user_pass": "***"
},
"oi_import": {
"ftp_host": "import.immonex.one",
"ftp_user": "import-XXXX",
"ftp_pwd": "***",
"customer_no": XXXX
}
}
}

Response (Site-Slug/URL bereits vergeben)
400 Bad Request

1
2
3
4
5
6
7
8
9
10
{
"code": "rest_invalid_param",
"message": "Ungültige(r) Parameter: site_slug",
"data": {
"status": 400,
"params": {
"site_slug": "Ungültiger Parameter."
}
}
}

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.

Endpunkt
PATCH 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
2
3
4
5
{
"address": "Beispielgasse 28",
"zipcode": "99124",
"phone": "0999 123123"
}

Bei Aktualisierung der Adresse werden die Koordinaten (lat und lng) 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
"data": {
"site_id": 321,
"url": "https://xyz-immo.immonex.one",
"admin_url": "https://xyz-immo.immonex.one/bearbeiten",
"site_domain": "xyz-immo.immonex.one",
"pending_custom_domain": "www.abc-xyz.immo",
"status": "ACTIVE",
"group": "partnerkunden1",
"booked_extra_modules": [],
"home_slider_imageset": "default",
"company": "XYZ Immmobilien GmbH",
"company_display": "XYZ IMMO",
"address": "Beispielgasse 28",
"address2": "",
"zipcode": "99124",
"city": "Demostadt",
"countrycode": "DEU",
"lat": 49.8587840,
"lng": 6.7854410,
"phone": "0999 123123",
...
}
}

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.

Endpunkt
DELETE 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
2
3
4
5
6
7
8
9
10
11
{
"data": {
"site_id": 321,
"url": "https://xyz-immo.immonex.one",
"admin_url": "https://xyz-immo.immonex.one/bearbeiten",
"site_domain": "xyz-immo.immonex.one",
"pending_custom_domain": "www.abc-xyz.immo",
"status": "PENDING_DELETE",
...
}
}