API COLLECT V1 FR

28/05/2021

Version 1.1

Objectif

Collecter les informations de commandes, de ventes ou de services rendus pour nourrir la plateforme Toalk qui se charge d'envoyer ensuite l'email de collecte d'avis aux clients et d'analyser tous les retours. La plateforme gère dédoublonnage et n'envoie pas d'emails consécutifs dans un délai de 6 mois.  

Protocole

Les requests se font en mode https à l’url https://api.toalk.com/v1/putmail.php, on récupère un accusé de l'enregistrement ainsi qu'un id associé.

 

Authentification

L'authentification se fait à l'aide d'une apikey associée à votre user toalk, vous pouvez trouver ces informations dans votre espace client. Vous devez passer en paramètre au minimum l'apikey, l'email du client et soit un numéro de compte (account) soit votre propre identifiant de compte (par exemple un code magasin).

Afin de tester nos apis, vous pouvez utiliser le compte de test suivant pour réaliser vos développements dès à présent en attendant d'avoir vos accès définitifs :

account : 1234

apikey : 9811cc0bef4049aca80d6ba17e806013

Paramètres

Les paramètres sont à passer en POST sous forme d’un tableau json.

NOM	REQUIS	TYPE	DESCRIPTIF
apikey	O	Varchar(32)	Apikey liée à votre user d'accès toalk.com
account	O si shortcode est nul	int	Numéro de compte. Attention dans le cas d'un client multicompte (par exemple une enseigne de magasins) il faut bien préciser quel est le compte concerné (en l'occurence le magasin)
shortcode	O si account est nul	varchar(12)	Numéro d'identification du compte qui vous est propre, par exemple un code magasin
mail	O	Varchar(45)	email du client qui sera sollicité pour déposer un avis
client	N	Varchar(45)	Votre numéro d'identification du client, sert aux recherches et dans la personnalisation des emails
order	N	Varchar(45)	Votre numéro de commande, sert aux recherches et dans la personnalisation des emails
firstname	N	Varchar(45)	Le Prénom du client, si vous souhaitez l'utilisez dans la personnalisation des emails
fullname	N	Varchar(45)	Nom complet du client (prénom + nom), sert aux recherches et dans la personnalisation des emails
ref1	N	Varchar(45)	Une référence qui vous est propre, peut servir à la personnalisation des emails et aux regroupement dans les analyses
ref2	N	Varchar(45)	Une référence qui vous est propre, peut servir à la personnalisation des emails et aux regroupement dans les analyses
ref3	N	Varchar(45)	Une référence qui vous est propre, peut servir à la personnalisation des emails et aux regroupement dans les analyses
version	N	int	Version de l'email à envoyer. Une même version d'email ne sera pas réenvoyée au client dans un délai de 6 mois. Permet de gérer plusieurs versions d'email, par exemple un mail suite à un devis et un mail lors d'un achat

 

Réponse JSON

La réponse contient le détail de la course enregistrée ainsi que son Id permettant par la suite d'en faire le suivi. En cas de rupture de charge, deux courses avec le même numéro seront créées et visibles par l'API de tracking pour suivre chacun des deux trajets. En cas d'erreur, l'api répond un json contenant un champ Message précisant la nature de l'erreur.

NOM	Taille	DESCRIPTIF
status	varchar(3)	OK ou NOK
message	varchar(45)	Message d'erreur ou de confirmation d'enregistrement
messageId	varchar(45)	Id de l'enregistrement

Exemple d'appel

<?php
$url = "https://api.toalk.com/v1/putmail.php";
$data = array(
	'apikey' => '9811cc0bef4049aca80d6ba17e806013',
	'account' => 1234,
	'mail' => 'yt@digf.fr',
	'client' => '707543',
	'order' => 'CO-202104001',
	'firstname' => 'Elon',
	'fullname' => 'Elon Musk',
	'ref1' => 'Magasin Paris 8',
	'ref2' => 'Vendeur Michel',
	'ref3' => 'Produit 56',
);
$datajson = json_encode($data);
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, $datajson);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type:application/json'));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$res = curl_exec($curl);
curl_close($curl);
var_dump($res);
?>

Exemple de réponse

{"status":"OK","message":"Customer has been added","messageId":"1234567"}