Catalogues

Les produits fournis par le flux xml généré par l'API Kelkoo sont soit proposés par un seul marchand, soit par plusieurs marchands, dans ce dernier cas un "Catalogue" est attribué à chaque produit. Un "Catalogue" désigne un flux spécifique à un produit dont un comparatif existe dans la base de données Kelkoo. Si ce catalogue existe pour un produit ceci implique l’existence de la balise "<CatalogId>" dans le résultat utilisant le template "Product Search V3".

Pour récupérer un flux d'un catalogue, il faut utiliser le template "Catalog Listing V3". Dans l'exemple suivant, on réutilisera l'exemple vue dans le chapitre précédent, mais cette fois-ci en testant l'existence de catalogue pour chaque produit. Dans un deuxième temps on va récupérer ce catalogue.

<?php
include('UrlSigner.php');
$url = UrlSigner('http://fr.shoppingapis.kelkoo.com', '/V3/productSearch?query=iphone+5&sort=default_ranking&start=1&results=4&show_products=1&show_subcategories=1&show_refinements=1','Tracking_Id', 'Affiliate_Key');
$xml = simplexml_load_file($url);
echo $xml->Products['totalResultsAvailable'].' r&eacute;sultats chez '.$xml->Products['totalMerchantsAvailable'].' marchands';
echo '<table width="600" border="1">
  <tr>
    <td></td>
    <td>Produit</td>
    <td>Marchand</td>
    <td>Prix(&euro;)</td>
    <td>Lien</td>
  </tr>';
foreach($xml->Products->Product as $product){
 echo '<tr>
    <td><img src="'.$product->Offer->Images->Image->Url.'" /></td>
    <td>'.$product->Offer->Title.'</td>
    <td>'.$product->Offer->Merchant->Name.'</td>
 <td>'.$product->Offer->Price->Price.'</td>';
 if($product->Offer->CatalogId = ""){
     echo '<td><a href="http://clk.tradedoubler.com/click?p=XXXXX&a=XXXXXXX&g=XXXXXXXX&url='.$product->Offer->Url.'" target="_blank">Voir l\'offre</a></td>';
 }
 else {
  echo '<td><a href="catalogue.php?catalog_Id='.$product->Offer->CatalogID.'" target="_parent">Voir les offres</a></td>';
 }
  echo '</tr>';
}
echo '</table>';
?>

Catalogue.php

<?php
include('UrlSigner.php');
$catalog_Id = $_GET['catalog_Id'];
$url = UrlSigner('http://fr.shoppingapis.kelkoo.com', '/V3/catalogListings?catalogId='.$catalog_Id.'','Tracking_Id', 'Affiliate_Key');
$xml = simplexml_load_file($url);
echo $xml->Products['totalResultsAvailable'].' r&eacute;sultats chez '.$xml->Products['totalMerchantsAvailable'].' marchands';
echo '<table width="700" border="1">
  <tr>
    <td></td>
    <td>Produit</td>
    <td>Marchand</td>
    <td>Prix(&euro;)</td>
    <td>Lien</td>
  </tr>';
foreach($xml->Offer as $product){
 echo '<tr>
    <td><img src="'.$product->Images->Image->Url.'" /></td>
    <td>'.$product->Title.'</td>
    <td>'.$product->Merchant->Name.'</td>
 <td>'.$product->Price->Price.'</td>
 <td><a href=http://clk.tradedoubler.com/click?p=XXXXX&a=XXXXXXX&g=XXXXXXXX&url='.$product->Offer->Url.'" target="_blank">Voir l\'offre</a></td> 
   </tr>';
}
echo '</table>';
?>

Lire

L'affiliation Kelkoo

Kelkoo est un site comparateur de prix présent dans une dizaine de pays européens mais aussi la Russie et le Brésil. Il offre aux marchands une plate-forme commerciale pour promouvoir leurs marchandises.

Si vous êtes éditeur d'un site ou d'un blog et que vous voulez le monétiser par le biais du programme d'affiliation Kelkoo, sachez que vous devez passer par la plate-forme Tradedoubler ou PublicIdées qui gèrent exclusivement ce programme (dans ce bolg, on traitera le cas de Tradedoubler).

Une fois votre site accepté chez Tradedoubler pour le programme Kelkoo, vous pouvez commencer à intégrer soit les widgets Kelkoo, soit utiliser l'API Kelkoo pour alimenter votre site par un flux de produits selon les catégories de votre choix, ou complètement construire votre propre comparateur de prix sur la base de cette API.

Dans ce blog, je vais exposer et expliquer le fonctionnement de l'API Kelkoo pour la construction d'un site comparateur de prix qui pourra vous faire gagner de l'argent. Je présenterai aussi des exemples d’intégration en PHP pour essayer de vous faciliter la tâche.

Première étape : l'enregistrement chez Tradedoubler

Allez sur le site de Tradedoubler pour enregistrer votre site, une fois votre site validé, vous pouvez candidater au programme Kelkoo.

Si votre site est accepté, vous allez recevoir un courriel vous confirmant l'activation de votre site pour le programme Kelkoo, mais à ce stade vous n'avez accès qu'aux widgets, bannières et moteurs de recherches. Sur ce même courriel, on vous invite à entrer en contact directement avec un collaborateur de chez Kelkoo pour demander les codes d'accès de l'API, vous devez simplement lui fournir l'id de votre site que Tradedoubler a attribué à votre site.

Le collaborateur Kelkoo vous fournira par la suite trois données pour accéder à l'API :

•  Tracking Id 

•  Affiliate Key

•  Region

A partir de là, on peut commencer l’intégration.

Lire

Premier script

Pour se mettre doucement dans le bain, je vous invite à suivre pas à pas ce petit tutoriel pour concevoir un premier script PHP pour tester nos requêtes.

UrlSigner

La fonction qui va nous permettre d'entrer en contact avec l'API KELKOO est UrlSigner définit comme suit :

function UrlSigner($urlDomain, $urlPath, $partner, $key){

settype($urlDomain, 'String');
settype($urlPath, 'String');
settype($partner, 'String');
settype($key, 'String');

$URL_sig = "hash";
$URL_ts = "timestamp";
$URL_partner = "aid";

$URLreturn = "";
$URLtmp = "";
$s = "";
// get the timestamp
$time = time();

// replace " " by "+"
$urlPath = str_replace(" ", "+", $urlPath);

// format URL
$URLtmp = $urlPath . "&" . $URL_partner . "=" . $partner . "&" . $URL_ts . "=" . $time;

// URL needed to create the tokken
$s = $urlPath . "&" . $URL_partner . "=" . $partner . "&" . $URL_ts . "=" . $time . $key;

$tokken = "";
$tokken = base64_encode(pack('H*', md5($s)));
$tokken = str_replace(array("+", "/", "="), array(".", "_", "-"), $tokken);

$URLreturn = $urlDomain . $URLtmp . "&" . $URL_sig . "=" . $tokken;

return $URLreturn; 

}

On stockera cette fonction dans fichier nommé UrlSigner.php (vous pouvez l'appeler comme vous voulez), et on l’appellera chaque fois qu'on veux lancer une requête.

Pour ce premier test, on va lancer une requête sur le mot clé "iphone 5", on simule la requête dans le Request Builder en utilisant le Template "Product Search V3" pour obtenir l'url suivante :

http://fr.shoppingapis.kelkoo.com/V3/productSearch?query=iphone+5&sort=default_ranking&start=1&results=20&show_products=1&show_subcategories=1&show_refinements=1&aid=Tracking_Id&timestamp=1393443050&hash=zhorGAY8xZk6V8gltepr2w--

A partir de là, on va construire notre url de requête comme suit (on a limiter le nombre de résultats à 4) :

$url = UrlSigner('http://fr.shoppingapis.kelkoo.com', '/V3/productSearch?query=iphone+5&sort=default_ranking&start=1&results=4&show_products=1&show_subcategories=1&show_refinements=1','Tracking_Id', 'Affiliate_Key');

Noter la suppression de "&timestamp=1393443050&hash=zhorGAY8xZk6V8gltepr2w--" car ce sont des données propres à l'API

Traitement du résultat

La variable $url contient maintenant notre fichier xml, pour le parser on utilisera la fonction simplexml_load_file() : 

<?php
include('UrlSigner.php');
$url = UrlSigner('http://fr.shoppingapis.kelkoo.com', '/V3/productSearch?query=iphone+5&sort=default_ranking&start=1&results=4&show_products=1&show_subcategories=1&show_refinements=1','Tracking_Id', 'Affiliate_Key');
$xml = simplexml_load_file($url);
echo $xml->Products['totalResultsAvailable'].' r&eacute;sultats chez '.$xml->Products['totalMerchantsAvailable'].' marchands';
echo '<table width="600" border="1">
  <tr>
    <td></td>
    <td>Produit</td>
    <td>Marchand</td>
    <td>Prix(&euro;)</td>
    <td>Lien</td>
  </tr>';
foreach($xml->Products->Product as $product){
 echo '<tr>
    <td><img src="'.$product->Offer->Images->Image->Url.'" /></td>
    <td>'.$product->Offer->Title.'</td>
    <td>'.$product->Offer->Merchant->Name.'</td>
 <td>'.$product->Offer->Price->Price.'</td>
    <td><a href="http://clk.tradedoubler.com/click?p=XXXXX&a=XXXXXXX&g=XXXXXXXX&url='.$product->Offer->Url.'" target="_blank">Lien</a></td>
  </tr>';
}
echo '</table>';
?>

Le lien marqué en rouge est fournit dans le courriel de validation de votre site par Kelkoo, il permet le tracking Tradedoubler de vos urls, il faut le placer avant le lien du produit.

Résultat :

Lire

Request Builder

Kelkoo a mis à la disposition des développeurs un site explicatif de son API et comment l'utiliser, vous pouvez vous y rendre à l'dresse suivante : http://developer.kelkoo.com/.

En cliquant sur l'onglet REQUEST BUILDER vous allez accéder à un formulaire qui vous permettra de simuler vos requêtes pour récupérer les flux xml souhaités.

Pour simuler une requête, vous devez remplir les paramètres obligatoires suivants :

• Tracking Id : qui permettra le tracking de vos urls.
• Affiliate Key : votre code d'affilié qui fera le lien avec votre compte Tradedoubler.
• Region : votre pays choisi, attribué selon l'emplacement de votre site. Il est important de ne pas se tromper de pays sinon les résultats seront erronés ou nuls.
• Template : indique le type de webservice que vous voulez interroger.

Lister les catégories

En choisissant le Template "Category Search" et en cliquant sur le bouton "Send Request", vous aurez comme résultat deux données :

Request Url : C'est l'url qui permet l'interrogation de l'API selon la requête choisie (dans ce cas lister les catégories disponibles), elle est sous cette forme : 

http://fr.shoppingapis.kelkoo.com/V2/categorySearch?shortcuts=false&features=None&aid=Tracking_Id&timestamp=1393414464&hash=LIoZhZMJSF1LD9p1OhOteA--

Response : Affiche le fichier le fichier xml résultant de la requête, chaque catégorie a les attributs suivants :

• refinements : indique si la catégorie contient un filtre.
• name : le nom de la catégorie.
• id : l'Id de la catégorie.
• catalogs : indique si la catégorie contient des catalogues ou juste des produits non comparés.

Si vous choisissez le format "Tree" vous allez affichez aussi les sous catégories. On notera aussi que Kelkoo attribue l'Id 601 à la catégorie racine.

Pour lister une catégorie spécifique, il suffit de renseigner le champ "Category" par l'Id de la catégorie voulue.

Lister les produits

Pour simuler une requête listant les produits, on choisit le Template "Product Search V3", on obtient un formulaire différent avec les champs suivants :

• Query : requête selon un ou plusieurs mots clés, exemple : "apple iphone".
• Category : l'Id de la catégorie dont on veut lister les produits.
• EAN : chercher un produit par son code EAN.
• Brand Name : nom de la marque qu'on cherche.
• Product Id : l'Id du produit qu'on cherche.
• Refinement : les filtres qu'on veut appliquer à la recherche, on expliquera plus loin comment l'utiliser.
• Merchant : recherche par Id du marchand.
• Offer Id : à chaque produit est attribué un "Offer Id" qui est différent du "Product Id".
• Sort : permet de trier les résultats selon le prix, s'il n'est pas renseigner, le trie se fera selon la pertinence des produits.
• Logical Operator : définit le mode de recherche si le champ "Query" est remplie par des mots clés, AND pour ET et OR pour OU, par défaut c'est AND.
• Start : indique par quel résultat commencer dans le classement, ceci permettra la gestion de la pagination des résultats qu'on verra plus loin.
• Results : permet de choisir le nombre de résultats qu'on veut afficher (limiter à 100 pour une requête).
• Price Min et Price Max : limitent une fourchette de prix.
•  Categories : affiche les catégories liées à la recherche.
• Refinements : affiche les filtres disponibles pour affiner la requête si l'on souhaite.
• Products : liste les produits.

Prenons un exemple : on lance la recherche de "iphone 5" sur le champs "Query", on a donc les données suivantes (notez que les résultats changent bien sûre selon la mise à jour de la base de données Kelkoo) :

Request Url : 

http://fr.shoppingapis.kelkoo.com/V3/productSearch?query=apple+iphone&sort=default_ranking&start=1&results=20&show_products=1&show_subcategories=1&show_refinements=1&aid=Tracking_Id&timestamp=1393417346&hash=a7uGNFKVNnMjNwft2B6zLw--

Response :

<ProductSearch>

+<Categories total_subcategories="30"></Categories>

+<Refinements></Refinements>

+<Products totalResultsAvailable="1622" firstResultPosition="1" totalResultsReturned="20" currency="EUR" lowestPrice="5.90" highestPrice="899.00" totalMerchantsAvailable="14" searchOperator="and"></Products>

+<Warnings></Warnings>

+<SearchInfo></SearchInfo>

</ProductSearch>

Traitons par nœud :

Categories : informe sur les sous catégories que contiennent le produit, si l'on déroule, on obtient les nœuds des sous catégories. Prenons le premier :

<SubCategory>

<Title>Accessoires pour téléphone portable</Title>

<Value>125801</Value>

<NumberOfProducts>937</NumberOfProducts>

</SubCategory>  

Title : nom de la sous catégorie.

Value : Id de la sous catégorie.

NumberOfProducts : nombre de produits existant pour cette sous catégorie.

Refinements : affiche les filtres disponibles pour ce produits, dans notre cas on obtient 5 filtres :

<Refinements>

+<Refinement name="NarrowsBy" label="Catégorie" totalvalues="30" type="ValueList"></Refinement>

+<Refinement name="Price" label="Prix" totalvalues="5" type="ValueList"></Refinement>

+<Refinement name="merchant" label="Marchand" totalvalues="14" type="ValueList"></Refinement>

+<Refinement name="Classification" label="Type" totalvalues="2" type="ValueList"></Refinement>

+<Refinement name="RebateRange" label="% de réduction" totalvalues="4" type="ValueList"></Refinement>

</Refinements>

Chaque noeud a les attributs suivants :

name : Nom du filtre, utilisé pour filtrer.

label : Nom du filtre, pour l'affichage.

totalvalues : nombre de résultats existants.

type : type du filtre, généralement "ValueList".

Si on déroule maintenant chaque nœud, on aura le détail des valeurs du filtre :

<RefineValue>

<Title>Accessoires pour téléphone portable</Title>

<Value>125801</Value>

<NumberOfProducts>937</NumberOfProducts>

</RefineValue>

Title : nom de la valeur filtre.

Value : Id de la valeur du filtre.

NumberOfProducts : nombre de produits existant pour cette valeur.

Products : liste les produits résultants de la requête :

<Products totalResultsAvailable="1622" firstResultPosition="1" totalResultsReturned="20" currency="EUR" lowestPrice="5.90" highestPrice="899.00" totalMerchantsAvailable="14" searchOperator="and">
+<Product></Product>
+<Product></Product>
-----------------------
+<Product></Product>
+<Product></Product>
<Products>

totalResultsAvailable : total des résultats disponibles.
firstResultPosition : position du premier résultat.
totalResultsReturned : total des résultats retournés.
currency : devise appliquée aux résultats.
lowestPrice : prix du produit le moins cher.
highestPrice : prix du produit le plus cher.
totalMerchantsAvailable : total des marchands proposant ce produit.
searchOperator : opérateur de recherche (par défaut AND).

Le nœud "Product" contient toutes les balises xml regroupant les informations du produit, en voici un exemple :

<Product>
<Offer id="8a5518b4a202369c5a6c04950cf0a4c0" type="MANUFACTURER_PRODUCTS">
<Title>Iphone 5 Blanc 64Go Occasion Usé Orange</Title>
<Images>
<Image>
<Url>http://r.kelkoo.com/r/fr/3012701/100020213/90/90/http%3A%2F%2Fpmcdn.priceminister.com%2Fphoto%2F977010780_L.jpg/ldgCEyvNMjz9JWmHShmQe8rz.icAcC66M5nurfBYOBc-</Url>
<Height>90</Height>
<Width>90</Width>
</Image>
<ZoomImage>
<Url>http://r.kelkoo.com/r/fr/3012701/100020213/auto/auto/http%3A%2F%2Fpmcdn.priceminister.com%2Fphoto%2F977010780_L.jpg/ldgCEyvNMjz9JWmHShmQe8rz.icAcC66M5nurfBYOBc-</Url>
</ZoomImage>
</Images>
<Video/>
<Url>http://ecs-fr.kelkoo.fr/ctl/go/sitesearchGo?.ts=1393443052309&.sig=TjvM_5Nr_W0Ppb6TJbEkPrLqbIk-&offerId=8a5518b4a202369c5a6c04950cf0a4c0&searchId=107611418913436_1393443052191_1746103&affiliationId=Tracking_Id&country=fr&wait=true&ecs=ok&contextLevel=1&merchantid=3012701&comId=3012701&catId=100020213&useSearch6=true</Url>
<MobileFriendly>false</MobileFriendly>
<CompareUrl>http://www.kelkoo.fr/p-telephone-portable-sans-abonnement-100020213/apple-iphone-5-64gb-19829092?partnerId=Tracking_Id</CompareUrl>
<Merchant id="3012701">
<Name>PriceMinister Occasions</Name>
<Logo>
<Url>http://r6.kelkoo.com/data/merchantlogos/3012701/PMOccasion.jpg</Url>
<Width>80</Width>
<Height>24</Height>
</Logo>
</Merchant>
<CatalogID>100020213-19829092</CatalogID>
<Catalog productId="19829092" categoryId="100020213">
<Name>Apple iPhone 5 64GB</Name>
</Catalog>
<Category id="100020213">
<Name>Téléphone portable sans abonnement</Name>
</Category>
<Price currency="EUR">
<Price>420</Price>
<DeliveryCost>9.2</DeliveryCost>
<DeliveryCostDetails>
<DeliveryCost>9.2</DeliveryCost>
</DeliveryCostDetails>
<TotalPrice>429.2</TotalPrice>
</Price>
<ProductClass>1</ProductClass>
<Availability>1</Availability>
<DeliveryTime>sous 2 à 5 jours</DeliveryTime>
<Promo/>
<OffensiveContent>false</OffensiveContent>
<FinancingOption/>
<MerchantCategory>Electronique Téléphones mobiles Non précisé</MerchantCategory>
<Brand>Apple</Brand>
<BrandId>211</BrandId>
<GreenProduct>false</GreenProduct>
</Offer>
</Product>

Lire