Voraussetzungen

Voraussetzung für die Nutzung der ONE API ist ein aktives Provider-Benutzerkonto sowie der zugehörige API-Key.

Beispiel: Anlegen einer ONE Site

Der typische Ablauf beim Anlegen einer immonex ONE Site gestaltet sich wie folgt:

  1. JWT anfordern
  2. Mailadresse prüfen
  3. Subdomain generieren
  4. Site anlegen
  5. Logo ergänzen
  6. Inhaberfoto hochladen

In den folgenden Codebeispielen kommen die HTTP-Clients Guzzle (PHP) bzw. axios (JavaScript) zum Einsatz.

JWT anfordern

Wir fordern ein Token mit dem Demo-API-Key “ABC123” an (Details).

cURL

1
2
3
4
curl --header "Content-Type: application/json" \
    --request POST \
    --data '{"api_key":"ABC123"}' \
    https://api.immonex.one/wp-json/jwt-auth/v1/token

PHP

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
$authClient = new \GuzzleHttp\Client(['base_uri' => 'https://api.immonex.one/wp-json/jwt-auth/v1/']);

try {
    $response = $authClient->post('token', ['json' => ['api_key' => 'ABC123']]);
} catch (\GuzzleHttp\Exception\TransferException $e) {
    // Fehlerbehandlung...
    var_dump($e->getMessage());
}

$authData = json_decode((string) $response->getBody(), true);

if (isset($authData['token'])) {
    $client = new \GuzzleHttp\Client([
        'base_uri' => 'https://api.immonex.one/wp-json/one-api/v2/',
        'headers' => [
            'Authorization' => 'Bearer ' . $authData['token'],
            'Accept' => 'application/json'
        ]
    ]);
} else {
    // Fehlerbehandlung...
}

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
axios.post('https://api.immonex.one/wp-json/jwt-auth/token',
    { 'api_key': 'ABC123' })
    .then(function (response) {
        if (response.status === 200) {
            axios.defaults.headers.common['Authorization'] = 'Bearer ' + response.data.token;
        } else {
            // Fehlerbehandlung...
            console.log(response);
        }
    })
    .catch(function (error) {
        // Fehlerbehandlung...
        console.log(error);
    });

Response (Erfolg)

200 OK

1
2
3
4
{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9pbngtb25lLmxvY2FsIiwiaWF0IjoxNTczNDY5MDMyLCJuYmYiOjE1NzM0NjkwMzIsImV4cCI6MTU3MzU1NTQzMiwiZGF0YSI6eyJ1c2VyIjp7ImlkIjoiNDUifX19.B7V2AgLQsZG8DYXgxB2wxkkiZV86Ot0F8Dh5oU-hJkU",
    "provider": "Demo-Provider"
}

Mailadresse prüfen

Die Inhaber-Mailadresse für die neu anzulegende ONE Site soll **info@abc-xyz.immo** lauten. Wir prüfen nun mit dem zuvor angeforderten JWT, ob diese Adresse gültig und noch verfügbar ist (Details).

cURL

1
2
3
curl --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9pbngtb25lLmxvY2FsIiwiaWF0IjoxNTczNDY5MDMyLCJuYmYiOjE1NzM0NjkwMzIsImV4cCI6MTU3MzU1NTQzMiwiZGF0YSI6eyJ1c2VyIjp7ImlkIjoiNDUifX19.B7V2AgLQsZG8DYXgxB2wxkkiZV86Ot0F8Dh5oU-hJkU" \
    --request GET \
    https://api.immonex.one/wp-json/one-api/v2/site-email-addresses/info@abc-xyz.immo

PHP

1
2
3
4
5
6
7
8
try {
    $response = $client->get('site-email-addresses/info@abc-xyz.immo');
} catch (\GuzzleHttp\Exception\TransferException $e) {
    // Fehlerbehandlung
    var_dump($e->getMessage());
}

$valid = $response->getStatusCode() == 200;

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var validEmail = '';

axios.get('https://api.immonex.one/wp-json/one-api/v2/site-email-addresses/info@abc-xyz.immo')
    .then(function (response) {
        if (response.status === 200) {
            validEmail = response.data.data.email;
        } else {
            // Fehlerbehandlung...
            console.log(response);
        }
    })
    .catch(function (error) {
        // Fehlerbehandlung...
        console.log(error);
    });

Response (Erfolg)

200 OK

1
2
3
4
5
6
7
{
    "code": "valid",
    "data": {
        "email": "info@abc-xyz.immo",
        "valid": 1
    }
}

Subdomain generieren

Die Subdomain einer ONE Site kann prinzipiell frei definiert werden, ebenso einfach ist aber die automatisierte Generierung anhand von Firma und Ort des Inhaber-Unternehmens (Details).

cURL

1
2
3
4
5
curl --header "Content-Type: application/json" \
    --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9pbngtb25lLmxvY2FsIiwiaWF0IjoxNTczNDY5MDMyLCJuYmYiOjE1NzM0NjkwMzIsImV4cCI6MTU3MzU1NTQzMiwiZGF0YSI6eyJ1c2VyIjp7ImlkIjoiNDUifX19.B7V2AgLQsZG8DYXgxB2wxkkiZV86Ot0F8Dh5oU-hJkU" \
    --request POST \
    --data '{"company":"ABC Xyz Immo","city":"Demostadt"}' \
    https://api.immonex.one/wp-json/one-api/v2/site-urls

PHP

1
2
3
4
5
6
7
8
9
10
11
12
13
try {
    $response = $client->post('site-urls', [
        'json' => [
            'company' => 'ABC Xyz Immo',
            'city' => 'Demostadt'
        ]
    ]);
} catch (\GuzzleHttp\Exception\TransferException $e) {
    // Fehlerbehandlung
    var_dump($e->getMessage());
}

$siteUrlData = json_decode((string) $response->getBody(), true)['data'];

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var siteUrlData = {};

axios.post('https://api.immonex.one/wp-json/one-api/v2/site-urls', {
        'company': 'ABC Xyz Immo',
        'city': 'Demostadt'
    })
    .then(function (response) {
        if (response.status === 200) {
            siteUrlData = response.data.data;
        } else {
            // Fehlerbehandlung...
            console.log(response);
        }
    })
    .catch(function (error) {
        // Fehlerbehandlung...
        console.log(error);
    });

Response (Erfolg)

200 OK

1
2
3
4
5
6
7
8
9
{
    "data": {
        "protocol": "https://",
        "slug": "abc-xyz-immo",
        "domain": "abc-xyz-immo.immonex.one",
        "url": "https://abc-xyz-immo.immonex.one",
        "sld": "immonex.one"
    }
}

Site anlegen

Nun wird eine ONE Site mit einem minimalen Datensatz erstellt (Details).

cURL

1
2
3
4
5
curl --header "Content-Type: application/json" \
    --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9pbngtb25lLmxvY2FsIiwiaWF0IjoxNTczNDY5MDMyLCJuYmYiOjE1NzM0NjkwMzIsImV4cCI6MTU3MzU1NTQzMiwiZGF0YSI6eyJ1c2VyIjp7ImlkIjoiNDUifX19.B7V2AgLQsZG8DYXgxB2wxkkiZV86Ot0F8Dh5oU-hJkU" \
    --request POST \
    --data '{"site_slug": "abc-xyz-immo","company": "ABC Xyz Immobilien","owner_gender": "f","owner_name": "Lisa X. Ample","address": "Demostraße 1","zipcode": "99999","city": "Demostadt","phone": "0999 1234567","email": "info@abc-xyz.immo","supervisory_authority": "Ordnungsamt Demostadt, Am Testerhof 20, 99999 Demostadt"}' \
    https://api.immonex.one/wp-json/one-api/v2/sites

PHP

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
$siteAttributes = [
    'site_slug' => $siteUrlData['slug'],
    'company' => 'ABC Xyz Immo',
    'owner_gender' => 'f',
    'owner_name' => 'Lisa X. Ample',
    'address' => 'Demostraße 1',
    'zipcode' => '99999',
    'city' => 'Demostadt',
    'phone' => '0999 1234567',
    'email' => 'info@abc-xyz.immo',
    'supervisory_authority' => 'Ordnungsamt Demostadt, Am Testerhof 20, 99999 Demostadt'
];

try {
    $response = $client->post('sites', [
        'json' => $siteAttributes
    ]);
} catch ( \GuzzleHttp\Exception\TransferException $e ) {
    // Fehlerbehandlung
    var_dump($e->getMessage());
}

$newSiteData = json_decode((string) $response->getBody(), true)['data'];

JavaScript

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
var newSiteData = {};

const siteAttributes = {
    'site_slug': siteUrlData.slug,
    'company': 'ABC Xyz Immobilien',
    'owner_gender': 'f',
    'owner_name': 'Lisa X. Ample',
    'address': 'Demostraße 1',
    'zipcode': '99999',
    'city': 'Demostadt',
    'phone': '0999 1234567',
    'email': 'info@abc-xyz.immo',
    'supervisory_authority': 'Ordnungsamt Demostadt, Am Testerhof 20, 99999 Demostadt'
}

axios.post('https://api.immonex.one/wp-json/one-api/v2/sites', siteAttributes)
    .then(function (response) {
        if (response.status === 200) {
            newSiteData = response.data.data;
        } else {
            // Fehlerbehandlung...
            console.log(response);
        }
    })
    .catch(function (error) {
        // Fehlerbehandlung...
        console.log(error);
    });

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
{
    "data": {
        "site_id": 123,
        "url": "https://abc-xyz-immo.immonex.one",
        "admin_url": "https://abc-xyz-immo.immonex.one/bearbeiten",
        "site_domain": "abc-xyz-immo.immonex.one",
        "status": "ACTIVE",
        "group": "early_birds",
        "booked_extra_modules": [],
        "home_slider_imageset": "default",
        "company": "ABC Xyz Immobilien",
        "company_display": "",
        "address": "Demostraße 1",
        "address2": "",
        "zipcode": "99999",
        "city": "Demostadt",
        "countrycode": "DEU",
        "lat": 49.8587840,
        "lng": 6.7854410,
        "phone": "0999 1234567",
        "fax": "",
        "email": "info@abc-xyz.immo",
        "www": "https://abc-xyz-immo.immonex.one",
        "vatin": "",
        "registry_court": "",
        "trade_register_number": "",
        "supervisory_authority": "Ordnungsamt Demostadt, Am Testerhof 20, 99999 Demostadt",
        "cd_color": "#E77805",
        "logo_url": "httpd://assets.immonex.one/wp-content/uploads/sites/123/branding/logo-abc-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-abc-xyz-immo-large.jpg",
        "about": "<strong>ABC Xyz 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
        }
    }
}

Logo ergänzen

Das Logo wird in diesem Beispiel nicht direkt übermittelt, stattdessen wird eine URL übergeben, über die die Bilddatei (Typ logo) API-seitig heruntergeladen und zur im vorherigen Schritt erstellten ONE Site mit der ID 123 hinzugefügt werden soll (Details).

cURL

1
2
3
4
5
curl --header "Content-Type: application/json" \
    --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9pbngtb25lLmxvY2FsIiwiaWF0IjoxNTczNDY5MDMyLCJuYmYiOjE1NzM0NjkwMzIsImV4cCI6MTU3MzU1NTQzMiwiZGF0YSI6eyJ1c2VyIjp7ImlkIjoiNDUifX19.B7V2AgLQsZG8DYXgxB2wxkkiZV86Ot0F8Dh5oU-hJkU" \
    --request POST \
    --data '{"image_url": "https://my.image.url/logo.png"}' \
    https://api.immonex.one/wp-json/one-api/v2/sites/123/images/logo

PHP

1
2
3
4
5
6
7
8
9
10
try {
    $response = $client->post('sites/' . $newSiteData['site_id'] . '/logo', [
        'json' => ['image_url' => 'https://my.image.url/logo.png']
    ]);
} catch ( \GuzzleHttp\Exception\TransferException $e ) {
    // Fehlerbehandlung
    var_dump($e->getMessage());
}

$logoVariants = json_decode((string) $response->getBody(), true)['data'];

JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
var logoVariants = {};

axios.post('https://api.immonex.one/wp-json/one-api/v2/sites' + newSiteData['site_id'] + '/images/logo',
    { 'image_url': 'https://my.image.url/logo.png' })
    .then(function (response) {
        if (response.status !== 200) {
            logoVariants = response.data.data;
        } else {
            // Fehlerbehandlung...
            console.log(response);
        }
    })
    .catch(function (error) {
        // Fehlerbehandlung...
        console.log(error);
    });

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": [
        {
            "type": "logo",
            "size": "large",
            "url": "https://assets.immonex.one/wp-content/uploads/sites/123/branding/logo-abc-xyz-immo-large.png"
        },
        {
            "type": "logo",
            "size": "medium",
            "url": "https://assets.immonex.one/wp-content/uploads/sites/123/branding/logo-abc-xyz-immo-medium.png"
        },
        {
            "type": "logo",
            "size": "small",
            "url": "https://assets.immonex.one/wp-content/uploads/sites/123/branding/logo-abc-xyz-immo-small.png"
        },
        {
            "type": "logo",
            "size": "org",
            "url": "https://assets.immonex.one/wp-content/uploads/sites/123/branding/logo-abc-xyz-immo-org.png"
        }
    ]
}

Inhaberfoto hochladen

Im letzten Schritt soll eine lokale Bilddatei (Typ owner_photo) direkt hochgeladen werden. Die Vorgehensweise entspricht hierbei der zuvor verwendeten URL-basierten Variante, anstelle der JSON-Daten werden im Request-Body aber die entsprechenden Binärdaten übertragen (Details).

cURL

1
2
3
4
5
curl --header "Content-Type: image/jpeg" \
    --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9pbngtb25lLmxvY2FsIiwiaWF0IjoxNTczNDY5MDMyLCJuYmYiOjE1NzM0NjkwMzIsImV4cCI6MTU3MzU1NTQzMiwiZGF0YSI6eyJ1c2VyIjp7ImlkIjoiNDUifX19.B7V2AgLQsZG8DYXgxB2wxkkiZV86Ot0F8Dh5oU-hJkU" \
    --request POST \
    --data-binary @photo.jpg \
    https://api.immonex.one/wp-json/one-api/v2/sites/123/images/owner_photo

PHP

1
2
3
4
5
$body = fopen('/path/to/photo.jpg', 'r');
$response = $client->post('sites/' . $newSiteData['site_id'] . '/owner_photo', ['body' => $body]);
fclose($body);

$photoVariants = json_decode((string) $response->getBody(), true)['data'];

JavaScript

Der Einfachheit halber gehen wir in diesem Beispiel davon aus, dass das zu übermittelnde Foto mittels Vue Croppa in einer Web-App geladen/bearbeitet wurde und der Code innerhalb einer asynchronen Methode ausgeführt wird.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var photoVariants = {};

const editedPhoto = await this.photo.promisedBlob('image/jpeg', 0.8);

axios.post('https://api.immonex.one/wp-json/one-api/v2/sites' + newSiteData['site_id'] + '/images/owner_photo',
    photo, { headers: { 'Content-Type': 'image/jpeg' } })
    .then(function (response) {
        if (response.status !== 200) {
            photoVariants = response.data.data;
        } else {
            // Fehlerbehandlung...
            console.log(response);
        }
    })
    .catch(function (error) {
        // Fehlerbehandlung...
        console.log(error);
    });

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": [
        {
            "type": "owner_photo",
            "size": "large",
            "url": "https://assets.immonex.one/wp-content/uploads/sites/123/branding/owner-photo-abc-xyz-immo-large.jpg"
        },
        {
            "type": "owner_photo",
            "size": "medium",
            "url": "https://assets.immonex.one/wp-content/uploads/sites/123/branding/owner-photo-abc-xyz-immo-medium.jpg"
        },
        {
            "type": "owner_photo",
            "size": "small",
            "url": "https://assets.immonex.one/wp-content/uploads/sites/123/branding/owner-photo-abc-xyz-immo-small.jpg"
        },
        {
            "type": "owner_photo",
            "size": "org",
            "url": "https://assets.immonex.one/wp-content/uploads/sites/123/branding/owner-photo-abc-xyz-immo-org.jpg"
        }
    ]
}