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 :

  1. Récupérer vos formulaires et vos ventes avec la page reqann.php

  2. 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 : 

Nom

Signification

Format

Obligatoire

auth

Le login. Demandez à votre contact Kwanko habituel.

Email

OUI

authv

Le mot de passe. Demandez à votre contact Kwanko habituel.

12 Caractères

OUI

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 :

Nom

Signification

Format

Obligatoire

login

L’identifiant 

12 caractères maximum

Oui

verif

Le mot de passe ou une chaîne de vérification composée (MD5)

32 caractères parmi 0-9 et a-f

Oui pour le niveau de sécurité 2 et 3 uniquement

mdp

Le mot de passe 

12 caractères maximum

Oui pour le niveau de sécurité 1 et 4 uniquement

 *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 :

  1. Paramètres fournis incomplets : il manque un ou plusieurs paramètres obligatoires.

  2. Paramètres d'identification fournis incorrects : problème de login.

  3. Paramètres d'identification fournis incorrects : problème de mot de passe.

  4. 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.

  5. Système indisponible temporairement.

  6. 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 :

Nom

Signification

Format

Obligatoire

camp

Indiquez quel(s) programme(s) est/sont concerné(s) par la requête

Un identifiant de programme ou une liste d’identifiants de la plateforme NetAffiliation, séparés par des virgules

Non, défaut=toutes

début

Indiquez le premier jour concerné par la requête

Chaîne de la forme : AAAA-MM-JJ

Non, défaut=du début (tout)

fin

Indiquez le dernier jour concerné par la requête

Chaîne de la forme : AAAA-MM-JJ

Non, défaut=date du jour

champs

Indiquez les champs souhaités dans le résultat ainsi que leur ordre de présentation Voir ci-dessous pour la liste des champs disponibles

Liste de noms de champs séparés par des virgules

Non, voir les valeurs par défaut ou possibles ci-dessous (1)

etat

Indiquez l’état des formulaires ou des ventes

Valeurs attendues : « v » pour validé / « r » pour refusé / « a » pour en attente / une combinaison

Non, défaut=toutes (« vra »)

types

Indiquez le type d’événement

Valeurs attendues : « f » pour les formulaires / « v » pour les ventes

Non, défaut=tous (« fv »)

site

Indiquez quel(s) site(s) est/sont concerné(s) par la requête

Un identifiant de site ou une liste d'identifiants de la plateforme NetAffiliation, séparés par des virgules

Non, défaut=tous

Champs disponibles

Liste des noms de champs disponibles pour le paramètre “champs” 

Nom

Signification

Format de retour

idcampagne

L'identifiant du programme de l'annonceur sur la plateforme Kwanko

Entier

nomcampagne

Le nom textuel du programme de l'annonceur

Chaîne de caractères

argann

La valeur du paramètre « argann » passé dans le tag de tracking

Chaîne de caractères

idsite

L'identifiant du site diffuseur sur la plateforme Kwanko

Entier

nomsite

Le nom textuel du site diffuseur

Chaîne de caractères

typologie

Le nom textuel de la typologie à laquelle le diffuseur est associé chez Kwanko

Chaîne de caractères

cout

Le montant des coûts, dans la monnaie du programme, de la commission

Nombre flottant avec le point « . » comme séparateur décimal

montant

Le montant de la vente dans la monnaie du programme, passé dans le paramètre «argmon» du tag de tracking

Nombre flottant avec le point « . » comme séparateur décimal. Vide si la ligne est un formulaire

monnaie

La monnaie du programme de l'annonceur

Identification v2 : « euro » pour l'euro / Identification v3 : Norme ISO 4217

etat

L'état de validation du formulaire ou de la vente

Valeurs attendues : « v » : validé / « r » : refusé / « a » : en attente

date

La date de réalisation du formulaire ou de la vente

Chaîne de la forme : AAAA-MM-JJ HH:II:SS

dcookie

La date du dernier cookie déposé

Chaîne de la forme : AAAA-MM-JJ HH:II:SS

validation

La date de validation du formulaire ou de la vente. Si le formulaire ou la vente est déjà validé(e) ou refusé(e), ce sera la date de réalisation

Chaîne de la forme : AAAA-MM-JJ HH:II:SS

cookie

L'origine du formulaire ou de la vente

Valeurs attendues : « clic » / « affichage » / « reattribution »

tag

Le nom du tag de tracking du formulaire ou de la vente

Chaîne correspondant au nom du tag de tracking paramétré sur la plateforme Kwanko

rappel

L'identifiant interne de la plateforme Kwanko du formulaire ou de la vente

Entier


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 :

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 :


Nom

Signification

Format

Obligatoire

dim

Indiquez le critère de groupement des informations statistiques

Un identifiant de la dimension, voir la liste ci-dessous

Non, défaut=2 Voir les valeurs possibles ci-dessous (2)

camp

Indiquez quel(s) programme(s) est/sont concerné(s) par la requête

Un identifiant de programme ou une liste d’identifiants de la plateforme Kwanko, séparés par des virgules

Non, défaut=tous

debut

Indiquez le premier jour concerné par la requête

Chaîne de la forme : AAAA-MM-JJ

Non, défaut=du début (tout)

fin

Indiquez le dernier jour concerné par la requête

Chaîne de la forme : AAAA-MM-JJ

Non, défaut= « debut »

per

Indiquez l'une des périodes prédéfinies concernées par la requête

Un identifiant de la période, voir la liste ci-dessous

Non, défaut=1 Voir les valeurs possibles ci-dessous (3)

champs

Indiquez les champs souhaités dans le résultat ainsi que leur ordre de présentation 

Voir ci-dessous pour la liste des champs disponibles

Liste de noms de champs séparés par des virgules

Non, voir les valeurs par défaut ou possibles ci-dessous (1)

site

Indique quel(s) site(s) est/sont concernés par la requête

Un identifiant de site ou une liste d'identifiants de la plateforme Kwanko, séparés par des virgules

Non, défaut=tous

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 » : 

Nom

Signification

Format de retour

idcamp

L'identifiant du programme de la plateforme Kwanko Ce champs peut être utilisé uniquement avec le paramètre « dim=1 »

Entier

nomcamp

Le nom textuel du programme Ce champs peut être utilisé uniquement avec le paramètre « dim=1 »

Chaîne de caractères

idsite

L'identifiant du site de la plateforme Kwanko. Ce champs peut être utilisé uniquement avec le paramètre « dim=2 »

Entier

nomsite

Le nom textuel du site Ce champs peut être utilisé uniquement avec le paramètre « dim=2 »

Chaîne de caractères

date

La date de réalisation 

Ce champs peut être utilisé uniquement avec le paramètre « dim=3 » ou « dim=4 »

Chaîne de la forme : • AAAA-MM-JJ si le champ « dim=3 » • AAAA-MM si le champ « dim=4 »

affcpt

Nombre total d'affichages

Entier

affval

Nombre d'affichages validés

Entier

clicpt

Nombre total de clics

Entier

clival

Nombre de clics validés

Entier

dclcpt

Nombre total de double clic

Entier

dclval

Nombre de double clic validés

Entier

foratt

Nombre de formulaires en attente

Nombre flottant avec le point « . » comme séparateur décimal

forval

Nombre de formulaires validés

Nombre flottant avec le point « . » comme séparateur décimal

forref

Nombre de formulaires refusés

Nombre flottant avec le point « . » comme séparateur décimal

venatt

Nombre de ventes en attente

Nombre flottant avec le point « . » comme séparateur décimal

venval

Nombre de ventes validées

Nombre flottant avec le point « . » comme séparateur décimal

venref

Nombre de ventes refusées

Nombre flottant avec le point « . » comme séparateur décimal

depatt

Somme des coûts en attente de validation

Nombre flottant avec le point « . » comme séparateur décimal

depval

Somme des coûts validés

Nombre flottant avec le point « . » comme séparateur décimal


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

  • « dim=2 » alors « champs » vaut par defaut  : idsite,nomsite,monnaie,affcpt,affval,clicpt,clival,dclcpt,dclval,foratt,forval,venatt,venval,depatt,depval

  • « 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

(2) Liste des identifiants de dimension disponibles pour le paramètre « dim » :

ID

Signification

1

Programme

2

Site

3

Jour

4

Mois

(3) Liste des identifiants de période disponibles pour le paramètre « per » :

Les paramètres « début » / « 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 « début » et/ou « fin ». Et si « début » et/ou « fin » sont définis, c'est le paramètre « per » qui sera finalement pris en compte.

ID

Signification

1

Aujourd'hui

2

Hier

3

7 derniers jours

4

Ce mois

5

Mois dernier

6

Ce trimestre

7

Cette année

8

Du début

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 :

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);

?>