Utilisation de l'API avec Curl
Vous trouverez ici l'explication du fonctionnement de la classe sellsyConnect (implémentant curl) que vous pourrez trouver ici
Comme vous avez pu le voir dans la section 'Premiers Pas' il y a deux type d'applications : publique et privée. Avec cette classe vous ne pouvez créer que des applications privées. Libre à vous de la modifier afin de pouvoir utiliser une authentification de type third-party et donc de pouvoir utiliser des applications publiques.
La classe sellsyConnect offre une méthode d'authentification via la classe Curl de PHP. Voici la première partie de son code :
class sellsyConnect_curl {
private static $api_url = "{{url_api}}";
private static $oauth_access_token = "{{user_token}}";
private static $oauth_access_token_secret = "{{user_secret}}";
private static $oauth_consumer_key = "{{consumer_token}}";
private static $oauth_consumer_secret = "{{consumer_secret}}";
private static $instance;
private $header;
private function __construct() {
$encoded_key = rawurlencode(self::$oauth_consumer_secret).'&'.rawurlencode(self::$oauth_access_token_secret);
$oauth_params = array (
'oauth_consumer_key' => self::$oauth_consumer_key,
'oauth_token' => self::$oauth_access_token,
'oauth_nonce' => md5(time()+rand(0,1000)),
'oauth_timestamp' => time(),
'oauth_signature_method' => 'PLAINTEXT',
'oauth_version' => '1.0',
'oauth_signature' => $encoded_key
);
$this->header = array(self::getHeaders($oauth_params), 'Expect:');
}
.
.
.
Vous avez 4 paramètres à remplacer afin de pouvoir vous connecter et dans un deuxième temps, interagir avec l'API.
- {{url_api}} - L'url de l'api
- {{user_token}} - Le token de votre utilisateur
- {{user_secret}} - Le secret de votre utilisateur
- {{consumer_token}} - Le token de votre application
- {{consumer_secret}} - Le secret de votre application
Ici l'Authentification est directe, une fois que vous avez renseigné ses informations, vous êtes connecté !
Une fois connecté, c'est à dire lorsque vous avez votre token/secret d'accès, vous pouvez appeler les méthodes de l'API. La classe sellsyConnect_curl fournit la méthode requestApi qui permet de gérer cette étape. Voici son code :
public function requestApi($requestSettings, $showJSON=false){
$params = array(
'request' => 1,
'io_mode' => 'json',
'do_in' => json_encode($requestSettings)
);
$options = array(
CURLOPT_HTTPHEADER => $this->header,
CURLOPT_URL => self::$api_url,
CURLOPT_POST => 1,
CURLOPT_POSTFIELDS => $params,
CURLOPT_RETURNTRANSFER => true,
);
$curl = curl_init();
curl_setopt_array($curl, $options);
$response = curl_exec($curl);
curl_close($curl);
$back = json_decode($response);
if ($showJSON){
self::debug($back); exit;
}
if (strstr($response, 'oauth_problem')){
sellsyTools::storageSet('oauth_error', $response);
}
if ($back->status == 'error'){
sellsyTools::storageSet('process_error', $back->error);
}
return $back;
}
Cette fonction prend en paramètre un tableau qui permettra de définir quelle méthode de l'API nous voulons utiliser et avec quels paramètres. Voici, par exemple comment récupérer la liste des clients avec une pagination et un paramètre de recherche :
$requestSettings = array( 'method' => 'Client.getList', 'params' => array( 'search' => array( 'contains' => 'TESTDOCUMENTATION', ), 'pagination' => array ( 'pagenum' => 1, 'nbperpage' => 10 ) ) ); $clientsListing = sellsyConnect_curl::load()->requestApi($requestSettings);
En réponse vous allez recevoir une réponse encodée suivant le IO_MODE que vous avez spécifié. Par exemple :
{"response":{"infos":{"nbperpage":10,"nbpages":1,"pagenum":"1","nbtotal":"1"},"result":{"corporation_2739":{"contactType":"corporation","status":"ok","contactId":"2739","contactDetails":"corporation","name":"","fullName":"TESTDOCUMENTATION","position":"","pic":"","tel":"","fax":"","email":"","id":"corporation_2739","contactMore":""}}},"error":"","status":"success"}
Vous recevez une réponse JSON contenant 3 informations :
- response - les données
- status - le status de notre requête (success/error)
- error - le message d'erreur s'il y en a un
Attention
En fonction des différentes méthodes le tableau de paramètres ainsi que la réponse peuvent varier. Voir la description des méthodes et de leurs réponses.En utilisant l'API Sellsy vous pourrez être confronté à deux types d'erreurs :
-
Les message d'erreur OAUTH - Dans la réponse vous ne recevrez pas de données formatées mais une chaine du type oauth_problem={{problem}}
oauth_problem=signature_invalid
oauth_problem=consumer_key_refused
-
Les message d'erreur de l'API - La réponse sera formatée en JSON, vous aurez donc dans la réponse JSON le status:error et error:{{error_message}}
{"response":null,"error":{"code":"E_IO_MODE_DONT_EXIST","message":"IO_MODE jsone doest not exist","more":"jsone"},"status":"error"}
Les classes sellsyConnect et sellsyTools permettent une première gestion simpliste de ces erreurs. Nous pouvons la retrouver dans la methode requestApi de la classe sellsyConnect :
.
.
.
if (strstr($response, 'oauth_problem')){
sellsyTools::storageSet('oauth_error', $response);
}
if ($back->status == 'error'){
sellsyTools::storageSet('process_error', $back->error);
}
.
.
.
- Les erreurs de l'API sont stockées dans process_error afin d'être rendues plus tard dans la transaction.
- Les erreurs d'OAuth sont stockées dans oauth_error et l'étape de connexion est remise à getRequestToken. Ceci signifie que l'utilisateur a été déconnecté.
La classe sellsyTools dispose d'une méhode permettant de rendre les erreurs : showErrors.
Vous avez maintenant toutes les cartes en main pour commencer à développer votre application. Vous pourrez trouver l'ensemble des méthodes, leurs paramètres et leurs formats de réponse dans dans les sections concernées.