Accès Annonceur
Introduction
Qu’est ce que l’API annonceur et pourquoi l’utiliser ?
API = application programming interface ou « interface de programmation d'application ») est une interface logicielle qui permet de « connecter » un logiciel ou un service à un autre logiciel ou service afin d'échanger des données et des fonctionnalités.
Le système d’interrogation à distance (API) de la base Kwanko vous permet de :
Récupérer vos formulaires et vos ventes avec la page reqann.php
Récupérer vos statistiques avec la page lisann.php
Pré-réquis
Pour accéder au système d’interrogation à distance de la base Kwanko, l'utilisateur doit être enregistré auprès de Kwanko et avoir confirmé son compte utilisateur avec identifiant et mot de passe.
Une fois cette étape réalisée, contactez votre gestionnaire de compte ou le service SKALE with Kwanko pour qu’il le génère pour vous les login et mot de passe pour l'API. Le mot de passe pour l’utilisation des Web Services est différent de celui utilisé pour accéder à la plateforme Kwanko / SKALE.
Voici les paramètres vous permettant de vous connecter au système de l’API :
En cas de perte de vos identifiants aux Web Services, nous vous invitons de contacter votre gestionnaire de compte ou le service SKALE.
Sécurité
Il est obligatoire d’accéder à la page de requête en passant par le protocole HTTPS qui se charge alors de chiffrer toutes les informations.
Identification*
Liste des paramètres permettant l’identification de l'utilisateur par le système :
*Identifiants de Web Services fournis avant Juillet 2013
Précisions sur le paramètre « verif » :
Ce paramètre dépend du niveau de sécurité paramétré sur le compte de l'utilisateur. Selon le niveau de sécurité la valeur de ce paramètre peut être en clair ou sous forme d’une chaîne de 32 caractères de la fonction md5 appelée sur la concaténation des autres paramètres.
Voir le détail des niveaux de sécurité ci-dessous :
Niveau 1
L'utilisateur ajoute son mot de passe en clair dans le paramètre « mdp », le paramètre « verif » ne doit pas être utilisé, la requête doit passer via le protocole HTTP. L’adresse de la page commence alors par http://stat.netaffiliation.com/
Niveau 2
L'utilisateur ajoute un hash md5 de son identifiant, son mot de passe, son adresse IP et la date du jour (AAAA-MM-JJ) dans le paramètre « verif », le paramètre « mdp » ne doit pas être utilisé, la requête doit passer via le protocole HTTP. L’adresse de la page commence alors par http://stat.netaffiliation.com/ Ex : md5($username.$password.$ipaddress.$date);
Niveau 3
L'utilisateur ajoute un hash md5 de son identifiant, son mot de passe, son adresse IP, la date du jour (AAAA-MM-JJ) et de la requête dans le paramètre « verif », le paramètre « mdp » ne doit pas être utilisé, la requête doit passer via le protocole HTTP. L’adresse de la page commence alors par http://stat.netaffiliation.com/
Niveau 4
L'utilisateur ajoute son mot de passe en clair à chaque requête dans le paramètre « mdp », le paramètre « verif » ne doit pas être utilisé, la requête doit passer via le protocole HTTPS qui se charge alors de chiffrer toutes les informations. L’adresse de la page commence alors par https://stat.netaffiliation.com/
Résultat de la requête
Le résultat de la requête correspond à du texte brut et contient, sur la première ligne, un code de retour de la requête, puis un résultat ligne par ligne dont les champs demandés sont séparés par un point-virgule « ; ».
Si un point-virgule « ; » apparaît dans un des champs d'une ligne de résultat le champ est entouré par des double-quotes « ” ». En d'autres termes il s'agit d'un résultat au format CSV après le code de retour.
Les codes de retour possibles sur la première ligne sont :
En cas de succès de la requête : la chaîne « OK » suivie d'un espace puis du nombre de lignes récupérées. Une requête peut-être réalisée avec succès et ne retournée aucune ligne, simplement OK 0
En cas d'échec de la requête : la chaîne « KO » suivie d'un espace puis d'un numéro d'erreur suivi d'un espace puis d'une explication « humainement compréhensible »
Les numéros d'erreurs possibles sont :
Paramètres fournis incomplets : il manque un ou plusieurs paramètres obligatoires.
Paramètres d'identification fournis incorrects : problème de login.
Paramètres d'identification fournis incorrects : problème de mot de passe.
Paramètre de requête incompris (mauvaise syntaxe par exemple). Dans ce cas, le message d'erreur qui suit contient le nom du paramètre posant problème.
Système indisponible temporairement.
Niveau de sécurité incorrect.
Récupération des conversions
Accès
L’accès se fait par le biais d’une page disponible sur le serveur web : https://stat.netaffiliation.com/reqann.php
L’appel à la page de requête peut se faire par méthode GET ou POST.
Cette page comprend un certain nombre de paramètres permettant l'identification et de préciser les informations souhaitées, les filtres et leurs formatages.
Paramètres de requête
Attention : Un paramètre ajouté mais vide (sans valeur) dans la requête, sera considéré comme non passé, donc avec sa valeur par défaut.
Vous pouvez ajouter des filtres dans la requête avec les paramètres suivants :
Champs disponibles
Liste des noms de champs disponibles pour le paramètre “champs”
Vous pouvez ajouter en plus à votre requête:
header qui permet de visualiser les libellés des colonnes
csv qui permet de télécharger la requête sous csv
Exemple de requête avec header et csv:
https://stat.netaffiliation.com/reqann.php?authl=xxxx&authv=xxxxxx&debut=2022-01-01&fin=2022-01-26&champs=idcampagne,nomcampagne,date,idsite,etat,cout,typologie&header&csv
Le fuseau horaire est UTC+0.
Si le paramètre « champs » n'est pas ajouté dans la requête (ou est vide) il vaut par défaut : idcampagne,idsite,date,validation,etat,montant,cout,monnaie,argann
Exemples de requêtes conversions
Dans les exemples qui suivent, et sauf contre indication, on suppose que l'utilisateur cherche à exécuter une requête avec les paramètres d'identification suivants et en identification V3 :
login : test@test.fr
mot de passe : AzErTy
Objectif : récupérer les ventes/formulaires validés et en attentes, réalisés entre deux dates sur tous les programmes et sites Url : https://stat.netaffiliation.com/reqann.php?authl=test@test.fr&authv=AzErTy&etat=va&debut=2013-07-15&fin=2013-07-16 Résultat : OK 4 133;5556;2013-07-15 13:15:26;2013-06-13 13:15:26;v;12.47;EUR;toto@toto.com 133;7744;2013-07-15 17:40:51;2013-05-13 17:40:51;v;8.12;EUR;test@email.com 433;85223;2013-07-15 22:01:00;2013-05-13 22:01:00;v;5.00;EUR;valide@ok.com 2289;55553;2013-07-16 23:12:00;2013-05-16 23:12:00;a;5.00;EUR;valide2@oko.com |
Objectif : récupérer les ventes/formulaires validés du 15/07/2013, avec des champs spécifiques, sur tous les programmes et sites: Url : https://stat.netaffiliation.com/reqann.php?authl=test@test.fr&authv=AzErTy&etat=v&champs=idcampagne,cout,argann&debut=2013-07-15 Résultat : OK 3 133;12.47;toto@toto.com 133;8.12;test@email.com 433;5.00;valide@ok.com |
Objectif : récupérer les ventes/formulaires du 15/07/2013, avec des champs spécifiques, sur les programmes 433 et 2289 et tous les sites : Url : https://stat.netaffiliation.com/reqann.php?authl=test@test.fr&authv=AzErTy&champs=idcampagne,cout,argann&debut=2013-07-15&camp=433,2289 Résultat : OK 2 433;5.00;valide@ok.com 2289;5.00;valide2@oko.com |
Accès aux statistiques
L’accès aux statistiques se fait par le biais d’une page disponible sur le serveur web : https://stat.netaffiliation.com/lisann.php
L’appel à la page de requête peut se faire par méthode GET ou POST.
Cette page comprend un certain nombre de paramètres permettant l'authentification et de préciser les informations souhaitées, les filtres et leurs formatages.
Paramètres de requête
Vous pouvez ajouter des filtres dans la requête avec les paramètres suivants :
Un paramètre ajouté mais vide (sans valeur) dans la requête sera considéré comme non passé, donc avec sa valeur par défaut.
(1) Liste des noms de champs disponibles pour le paramètre « champs » :
Le fuseau horaire: timezone de votre campagne.
Si le paramètre « champs » n'est pas ajouté (ou est vide) dans la requête, il vaut par défaut et en fonction du paramètre « dim » :
« dim=1 » alors « champs » vaut par defaut : idcamp,nomcamp,monnaie,affcpt,affval,clicpt,clival,dclcpt,dclval,foratt,forval,venatt,venval,depatt,depval,boncpt,depbon
« dim=2 » alors « champs » vaut par defaut : idsite,nomsite,monnaie,affcpt,affval,clicpt,clival,dclcpt,dclval,foratt,forval,venatt,venval,depatt,depval, boncpt,depbon
« dim=3 » ou « dim=4 » alors « champs » vaut par défaut : date,monnaie,affcpt,affval,clicpt,clival,dclcpt,dclval,foratt,forval,venatt,venval,depatt,depval,boncpt,depbon
(2) Liste des identifiants de dimension disponibles pour le paramètre « dim » :
(3) Liste des identifiants de période disponibles pour le paramètre « per » :
Les paramètres « debut » / « fin » ET « per » ont pour but de définir la plage de récupération des informations dans la requête.
Si le paramètre « per » est présent dans la requête, il n'est pas nécessaire de définir les paramètres « debut » et/ou « fin ». Et si « debut » et/ou « fin » sont définis, c'est le paramètre « per » qui sera finalement pris en compte.
Exemples de requêtes
Dans les exemples qui suivent, et sauf contre indication, on suppose que l'utilisateur cherche à exécuter une requête avec les paramètres d'identification suivants et en identification V3 :
login : test@test.fr
mot de passe : AzErTy
Objectif : récupérer les statistiques sur les actions réalisées le 12/07/2013, pour tous les sites et programmes en regroupant les informations par programmes : Url : https://stat.netaffiliation.com/lisann.php?authl=test@test.fr&authv=AzErTy&debut=2013-07-12 Résultat : OK 3 175;VPC.com;EUR;370849;370849;6755;6755;0;0;0;0;0;18;0.00;140.13 190;Concours.com;EUR;3336;3336;1387;1387;0;0;0;0;0;5;0.00;29.86 632;Voyage.com;EUR;18986;18986;1731;1731;0;0;0;3;0;5;0.00;105.53 |
Objectif : récupérer les statistiques sur les actions réalisées le 12 juillet 2013, sur tous les programmes, avec des champs spécifiques, en regroupant les informations par programmes : Url : https://stat.netaffiliation.com/lisann.php?authl=test@test.fr&authv=AzErTy&champs=idcamp,venval,depatt,depval&debut=2013-07-12 Résultat obtenu : OK 3 175;18;0.00;140.13 190;5;0.00;29.86 632;5;0.00;105.53 |
Code php d'exemple
<?php //Example for Web Services function checkAndParseStat($content) { $delimiter = ';'; $enclosure = '"'; $escape = '\\'; $rows = explode(PHP_EOL, $content); if(!$rows) { return false; } $nb_rows = (count($rows) - 1); $declared_lines = intval(substr($rows[0], 2, mb_strlen($rows[0]))); if (strpos($rows[0], "KO")) { //Wrong use of the API, please check the query url return false; } elseif (strpos($rows[0], "OK 0")) { //No stat for this query return false; } elseif ($declared_lines === ($nb_rows - 1)) { $values = array(); for ($i = 1; $i < $nb_rows; $i++) { $values[] = str_getcsv($rows[$i], $delimiter, $enclosure, $escape); } return $values; } else { //Something is wrong return false; } } function getNetaffStat($login, $password, $date) { $maxAttempted = 10; $fields = 'idcampagne,nomcampagne,argann,idsite,nomsite,cout,etat,monnaie,date,validation,montant,type'; $content = file_get_contents('https://stat.netaffiliation.com/reqann.php?authl='.$login.'&authv='.$password.'&debut='.$date.'&champs='.$fields); for ($i = 1; $i <= $maxAttempted; $i++) { if (!strpos($http_response_header[0], "200")) { $content = file_get_contents('https://stat.netaffiliation.com/reqann.php?authl='.$login.'&authv='.$password.'&debut='.$date.'&champs='.$fields); } else { break; } //Max 20 query per minute sleep(30); } if($content) { return checkAndParseStat($content); } else { return false;} } $result = getNetaffStat("LOGIN@LOGIN.COM", "PASSWORD", date('Y-m-d')); var_dump($result); ?> |