SDK

Il est nécessaire d’obtenir au préalable l’accord écrit de Publimmo pour l’utilisation de l’un ou l’autre de ces services.

• Démarrage
• Client de recherche
• Object Collection
• Object Entity
• Mailer

Démarrage

Installer le SDK

---

Avec Composer

Ajoutez ce package à votre fichier composer.json

"repositories": [
  ...
  {
    "type": "vcs",
    "url": "git@github.com:alanpilloud/publimmopro-sdk-php.git"
  }
  ...
],

Puis ce requirement

"require": {
  ...
  "publimmopro/phpsdk": "*",
  ...
},

Puis exécutez composer update.

Sans Composer

Téléchargez le SDK sur github.

Placez le contenu de /src/PublimmoPro/ dans un répertoire accessible à votre code, puis incluez les différents fichiers.

Initialisation

use \PublimmoPro\Client;

// Indiquez l'ID d'agence Publimmo, et sa clé
$PublimmoClient = new Client(99999, 'key');

Client de recherche

use \PublimmoPro\Client;

$Client = new Client('2121313', 'unecle');

$Client->setType(Client::PARKING)
       ->setDisponiblite(Client::AVAILABILITY_IS_AVAILABLE)
       ->query();

// ou obtenir un objet directement
$Client->query(43242);

Initialisation

Utilisez la classe PublimmoPro\Client pour pouvoir faire des requêtes à l'API.

use \PublimmoPro\Client;

// Indiquez l'ID d'agence Publimmo, et sa clé
$PublimmoClient = new Client(99999, 'key');

Méthodes

query(int $id = null)

Envoie la requête au webservice et récupère les résultats.

Paramètres

Param	Type	Description
$id	int	Optionnel, identifiant de l'objet à chercher

Retour

Pour les requêtes d'objet, une instance de PublimmoPro\ObjectEntity est retournée ou false si la requête n'a pas retourné de résultat.

Pour les requêtes de recherche, Une instance de PublimmoPro\ObjectCollection est retournée ou false si la requête n'a pas retourné de résultat.

Exemple

$Client->query(43284); // retourne un objet ObjectEntity

$Client->query(); // retourne un objet ObjectCollection

---

getQueryURL()

Retourne l'URL de la requête générée.

Paramètres

Pas de paramètres

Exemple

echo $Client->getQueryURL();

---

setCity(string $city)

Fonctionnement à vérifier

Permet de définir la localité dans laquelle effectuer la recherche.

Paramètres

Param	Type	Description
$city	string	Nom de la ville

Exemple

$Client->setCity('Lausanne');

---

setCityId(int $cityId)

Définit dans quelle ville rechercher.

Paramètres

Param	Type	Description
$cityId	int	Identifiant de la ville, se référer à la liste des communes ou à la recherche de communes

Exemple

$Client->setCityId(481);

---

setCountry(string $countryCode)

Définit le pays dans lequel les objets doivent être recherchés.

Paramètres

Param	Type	Description
$countryCode	string	Pays au format ISO 3166-alpha2. Exemple: 'fr', 'ch' ou 'de'

Exemple

$Client->setCountry('fr');

---

setCourtierId(int $id)

Définit l'identifiant du courtier afin de ne retourner que ses objets.

Paramètres

Param	Type	Description
$id	int	Identifiant du courtier

Exemple

$Client->setCourtierId(58495);

---

setDisponiblite(int $disponibility)

Définit la disponiblitité des objets à retourner.

Paramètres

Param	Type	Description
$disponiblitity	int	Identifiant de disponibilité

Constantes

• Client::AVAILABILITY_IS_AVAILABLE
• Client::AVAILABILITY_IS_RESERVED
• Client::AVAILABILITY_IS_SOLD
• Client::AVAILABILITY_IS_OPTION

Exemple

$Client->setDisponiblite(Client::AVAILABILITY_IS_AVAILABLE);

---

setDistance(int $distance)

Définit le rayon de recherche en km. Fonctionne de paire avec setCityId.

Paramètres

Param	Type	Description
$distance	int	Rayon de recherche

Exemple

$Client->setCityId(481)->setDistance(20);

---

setForeigners()

Définit que la recherche doit retourner les objets disponibles à la vente aux étrangers.

Paramètres

Pas de paramètres

Exemple

$Client->setForeigners();

---

setReference($ref)

Définit l'identifiant Publimmo ou la référence agence de l'objet à chercher.

Paramètres

Param	Type	Description
$ref	mixed	Identifiant Publimmo ou référence d'agence

Exemple

$Client->setReference(54589);
$Client->setReference('Villa 34');

---

setIds(int ...$ids)

Définit une liste d'identifiants d'objets à récupérer.

Paramètres

Param	Type	Description
$ids	int	Liste d'identifiants

Exemple

$Client->setIds(45894, 23489, 45495);

---

setLanguage(string $ul)

Définit la langue utilisateur.

Paramètres

Param	Type	Description
$ul	string	Langue au format ISO 3166-alpha2. Valeurs possibles : 'de', 'fr' ou 'en'

Exemple

$Client->setLanguage('de');

---

setLocationType(int $type)

Définit la durée du contrat de location.

Paramètres

Param	Type	Description
$type	int	Type de durée

Constantes

• Client::LOCATION_TYPE_WEEK : Location à la semaine
• Client::LOCATION_TYPE_SEASON : Location à la saison
• Client::LOCATION_TYPE_YEAR : Location à l'année

Exemple

$Client->setLocationType(Client::LOCATION_TYPE_WEEK);

---

setNpaOrder(int $npaOrder)

Définit l'ordre des résultats en commencant par le Numréro Postal d'Acheminement spécifié.

Paramètres

Param	Type	Description
$npaOrder	int	NPA de la commune

Exemple

$Client->setNpaOrder(1800);

---

setRange(string $type, int $min, int $max)

Définit une fourchette de prix, surface ou chambres.

Paramètres

Param	Type	Description
$type	string	Type de valeur, "price", "surface" ou "room"
$min	int	Prix minimum désiré
$max	int	Prix maximum désiré

Exemple

$Client->setRange("price", 2000, 2900);

// définir plusieurs fourchettes
$Client->setRange("price", 2000, 2900)
       ->setRange("room", 3, 6);

---

setPromotionType(int $type)

Définit le type de promotion à récupérer.

Paramètres

Param	Type	Description
$type	int	Type de promotion

Constantes

• Client::PROMOTION_TYPE_PROMOTION : retourne les objets dont le type est "promotion"
• Client::PROMOTION_TYPE_NEW : retourne les objets de promotion et les appartments et maisons neuves
• Client::PROMOTION_TYPE_NOT_PROMOTION : retourne les objets dont le type n'est pas "promotion"

Exemple

$Client->setPromotionType(Client::PROMOTION_TYPE_NEW);

---

setRegion(int $region)

Définit de quelle région doivent provenir les objets.

Paramètres

Param	Type	Description
$region	int	Identifiant de la région, se référer à la liste des régions

Exemple

$Client->setRegion(8);

---

setResidenceSecondaire(bool $state)

Définit si on souhaite obtenir des objets disponibles à la vente en résidence secondaire.

Paramètres

Param	Type	Description
$state	bool	true inclut les objets disponibles à la vente en résidence secondaire false les exclut

Exemple

$Client->setResidenceSecondaire(true);

---

setSearchString(string $searchString)

Permet de définir un mot-clé de recherche.

Paramètres

Param	Type	Description
$searchString	string	Mot-clé à rechercher

Exemple

$Client->setSearchString('piscine');

---

setSelfOnly()

Fonction de réseau

Permet de ne récupérer que les résultats de l'agence, sans ceux du réseau.

Paramètres

Pas de paramètres

Exemple

$Client->selfOnly();

---

setOrder(int $sortBy, string $sortDirection = null)

Permet de définir le critère de tri et l'ordre.

Paramètres

Param	Type	Description
$sortBy	int	Critère de tri
$sortDirection	string	Optionnel, sens du tri, accepte 'asc' ou 'desc'

Constantes

• Client::SORT_BY_PRICE
• Client::SORT_BY_ROOMS
• Client::SORT_BY_SURFACE
• Client::SORT_BY_CREATED_AT

Exemple

$Client->setSort(Client::SORT_BY_PRICE);

$Client->setSort(Client::SORT_BY_PRICE, 'asc');

---

setTransaction(int $transaction)

Définit le type de transaction, acheter ou louer.

Paramètres

Param	Type	Description
$transaction	int	Type de transaction

Constantes de transaction

• Client::BUY
• Client::RENT

Exemple

$Client->setTransaction(Client::BUY);

---

setType(int ...$types)

Permet de faire une recherche d'objets selon les critères définis.

Paramètres

Param	Type	Description
$types	int	Liste de types, 1 à 6 types possibles

Constantes de types

• Client::APPARTMENT
• Client::BUILDING
• Client::COMMERCIAL
• Client::HOUSE
• Client::LAND
• Client::PARKING

Exemple

$Client->setType(Client::APPARTMENT,Client::HOUSE);​

Object Collection

PublimmoPro\ObjectCollection est une classe représentant une liste d'objets obtenue lors d'une recherche.

Initialisation

Utilisez la classe PublimmoPro\Collection pour pouvoir faire des manipulations sur les résultats de recherche.

Exemple d'instanciation de l'objet

Il est peu probable que ceci ait besoin d'être fait à la main
En effet, la méthode query() de la classe PublimmoPro\Client retourne déjà un objet ObjectCollection.

use \PublimmoPro\ObjectCollection;

$Collection = new ObjectCollection($results, 80);

$Collection->get();

Il est plus probable que cela soit utilisé à la suite d'une requête Client.

use \PublimmoPro\Client;

$Client = new Client('2121313', 'unecle');

$Collection = $Client->setType(Client::PARKING)
       ->setDisponiblite(Client::AVAILABILITY_IS_AVAILABLE)
       ->query();

$Collection->get();

Méthodes

get()

Retourne la liste d'objets.

Paramètres

Pas de paramètres

Exemple

$Collection->get();

---

getTotal()

Retourne le nombre total d'objets trouvés.

Paramètres

Pas de paramètres

Exemple

$Collection->getTotal(); // 432

---

filter(string $filter_type, mixed $objects_to_filter)

Filtre les résultats en incluant ou excluant les identifiants d'objets indiqués.

Paramètres

Param	Type	Description
$filter_type	string	Type de filtre, accepte "include" ou "exclude"
$objects_to_filter	mixed	identifiant de l'objet à filtrer ou tableau d'objets à filtrer

Exemple

$Collection->filter('include', 85763)->get();
$Collection->filter('exclude', [85763, 24987])->get();

---

sort(mixed $instructions)

Trie les résultats selon les instructions données.

Paramètres

Param	Type	Description
$instructions	mixed	Chaîne d'instruction ou tableau de châines d'instructions

Composition de l'instruction

Une instruction est une châine composée des trois éléments suivants :

• Le champ : nom du champ tel que décrit dans l'API
• Sens de tri : 'asc' ou 'desc'
• Type de champ : 'integer', 'float' ou 'string'

Sa syntaxe est "champ:sens:type".

Exemple

$Collection->sort('prix:asc:integer')->get();
$Collection->sort(['prix:asc:integer', 'pieces:desc:float'])->get();

Object Entity

Représente un objet.

Il est peu probable que vous ayiez à instancier vous-même cette classe.

Lorsque que l'on fait une requête d'objet, elle retourne directement un objet de type PublimmoPro\ObjectEntity :

$ObjectEntity = $Client->query(43242);

Méthodes

__construct(object $result)

Créé une nouvelle instance de PublimmoPro\ObjectEntity.

Paramètres

Param	Type	Description
$result	object	Résultat provenant d'une requête d'objet PublimmoPro\Client

Exemple

$Mailer = new ObjectEntiy($responseFromAPI);

---

raw()

Retourne les données brutes et exploitables directement.

Consultez la liste des propriétés disponibles.

Paramètres

Pas de paramètre.

Exemple

$objectData = $ObjectEntity->raw();

echo '<h1>A vendre à '.$objectData->localite.'</h1>';

---

isFromNetwork()

Vérifie s'il s'agit d'un objet provenant du réseau d'agences.

Paramètres

Pas de paramètre.

Exemple

$ObjectEntity->isFromNetwork()
    ? echo 'vrai'
    : echo 'faux';

---

isPromotion()

Vérifie que l'objet est une promotion.

Paramètres

Pas de paramètre.

Exemple

$ObjectEntity->isPromotion()
    ? echo 'vrai'
    : echo 'faux';

---

isType(int $objectType)

Vérifie le type d'objet.

Paramètres

Param	Type	Description
$objectType	int	Type d'objet, utilisez les constantes de types de la classe PublimmoPro\Client.

Constantes de types de la classe PublimmoPro\Client

• Client::APPARTMENT
• Client::BUILDING
• Client::COMMERCIAL
• Client::HOUSE
• Client::LAND
• Client::PARKING

Exemple

$ObjectEntity->isType(Client::HOUSE)
    ? echo 'vrai'
    : echo 'faux';

Mailer

La classe Mailer permet de créer des demandes de dossier à envoyer par email. Elle ne gère pas directement l'envoi de mail, ceci vous laissant le libre choix de la méthode à employer.

use \PublimmoPro\Mailer;

$userData = [
    // mandatory fields
    'title' => 'Monsieur',
    'lastname' => 'Dupont',
    'firstname' => 'Jean',
    'email' => 'jean@dupont.ch',
    'phone' => '021 555 55 55',
    'language' => 'fr',

    // secondary fields
    'address' => 'Rue exemple 3',
    'zipcode' => '5555',
    'city' => 'Ville exemple',
    'country' => 'Suisse',
    'message' => 'Bonjour, je souhaite obtenir un dossier.',
];

$Mailer = new Mailer($currentObjectEntity, $userData, 'https://mywebsite.com');

// Example for WordPress
wp_mail(
    $Mailer->toMail, // to email address
    Mailer::SUBJECT, // subject
    $Mailer->getEmailBody() // body
);

Méthodes

__construct(ObjectEntity $objectEntity, array $userdata, string $siteUrl)

Créé une nouvelle instance de PublimmoPro\Mailer.

Paramètres

Param	Type	Description
$objectEntity	PublimmoPro\ObjectEntity	Entité d'objet, représente l'objet pour lequel on veut faire la demande
$userData	array	Tableau de clé/valeur contenant obligatoirement les clés suivantes title, lastname, firstname, email, phone, language et accessoirement address, zipcode, city, message
$siteUrl	string	Url du site courrant

Exemple

$Mailer = new Mailer($currentObjectEntity, $userData, 'https://mywebsite.com');

---

getEmailBody()

Retourne le corps de l'email pour une demande de dossier.

Paramètres

Pas de paramètres

Exemple

echo $Mailer->getEmailBody();