API CashBack - Public

API CashBack
API CashBack
Guide d'intégration et de récupération d'un identifiant externe
Ce document est destiné à vous présenter l'API CashBack et à vous guider dans le processus
d'intégration et de récupération d'un identifiant externe dans le système de tracking Public-Idées
Version 1.0.5 (03/01/2013) – Copyright © Public-idées
1/8
Version 1.0.5 (03/01/2013) – Copyright © Public-Idées
API CashBack
Table des matières
Présentation de l'API CashBack............................................................................................ 3
1.Introduction....................................................................................................................3
2.Mise en place.................................................................................................................3
3.Contenu et structure de la variable « cb » (CashBack).................................................3
4.Interrogation de l'API CashBack ...................................................................................4
4.1.Principe de base.....................................................................................................4
4.2. Présentation des divers critères de recherche sur l'API.......................................5
4.2.1.Liste des paramètres obligatoires...................................................................5
4.2.2.Liste des paramètres supplémentaires pour affiner votre recherche ...........6
4.3.Exemples d'interrogations .....................................................................................8
2/8
Version 1.0.5 (03/01/2013) – Copyright © Public-Idées
API CashBack
Présentation de l'API CashBack
1. Introduction
Grâce à notre API CashBack, vous pouvez intégrer l’identifiant externe (subId) de votre choix, au
sein du système de tracking de Public-Idées.
Cet identifiant va se voir mis en relation avec vos remontées de ventes et/ou formulaires et par la
même occasion être inséré dans vos statistiques.
2. Mise en place
Pour mettre en place votre identifiant externe et l'intégrer au sein du process de tracking de
Public-Idées, rajoutez la variable &cb=votreidentifiantexterne aux URL de tracking de la
plateforme .
Exemple d'intégration
Lien de tracking de base HTML :
<a href="http://tracking.publicidees.com/clic.php?
partid=2&progid=109&promoid=54004&cb=votreidentifiantexterne " target="_blank"><img
src="http://tracking.publicidees.com/banner.php?
partid=2&progid=109&promoid=54004&cb=votreidentifiantexterne " border="0"></a>
Lien de tracking JAVASCRIPT :
<script type="text/javascript" src="http://tracking.publicidees.com/showbanner.php?
partid=2&progid=109&promoid=54004&cb=votreidentifiantexterne"></script>
À noter :
Il est important d’ajouter la variable &cb=votreidentifiantexterne sur l’ensemble du tracking (« a href »
et « img src ») pour pouvoir correctement remonter l’identifiant lors des actions postclic et postview.
L’ajout de la variable dans les trackings de programmes au clic, au double clic et au clic d’arrivé est
inutile car non pris en charge sur ces programmes.
Présentation de l'API CashBack
Version 1.0.5 (03/01/2013) – Copyright © Public-Idées
3/8
API CashBack
3. Contenu et structure de la variable « cb » (CashBack)
La variable «cb » doit renvoyer la valeur de l'identifiant externe que vous aurez choisi.
D'autre part, votre identifiant contenu dans la variable «cb » devra répondre à un certain nombre de
caractéristiques :
•
•
•
•
Il est limité à 255 caractères
Il ne doit pas comporter d'espaces
Il peut contenir des lettres et des chiffres
Il ne doit pas contenir de caractères spéciaux ou accentués (accents, espaces, des &...). Si ce
dernier devait être amené à en comporter, vous devrez l'encoder avant de le passer en
paramètre
4. Interrogation de l'API CashBack
4.1. Principe de base
Une fois votre identifiant externe intégré au sein du système de tracking de Public-Idées, vous allez
pouvoir interroger notre API sécurisée afin d’obtenir toutes les informations relatives aux ventes et
aux formulaires que vous aurez générés par le biais de votre identifiant externe.
Les étapes d'interrogation de notre API sont les suivantes :
•
•
Contactez notre API à l'url suivante : http://api.publicidees.com/cb.php
A cette url de base vous devez rajouter des paramètres obligatoires qui vous permettront de
vous identifier, à savoir : votre clé sécurisée et votre identifiant de site
À noter :
Pour information, ces identifiants sont obligatoires pour accéder à notre API sécurisée.
Pour ceux qui auront effectué une demande d'identifiants auprès de notre équipe éditeurs, vous les
retrouverez dans le corps du mail qui vous aura été envoyé.
Dans le cas ou vous souhaitez utiliser notre API mais que vous ne disposez pas encore d'identifiants, vous
pouvez effectuer une demande par mail à [email protected]
Une fois que vous aurez obtenu vos identifiants, ces derniers se présenteront dans l'url sous cette forme :
http://api.publicidees.com/cb.php?k=votre_cle&p=votre_identifiant
Présentation de l'API CashBack
Version 1.0.5 (03/01/2013) – Copyright © Public-Idées
4/8
API CashBack
Pour information :
- La variable « p » pour « votre_identifiant » correspond à votre identifiant de site affilié. A titre indicatif
il équivaut à la valeur du paramètre « partid » dans vos liens de tracking.
- La variable « k » pour « votre_cle » correspond à votre clé sécurisée.
•
Une fois identifié, l'API va vous générer un flux XML
Exemple de flux XML généré :
<cashBack id="[Id interne affilié Public-Idées]">
<programme id="[Id interne programme Public-Idées]">
<name>[Nom du programme]</name>
<statistiques total="[Nombre de clics total sur la période]">
<clic date="[Date du clic]" nbre="[Nombre de clics]" />
. . .
. . .
</statistiques>
<action id="[id interne action annonceur]" cashBack="[Id interne cash back
affilié]" dateAction="[Date d’enregistrement de l’action : aaaa-mm-jj]"
dateValid="[Date de traitement de l’action par l’annonceur : aaaa-mm-jj]"
statut="[Statut de l’action]" type="[Type d’action]" montantCom="[Montant de
la commission reversée à l’affilié]" montantVente="[Montant de la vente HT
payée par le client]" />
. . .
. . .
</programme>
. . .
. . .
</cashBack>
4.2. Présentation des divers critères de recherche sur l'API
4.2.1. Liste des paramètres obligatoires
Comme nous vous l'avons présenté précédemment, vous avez des paramètres obligatoires à
renseigner afin de vous connecter à notre API. Ces derniers sont uniques et personnels.
Les paramètres obligatoires sont la variable « p »(pour votre identifiant de site) et « k » (pour votre
clé sécurisée).
Par défaut, en appelant http://api.publicidees.com/cb.php?k=votre_cle&p=votre_identifiant
Vous obtenez des statistiques pour la journée en cours
Présentation de l'API CashBack
Version 1.0.5 (03/01/2013) – Copyright © Public-Idées
5/8
API CashBack
4.2.2. Liste des paramètres supplémentaires pour affiner votre recherche
Au delà des paramètres d'interrogation obligatoires, vous pouvez affiner votre recherche en ajoutant
dans l'url des paramètres supplémentaires.
Attention :
Lors de l'interrogation de l'API il n'est pas possible d'avoir plusieurs fois la même variable dans l'url
d'appel. Il faut donc effectuer plusieurs appels.
Exemple : http://api.publicidees.com/cb.php?k=votre_cle&p=votre_identifiant&cb=1&cb=3
Consultation des statistiques pour un type de rémunération (vente, formulaire) :
Rajoutez la variable « t » avec la valeur correspondant au type de la commission dans l'url
d'interrogation de l'API
• t = 3 : rémunération à la vente
• t = 4 : rémunération au formulaire
• si la variable « t » n'est pas renseignée vous aurez par défaut les 2 rémunérations
Consultation des statistiques en fonction du statut de la vente/formulaire (en attente, validé ou
refusé ) :
Rajoutez la variable « s» avec la valeur correspondant au type de la commission dans l'url
d'interrogation de l'API
• s = 0 : vente/lead refusé
• s = 1 : vente/lead en attente
• s = 2 : vente/lead validé
• si la variable « s » n'est pas renseignée vous aurez par défaut les 3 états
Consultation des statistiques sur une date définie
Rajoutez la variable « d» dans l'url d'interrogation de l'API
• La date doit être au format aaaa-mm-jj
• si la variable « d» n'est pas renseignée vous aurez par défaut la date du jour
Présentation de l'API CashBack
Version 1.0.5 (03/01/2013) – Copyright © Public-Idées
6/8
API CashBack
Consultation des statistiques sur une période définie
Rajoutez la variable « dd» (pour date de début) et la variable « df» (pour date de fin) dans l'url
d'interrogation de l'API
• La date doit être au format aaaa-mm-jj
Exemple : &dd=2011-09-23&df=2011-09-30
Consultation des statistiques à date d'action ou de validation (accepté ou refusé)
Rajoutez la variable « td» avec la valeur correspondant au type de date souhaité
• td = a : pour obtenir les statistiques à date d'action, date à laquelle a été enregistré la vente
ou le lead (pour information, « td = a » est la valeur par défaut qui est prise en compte)
• td = v : pour obtenir les statistiques à date de validation, date à laquelle l'annonceur à validé
ou refusé la vente/lead
Consultation des statistiques pour un certain identifiant cashback
Rajoutez la variable « cb» avec la valeur de l'identifiant cashback désiré dans l'url d'interrogation
de l'API
• si la variable « cb» n'est pas renseignée vous aurez par défaut tous vos identifiants externes
Attention :
Lors de la restitution de la variable « cb » dans le flux xml , cette dernière va être encodée. Vous devrez
donc utiliser la fonction urldecode() ou un équivalent pour retrouver la chaîne d'origine.
Consultation des statistiques avec affichage des clics
Rajoutez la variable « c» dans l'url d'interrogation de l'API
• c = 1 : affichage du nombre de clics avec détail par jour
À noter :
Tous les paramètres que nous vous avons présentés peuvent être cumulés à l'exception de :
–
la variable « d » (pour faire une recherche sur un jour défini) ET la variable « dd / df » (pour faire
une recherche sur une période définie)
–
la variable « td=a » et « td=v ». En effet, on ne peut pas faire de recherche à date « d'action » et à
date de « validation »
Présentation de l'API CashBack
Version 1.0.5 (03/01/2013) – Copyright © Public-Idées
7/8
API CashBack
4.3. Exemples d'interrogations
Consultation des statistiques sur une journée donnée :
http://api.publicidees.com/cb.php?k=VOTRE_CLE&p=VOTRE_ID&d=2011-11-11
Consultation des statistiques sur une période :
http://api.publicidees.com/cb.php?k=VOTRE_CLE&p=VOTRE_ID&dd=2011-11-02&df=2011-1111
Consultation des statistiques avec affichage des clics (seulement sur le mois en cours):
http://api.publicidees.com/cb.php?k=VOTRE_CLE&p=VOTRE_ID&dd=2011-11-02&df=2010-1111&c=1
Consultation des statistiques validées sur une période donnée :
http://api.publicidees.com/cb.php?k=VOTRE_CLE&p=VOTRE_ID&dd=2011-11-02&df=2011-1111&td=v
Consultation des statistiques validées avec un identifiant cash back donné :
http://api.publicidees.com/cb.php?k=VOTRE_CLE&p=VOTRE_ID&dd=2011-11-02&df=2011-1111&td=v&cb=votre_identifiant_cash_back
Consultation des ventes validées et en attente entre le 29/09/2011 et le 31/09/2011 :
http://api.publicidees.com/cb.php?k=VOTRE_CLE&p=VOTRE_ID&dd=2011-11-02&df=2011-1111&s=1&t=3
ET
http://api.publicidees.com/cb.php?k=VOTRE_CLE&p=VOTRE_ID&dd=2011-11-02&df=2011-1111&s=2&t=3
Présentation de l'API CashBack
Version 1.0.5 (03/01/2013) – Copyright © Public-Idées
8/8