Avec l'API CASAGATEWAY, vous pouvez exporter des données d'objets vers un site web externe et envoyer des demandes de renseignements. Avec un compte CASAONE Pro, vous pouvez même recevoir et répondre directement aux demandes dans CASAONE.

Exportation SwissRETS via HTTP

Cette interface permet de transférer des données d'objets depuis un portail de publication (publisher) vers CASAGATEWAY en utilisant la norme SwissRETS. Cela se fait entièrement via HTTP, ce qui évite toute dépendance FTP. Le fichier XML peut être récupéré à tout moment via l'API CASAGATEWAY. CASAGATEWAY génère et fournit directement un corps XML dans la réponse. CASAGATEWAY exécutera également des pokes/hooks dès qu'il y a des modifications ou mutations des données. Ces actions sont déclenchées par une requête GET sur une URI préconfigurée.

Comment obtenir les données d'accès nécessaires ?

En fonction de la fonctionnalité que vous souhaitez utiliser, vous aurez besoin de différentes données d'accès. Pour exporter des objets vers un site web externe, vous aurez seulement besoin de la « clé API » et de la « clé privée ». Si vous souhaitez envoyer des demandes de renseignements supplémentaires via l'API, vous aurez également besoin du « fournisseur CASAMAIL », du « publisher CASAMAIL » et d'un « SimpleAuthUser » (nom d'utilisateur et mot de passe).

Vous pouvez obtenir vos données d'accès auprès de notre support.

Demander des données d'accès

Comment générer et récupérer un XML (fetch) ?

La demande s'effectue via HTTP standard avec une poignée de main HMAC, générée à l'aide d'une clé API et d'une clé privée fournies par CASAGATEWAY. Veuillez noter que vous ne devez jamais rendre publique la clé privée. Ce XML peut être facilement intégré à votre infrastructure, ou vous pouvez l'utiliser directement comme support de stockage. Le traitement et la persistance de ce XML sont de la responsabilité du consommateur. Cependant, nous proposons quelques classes PHP qui simplifient l'interprétation des valeurs.

Standards Casasoft sur GitHub

Authentification via HMAC

Cette section explique comment la clé HMAC est générée et ajoutée à une chaîne de requête. Assurez-vous que la clé privée n'est jamais incluse dans la requête finale. À la place, une clé HMAC et la clé API publique doivent être envoyées. Les signes "+" servent uniquement à la séparation visuelle des éléments. Triez les options par ordre alphabétique.

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"

Quels standards sont disponibles avec cette méthode HTTP ?

CASAGATEWAY tentera de respecter le numéro de version lors de l'exportation, mais ne pourra garantir que le premier chiffre (version principale). La version effective (par exemple 2..) sera déclarée dans la réponse correspondante.

Exemple PHP

Cet exemple montre une fonction PHP simple qui génère et exécute cette requête via CURL.

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

Quelles options puis-je utiliser ?

company:company_slug pour filtrer par entreprise. Cela est utile pour les portails/publicateurs plus grands qui souhaitent diviser leurs imports.

Quelles entreprises (fournisseurs) souhaitent envoyer des objets pour moi (publicateur) et comment obtenir leur company_slug ?

Avec la même clé API et la même procédure, vous pouvez obtenir une liste JSON de toutes les entreprises prêtes à publier des objets sur cette plateforme via le lien suivant :
https://casagateway.ch/rest/publisher-companies

Comment savoir si quelque chose a été mis à jour ?

CASAGATEWAY exécutera un poke/hook sur une URI prédéfinie en cas de modification (via une requête POST). Celle-ci pourrait par exemple ressembler à ceci :

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

Si vous êtes un portail, il est également possible d'ajouter le slug de l'entreprise à l'URI, ce qui pourrait ressembler à ceci :

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

Ici, un script pourrait être utilisé pour lancer un import dès que possible. Cependant, les imports doivent être lancés de manière asynchrone ou être enregistrés pour un futur traitement. Pendant ce processus, aucun import ne doit être effectué, car CASAGATEWAY annulera la requête après un court délai.

Exemple Postman

{
    "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

Comment cela fonctionne-t-il ?

Au lieu d'envoyer un e-mail, une requête POST doit être envoyée à casamail.ch. Cette requête sera ensuite enregistrée dans la base de données CASAMAIL et sera ensuite distribuée plusieurs fois à partir de là.

IMPORTANT : Veuillez utiliser des méthodes modernes pour vous assurer qu'aucune demande de spam n'est transmise à notre interface via les formulaires. Si une attaque de spam devait néanmoins se produire, nous serions contraints de bloquer l'interface.

Quels sont les valeurs possibles ?

Voici un aperçu des valeurs possibles que peut contenir un message (msg) :

x: aleur indéterminée.

Fett: Champ obligatoire

Exemple PHP POST avec 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>';
}
?>

Profil de recherche

Les informations du profil de recherche peuvent être ajoutées à une demande via extra_data.

{
"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"
}
}
}

Importation SwissRETS via HTTP

Cette interface permet à un fournisseur de données (généralement un logiciel) de transférer un portefeuille d'objets depuis un compte client (généralement appelé fournisseur) vers CASAGATEWAY en utilisant les fichiers XML du standard SwissRETS. Cela se fait entièrement via HTTP, ce qui élimine toute dépendance à FTP. Le fichier XML peut être envoyé à l'API CASAGATEWAY à tout moment.

Comment obtenir les clés API et la clé privée ?

Casasoft AG peut générer et fournir ces clés. Chaque clé est utilisée pour authentifier une interface fournisseur/entreprise, qui peut ensuite être utilisée pour fournir des données à un logiciel.

Comment envoyer un fichier XML ?

La requête se fait via HTTP standard et un handshake HMAC, généré à l'aide d'une clé API et d'une clé privée. Ces clés sont fournies par CASAGATEWAY. Veuillez noter que vous ne devez jamais rendre la clé privée publique.

SwissRETS sur GitHub

Le fichier XML peut être intégré à votre infrastructure de manière flexible, ou vous pouvez l'utiliser directement comme support de stockage. La génération de ce fichier XML est de la responsabilité de l'expéditeur. Toutefois, nous proposons quelques classes PHP qui simplifient l'interprétation des valeurs. github.com/casamodules/CasasoftStandards

Formule HMAC

Voici comment la clé HMAC est générée et ajoutée à une chaîne de requête. Assurez-vous que la clé privée ne soit jamais incluse dans la requête finale. À la place, une clé HMAC et la clé API publique doivent être envoyées. Les signes "+" sont utilisés uniquement pour la séparation visuelle des éléments. Triez les options par ordre alphabétique.

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

Quels standards sont disponibles avec cette méthode HTTP ?

Veuillez toujours ajouter la version complète que vous envoyez, cela permettra à CASAGATEWAY de mieux interpréter votre fichier. Sinon, la version la plus récente sera interprétée ou, dans certains cas, l'interpretation sera effectuée à partir de la définition du schéma XML.

Exemple PHP

Cet exemple montre une fonction PHP simple qui génère et exécute cette requête via CURL.

<?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

Quelles entreprises sont autorisées pour moi (logiciel) et comment obtenir cette liste ?

Cela n'est pas encore disponible et les inscriptions ainsi que les informations doivent être obtenues directement auprès de Casasoft AG.

Glossaire

logiciel : Un logiciel capable de fournir des portefeuilles clients.

éditeur : Une instance de publication de CASAGATEWAY. Normalement associée à un portail ou à des sections de sites web.

fournisseur : Une interface d'importation ou de collecte. Il s'agit généralement de courtiers ou de groupes de courtiers utilisant un logiciel immobilier qui fournit des données à CASAGATEWAY.