Mit der CASAGATEWAY API können Sie Objektdaten an eine externe Webseite exportieren und Interessentenanfragen versenden. Mit einem CASAONE Pro Account, können Sie die Anfragen sogar direkt in CASAONE erhalten und beantworten.

SwissRETS export per HTTP

Diese Schnittstelle ermöglicht das transferieren von Objektdaten eines Veröffentlichungs-Portal (Publisher) auf CASAGATEWAY mittels dem SwissRETS Standart. Dies wird vollständig über HTTP ermöglich und benötigt somit keine FTP Abhängigkeiten. Das XML kann beliebig von dem CASAGATEWAY API jederzeit abgeholt werden. CASAGATEWAY generiert und liefert per response dann direkt ein XML body. Ebenfalls wird CASAGATEWAY pokes/hooks ausführen sobald jegliche Änderungen oder Mutationen zu den Daten vorgenommen wurden. Diese werden per GET an einem vorkonfigurierten URI ausgelöst.

Wie erhalte ich die benötigten Zugangsdaten?

Je nachdem, welche Funktion Sie benutzen möchten, benötigen Sie unterschiedliche Zugangsdaten. Um Objekte an eine externe Webseite zu exportieren, benötigen Sie lediglich den "API-Key" und den "Private-Key". Wenn Sie zusätzliche Interessentenanfragen über die API versenden möchten, benötigen Sie ausserdem den "CASAMAIL Provider", den "CASAMAIL Publisher" und einen SimpleAuthUser (Benutzername & Passwort).

Die Zugangsdaten können Sie bei unserem Support bestellen.

Zugangsdaten anfordern

Wie kann ich ein XML generieren und abrufen (fetch)?

Der Request läuft mittels gewöhnlichem http und einem HMAC handshake, der durch ein API Key und einem Private Key generiert wird, ab. Dieser wird von CASAGATEWAY zur Verfügung gestellt. Bitte beachten Sie das Sie den Private Key nie öffentlich zugänglich machen. SwissRETS Dieses XML kann beliebig mit Ihrer Infrastruktur abgeglichen werden, oder Sie nutzen das XML gleich als Speicher-Medium. Das Parsen und Persistieren dieser XML liegt in den Händen des Konsumenten. Allerdings bieten wir einige PHP Klassen an die das interpretieren von Werten vereinfacht.

Casasoft Standards auf GitHub

Authentifizierung Mittels HMAC

Hier wird abstrahiert wie der request hmac key generiert wird und an einem request string angehängt wird. Achten Sie das der Private Key niemals im schlussendlichem request angegeben wird. Anstelle wird ein hmac key und das öffentliche api key mitgeliefert. Die + Zeichen dienen nur zur visuellen trennung. sortiere die optionen alphabetisch.

checkstring = key1+value1+key2+value2+key3+value3+PRIVATE_KEY+TIMESTAMP
HMAC = hash checkstring with sha256 // take note that this is not the built in php hash_hmac function just a hash with sha256
xml_response = [GET] "http://casagateway.ch/rest/publisher-properties?hmac=HMAC&apikey=API_KEY&timestamp=TIMESTAMP&key1=value1&key2=value2&key3=value3"

Welche Standarte sind mit dieser HTTP-Methodik verfügbar?

CASAGATEWAY wird versuchen die Versionsnummer beim exportieren zu respektieren kann aber nur die erste stelle (haupt Version) garantieren. in welcher version (2.*.*) das es dann effektiv daherkommt wird dan im jeweiligem response deklariert.

PHP Beispiel

Dieses Beispiel zeigt eine einfache PHP Funktion die mittels CURL diese Abfrage generiert und ausführt.

function getSwissRETS($apikey, $privateKey, $options){
    //specify the current UnixTimeStamp
    $timestamp = time();
 
    //specify your api key
    $apikey = $apikey;
 
    //specify your private key
    $privatekey = $privateKey;
 
    //sort the options alphabeticaly and combine it into the checkstring
    ksort($options);
    $checkstring = '';
    foreach ($options as $key = $value) {
        $checkstring .= $key . $value;
    }
     
    //add private key at end of the checkstring
    $checkstring .= $privatekey;
 
    //add the timestamp at the end of the checkstring
    $checkstring .= $timestamp;
 
    //hash it to specify the hmac
    $hmac = hash('sha256', $checkstring, false);
 
    //combine the query (DONT INCLUDE THE PRIVATE KEY!!!)
    $query = array(
        'hmac' = $hmac,
        'apikey' = $apikey,
        'timestamp' = $timestamp
    ) + $options;
 
    //build url
    $url = 'https://casagateway.ch/rest/publisher-properties?' . http_build_query($query, '', '&');
    $url = urldecode($url);
     
    //execute request with CURL
    $response = false;
    try {
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        if($httpCode == 404) {
            $response = $httpCode;
        }
        curl_close($ch);
    } catch (Exception $e) {
        $response =  $e-getMessage() ;
    }
 
    return $response;
}
 
$options = array(
'format' => 'swissrets:2.7' // legacy version available with "casa-xml" or a version < 1.0 such as 0.1.0
//further options might be added later
);
$xml_string = getSwissRETS('API_KEY_GOES_HERE', 'PRIVATE_KEY_GOES_HERE', $options);

//use the $xml_string as you see fit from here on

Welche Optionen kann ich nutzten

company: company_slug um nach Firmen zu filtern. Dies ist Sinnvol für grössere Portal/Publishers, die die Imports Unterteilen möchten.

Welche Firmen (Provider) wollen für mich (Publisher) Objekte versenden und wie erhalte ich deren company_slug?

Mit dem gleichen API Schlüssel und Verfahren kann unter dem Link "https://casagateway.ch/rest/publisher-companies" eine JSON Liste aller Firmen bezogen werden die auf diese Platform Objekte zum veröffentlichen bereit haben.

Wie weiss ich wenn sich etwas aktualisiert hat?

CASAGATEWAY wird bei jeglichen Änderungen einen poke/hook auf eine vordefinierte URI ausführen (über einen POST request). Diese kann z.B. wie folgt aussehen:

http://your-new-website.ch/casagateway-change-alert?timestamp=1234567890&a_super_secret_key=12k34k5j2hkj34k2j3bkj2b3kj3

sollte es sich bei ihnen um ein Portal handeln kann auch noch zusätzlich der Slug der Firma der URI angehängt werden - was dann wie folgt aussehen könnte

http://your-portal.ch/casagateway-change-alert?timestamp=1234567890&a_super_secret_key=12k34k5j2hkj34k2j3bkj2b3kj3&company=test-company-slug

Hier könnte ein Script sein welches ein Import bei der nächsten Gelegenheit ausführt. Allerdings sollten die Imports nur asynchron angestossen werden oder zukünftig vermerkt werden. Während diesem Aufrufs sollte kein Import ausgeführt werden da der CASAGATEWAY den Request nach einer kurzen Zeit abbrechen wird.

Postman Beispiel

{
    "info": {
        "_postman_id": "c2613351-2d56-4378-b7ab-1f2b1d679639",
        "name": "CASAGATEWAY",
        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "item": [
        {
            "name": "SwissRETS export per HTTP",
            "event": [
                {
                    "listen": "prerequest",
                    "script": {
                        "id": "73feb881-d49a-450d-aed4-e271046ea870",
                        "exec": [
                            "// fetches required privatekey and generates a timestamp",
                            "const privatekey = pm.request.url.query.get('privatekey');",
                            "const timestamp = Date.now();",
                            "",
                            "// gets all option parameters / sorts them alphabeticaly / and turn them into a string",
                            "const optionParams = pm.request.url.query.all().filter((param) = !['apikey', 'privatekey', 'hmac', 'timestamp'].includes(param.key) && !param.disabled);",
                            "optionParams.sort((a,b) = a.key.toString().localeCompare(b.key))",
                            "const optionsStr = optionParams.reduce((acc, curVal) = {",
                            "    return `${acc}${curVal.key}${curVal.value}`;",
                            "}, '');",
                            "",
                            "// combines the previous values into a hmacString and hashes it using sha256",
                            "const hmacString = `${optionsStr}${privatekey}${timestamp}`;",
                            "const hmac = CryptoJS.enc.Hex.stringify(CryptoJS.SHA256(hmacString));",
                            "",
                            "// sets timestamp and hmac",
                            "pm.request.url.query.add({key: 'timestamp', value: timestamp.toString()});",
                            "pm.request.url.query.add({key: 'hmac', value: hmac});",
                            "",
                            "// removes the privatekey from actually being sent. This would defeat the purpose.",
                            "pm.request.url.query.remove('privatekey');"
                        ],
                        "type": "text/javascript"
                    }
                }
            ],
            "request": {
                "method": "GET",
                "header": [],
                "url": {
                    "raw": "https://casagateway.ch/rest/publisher-properties?privatekey=PRIVATE_KEY_HERE&apikey=PUBLIC_KEY_HERE&format=swissrets:2",
                    "protocol": "https",
                    "host": [
                        "casagateway",
                        "ch"
                    ],
                    "path": [
                        "rest",
                        "publisher-properties"
                    ],
                    "query": [
                        {
                            "key": "privatekey",
                            "value": "PRIVATE_KEY_HERE",
                            "description": "(Required) Private key of publisher defined within CASAGATEWAY. This will be converted into a HMAC string."
                        },
                        {
                            "key": "apikey",
                            "value": "PUBLIC_KEY_HERE",
                            "description": "(Required) Public key of publisher defined within CASAGATEWAY"
                        },
                        {
                            "key": "format",
                            "value": "swissrets:2",
                            "description": "(Required) Format to be returned within response body. For Example: swissrets:2 or casa-xml or idx:3.1"
                        },
                        {
                            "key": "company",
                            "value": "company-slug-here",
                            "description": "(Optional) You can filter the results by specifying a company slug. This usualy is only usefull for publishers that have a lot of companies and are splitting their imports based on companies. Company slugs are defined within CASAGATEWAY.",
                            "disabled": true
                        }
                    ]
                },
                "description": "Fetch Properties from a CASAGATEWAY publisher represeneted as a real estate standard."
            },
            "response": []
        }
    ],
    "protocolProfileBehavior": {}
}

CASAMAIL Restful post

Wie funktioniert es?

Anstatt eine E-Mail zu versenden soll hier ein POST request zu casamail.ch gemacht werden. Diese Anfrage wird dann in der CASAMAIL DB abgespeichert und von dort aus mehrfach verteilt.

Welche Werte sind möglich?

Folgend finden Sie eine Übersicht-Liste aller Werte die eine msg (Nachricht) enthalten kann:

x: Wert kann nicht bestimmt werden.

Fett: Pflichtfeld

Beispiel PHP POST mit CURL

<?php
$data = $postdata;
$data['email'] = $postdata['emailreal'];
$data['provider'] = $customerid;
$data['publisher'] = $publisherid;
$data['lang'] = substr(get_bloginfo('language'), 0, 2);
$data['property_reference'] = $this->getFieldValue('referenceId');
$data['property_street'] = $this->getFieldValue('address_streetaddress');
$data['property_postal_code'] = $this->getFieldValue('address_postalcode');
$data['property_locality'] = $this->getFieldValue('address_locality');
$data['property_country'] = $this->getFieldValue('address_country');
$data['property_country'] = $this->getFieldValue('address_country');
/* ... */

$data_string = json_encode($data); 

$ch = curl_init('https://message.casasoft.com/api/msg');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); 
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string); 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 
curl_setopt($ch, CURLOPT_HTTPHEADER, array( 
'Content-Type: application/json', 
'Content-Length: ' . strlen($data_string)) 
);
curl_setopt($ch, CURLOPT_USERPWD, "simpleauthuser:simpleauthpassword");

$result = curl_exec($ch);
$json = json_decode($result, true);
if (isset($json['validation_messages'])) {
echo '<p>'.print_r($json['validation_messages'], true).'</p>';
}
?>

Suchprofile

Suchprofil Angaben können an eine Anfrage per extra_data angehängt werden.

{
"email" : "max.muster@domain.ch",
"publisher" : "foo",
"provider" : "bar",
"extra_data" : {
"acquiredThrough" : "Andere",
"addTagsToContact":["special-tag","another-tag"],
"searchProfile": {
"salestype":"buy",
"categories":"flat",
"rooms_from":"3",
"rooms_to":"5.5",
"price_from":"",
"price_to":"1500000",
"living_space_from":"125",
"living_space_to":"",
"living_space_gross_from": "",
"living_space_gross_to": "",
"property_area_from":"",
"property_area_to":"",
"postal_code":"6340",
"locality":"Baar",
"radius":5000,
"note":"Test"
}
}
}

SwissRETS import per HTTP

Diese Schnittstelle ermöglicht ein Daten-Zulieferer (normalerweise software genant) das transferieren von einem Objekt-Portfolio eines Kunden-Kontos (normalerweise provider gennant) mittels dem SwissRETS Standart XMLs auf CASAGATEWAY . Dies wird vollständig über HTTP ermöglich und benötigt somit keine FTP Abhängigkeiten. Das XML kann beliebig an die CASAGATEWAY API jederzeit gesendet werden.

Wie erhalte ich die API und Private Keys?

Casasoft AG kann Ihnen diese keys gennerieren und liefern. Jeder Schlüssel dient zum authentifizieren einer provider/company Schnittstelle die wiederum mit eine software belieferbar sind.

Wie kann ich ein XML senden?

Der request läuft mittels gewöhnlichem http und einem HMAC handshake der durch ein API Key und einem Private Key generiert wird ab. Dieser wird von CASAGATEWAY zur verfügung gestellt. Bitte beachten Sie das Sie den Private Key nie Öffentlich zugänglich machen.

SwissRETS auf GitHub

Dieses XML kann dan beliebig mit Ihrer Infrastruktur beglichen werden, oder Sie nutzen das XML gleich als Speicher-Medium. Das gennerieren dieser XML liegt in den Händen des Senders. Allerdings bieten wir einige PHP Klassen an die das interpretieren von Werten vereinfacht. github.com/casamodules/CasasoftStandards

HMAC Formel

Hier wird abstrahiert wie der request hmac key generiert wird und an einem request string angehängt wird. Achten Sie das der Private Key niemals im schlussendlichem request angegeben wird. Anstelle wird ein hmac key und das öffentliche api key mitgeliefert. Die + Zeichen dienen nur zur visuellen trennung. sortiere die optionen alphabetisch.

checkstring = key1+value1+key2+value2+key3+value3+PRIVATE_KEY+TIMESTAMP
HMAC = hash checkstring with sha256 // take note that this is not the built in php hash_hmac function just a hash with sha256
xml_response = [GET] "http://casagateway.ch/rest/publisher-properties?hmac=HMAC&apikey=API_KEY

Welche Standarte sind mit dieser HTTP-Methodik verfügbar?

Bitte fügen sie die ganze version an den sie versenden, so hat CASAGATEWAY eine bessere chance ihre Datei richtig zu interpretieren, ansonsten wird entweder die aktuellste version interpretiert, oder es wird unter umständen aus der XML schema definition ausgelesen..

PHP Beispiel

Dieses Beispiel zeigt eine einfache PHP Funktion die mittels CURL diese Abfrage generiert und ausführt.

<?php
function sendToGateway($apikey, $privateKey, $options, $apiurl, $fullPathToFile){

//specify the current UnixTimeStamp
$timestamp = time();

//specify your api key
$apikey = $apikey;

//specify your private key
$privatekey = $privateKey;

//sort the options alphabeticaly and combine it into the checkstring
ksort($options);
$checkstring = '';
foreach ($options as $key => $value) {
$checkstring .= $key . $value;
}

//add private key at end of the checkstring
$checkstring .= $privatekey;

//add the timestamp at the end of the checkstring
$checkstring .= $timestamp;

//hash it to specify the hmac
$hmac = hash('sha256', $checkstring, false);

//combine the query (DONT INCLUDE THE PRIVATE KEY!!!)
$query = array(
'hmac' => $hmac,
'apikey' => $apikey,
'timestamp' => $timestamp
) + $options;

//build url
$url = $apiurl . '?' . http_build_query($query);

$response = '';
try {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);

if ($options['method'] == 'direct') {
if (isset($fullPathToFile) && $fullPathToFile) {
$file_to_send = $fullPathToFile;
$response .= 'file_to_send: ' . $file_to_send . "\n";
curl_setopt($ch, CURLOPT_POST, true);

if (version_compare(PHP_VERSION, '5.5.0', '<')) {
curl_setopt($ch, CURLOPT_POSTFIELDS, array('file' => '@' . $file_to_send.';filename=swissrets.xml')); 
} else {
$file = curl_file_create($file_to_send, 'application/xml', 'swissrets.xml');
curl_setopt($ch, CURLOPT_POSTFIELDS, array('file' => $file)); 
}
} else {
return array(
'response' => 'define a file for direct please' . print_r($_FILES, true),
'url' => $url
);
}
}

$curlResponse = curl_exec($ch) . " \n";
$response .= 'curlResponse: ' . htmlentities($curlResponse) ;
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$response .= 'httpcode: ' . $httpCode . " \n";
$response .= print_r(curl_getinfo($ch), true);
curl_close($ch);
} catch (Exception $e) {
$response = $e->getMessage();
}

//present the result
return array(
'response' => $response,
'url' => $url
);
}

$apikey = 'APIKEY_PROVIDED_BY_CASASOFT';
$privatekey = 'PRIVATEKEY_PROVIDED_BY_CASASOFT';
$options = [
'method' => 'direct', // send xml directly over https
'queue' => 1, // puts it into a queu for later import (no import information in response)
'format' => 'swissrets:2.0',
'debug' => 1, // return debug messages
'force' => 0, // Will cause a re-evaluation of all properties. Only use this in emergencies or manually!!!
];
$apiurl = 'https://casagateway.ch/rest/update-all';
$fullPathToFile = '/local/path/to/swissrets.xml';
$result = sendToGateway($apikey, $privatekey, $options, $apiurl, $fullPathToFile);

echo $result['response']; //for debuging

Welche Firmen sind für mich (software) Freigegeben und wie erhalte ich diese Liste?

Dies ist momentan noch nicht verfügbar und Registrierungen und Informationen müssen direkt von Casasoft AG bezogen werden.

Glossar

software: Eine Software die Kunden-Portfolien zuliefern kann.

publisher: Eine Veröffentlichungsinstanz vom CASAGATEWAY. Normalerweise assoziiert mit Portal- oder Webseitenbereiche.

provider: Eine Import- oder Erfassungsschnittstelle. Normalerweise sind das Makler oder Maklergruppen mit einer Immobilien-Software die an die CASAGATEWAY liefern.