Advertiser access
Introduction
What is the Advertiser API and why use it?
API = application programming interface) is a software interface that allows one software or service to be "connected" to another software or service in order to exchange data and functionality.
The Kwanko remote query system (API) allows you to :
Retrieve your forms and sales with the reqann.php page
Get your statistics with the lisann.php page
General requirements
To access the Kwanko remote query system, the user must be registered with Kwanko and have confirmed their user account with a login and password.
Once you have done this, generate your password on the Web Services page or contact your account manager or the SKALE with Kwanko service to generate it for you. The password for using Web Services is different from the one used to access the Kwanko / SKALE platform.
Here are the parameters that allow you to connect to the API system:
If you lose your Web Services login details, we invite you to connect to the "Web Services" page of the Kwanko platform. If this page is not accessible on your account, please contact your account manager or the SKALE service.
Security
It is mandatory to access the request page through the HTTPS protocol which then encrypts all information.
Identification
List of parameters that allow the system to identify the user :
*Web Services credentials provided before July 2013
Clarification of the "verif" parameter:
This parameter depends on the security level set on the user's account. Depending on the security level the value of this parameter can be in clear text or as a 32 character string from the md5 function called on the concatenation of the other parameters.
See details of the security levels below:
Level 1
The user adds his password in clear text in the "mdp" parameter, the "verif" parameter must not be used, the request must go through the HTTP protocol. The address of the page then starts with http://stat.netaffiliation.com/
Level 2
The user adds an md5 hash of his login, password, IP address and the current date (YYYY-MM-DD) in the "verif" parameter, the "mdp" parameter must not be used, the request must go through the HTTP protocol. The address of the page then starts with http://stat.netaffiliation.com/ Ex: md5($username.$password.$ipaddress.$date);
Level 3
The user adds an md5 hash of his login, password, IP address, the current date (YYYY-MM-DD) and the request in the "verif" parameter, the "mdp" parameter must not be used, the request must go through the HTTP protocol. The address of the page then starts with http://stat.netaffiliation.com/
Level 4
The user adds his password in clear text to each request in the "mdp" parameter, the "verif" parameter must not be used, the request must go through the HTTPS protocol which then encrypts all the information. The address of the page then begins with https://stat.netaffiliation.com/
Result of the query
The result of the query is plain text and contains, on the first line, a query return code, then a line-by-line result with the requested fields separated by a semi-colon ";".
If a semicolon ";" appears in one of the fields of a result line, the field is surrounded by double quotes " " ". In other words, it is a CSV result after the return code.
The possible return codes on the first line are :
If the query is successful: the string "OK" followed by a space and then the number of lines retrieved. A query may be successful and return no rows, simply OK 0
If the request fails: the string "KO" followed by a space then an error number followed by a space then an explanation
The possible error numbers are :
Incomplete parameters provided: one or more mandatory parameters are missing.
Incorrect identification parameters provided: login problem.
Incorrect identification parameters provided: password problem.
Misunderstood query parameter (e.g. wrong syntax). In this case, the error message that follows contains the name of the problematic parameter.
System temporarily unavailable.
Incorrect security level.
Retrieval of Forms/Sales
Access
Access is via a page available on the web server: https://stat.netaffiliation.com/reqann.php
The call to the request page can be made by GET or POST method.
This page contains a number of parameters for identifying and specifying the desired information, filters and their formatting.
Request parameters
Warning: A parameter added but empty (without value) in the query, will be considered as not passed, thus with its default value.
You can add filters to the query with the following parameters:
Available fields
List of field names available for the "fields" parameter
You can add more to your request:
header which allows to visualise the labels of the columns
csv which allows you to download the query in csv format
Example of a query with header and csv:
The time zone is UTC+0
If the "champs" parameter is not added to the query (or is empty), it defaults to: idcampagne,idsite,date,validation,etat,montant,cout,monnaie,argann
Examples of conversions queries
In the following examples, and unless otherwise stated, it is assumed that the user seeks to execute a query with the following identification parameters and in V3 identification:
login : test@test.fr
password : AzErTy
Objective: to recover validated and pending sales/forms made between two dates on all programmes and sites:
Result:
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
Objective: to retrieve validated sales/forms from 15/07/2013, with specific fields, on all programmes and sites:
OK 3
133;12.47;toto@toto.com
133;8.12;test@email.com
433;5.00;valide@ok.com
Objective: to retrieve the sales/forms of 15/07/2013, with specific fields, on the 433 and 2289 programs and all sites:
Result obtained :
OK 2
433;5.00;valide@ok.com
2289;5.00;valide2@oko.com
Access to statistics
The statistics are accessed through a page available on the webserver: https://stat.netaffiliation.com/lisann.php
The call to the request page can be made by GET or POST method.
This page contains a number of parameters for authentication and for specifying the desired information, filters and their formatting.
Request parameters
You can add filters to the query with the following parameters:
A parameter added but empty (without value) in the query will be considered as not passed, thus with its default value.
(1) List of field names available for the "champs" parameter:
The time zones change depending on the identification mode:
Identification v2 : Time zone : Europe/Paris GMT+2
Identification v3: Time zone: UTC+0
If the "fields" parameter is not added (or is empty) in the query, it defaults to the "dim" parameter:
"dim=1" then "champs" defaults to: idcamp,nomcamp,monnaie,affcpt,affval,clicpt,clival,dclcpt,dclval,foratt,forval,venatt,venval,depatt,depval,boncpt,depbon
"dim=2" then "champs" defaults to: idsite,nomite,monnaie,affcpt,affval,clicpt,clival,dclcpt,dclval,foratt,forval,venatt,venval,depatt,depval,boncpt,depbon
If "dim=3" or "dim=4" then "champs" defaults to: date,currency,affcpt,affval,clicpt,clival,dclcpt,dclval,foratt,forval,venatt,venval,depatt,depval,boncpt,depbon
(2) List of available dimension identifiers for the "dim" parameter:
(3) List of available period identifiers for the "per" parameter:
The parameters "debut" / "fin" AND "per" are used to define the range of information retrieved in the query.
If the "per" parameter is present in the request, it is not necessary to define the "debut" and/or "fin" parameters. And if "start" and/or "end" are defined, it is the "per" parameter that will finally be taken into account.
Examples of requests
In the following examples, and unless otherwise stated, it is assumed that the user seeks to execute a query with the following identification parameters and in V3 identification:
login : test@test.fr
password : AzErTy
Objective: to retrieve statistics on the actions carried out on 12/07/2013, for all sites and programmes, grouping the information by programme:
Url: https://stat.netaffiliation.com/lisann.php?authl=test@test.fr&authv=AzErTy&debut=2013-07-12
Result:
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
Objective: to retrieve statistics on actions carried out on 12 July 2013, on all programmes, with specific fields, grouping the information by programmes:
Result obtained :
OK 3
175;18;0.00;140.13
190;5;0.00;29.86
632;5;0.00;105.53
Example php code
<?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);
?>