Utilisation de l'API avec OAuth

Vous trouverez ici l'explication du fonctionnement de la classe sellsyConnect (implémentant Oauth) et que vous pourrez trouver ici

Cette classe vous permet de créer des applications privées et publiques.

Comme vous avez pu le voir dans la section 'Premiers Pas' il y a deux type d'applications : publique et privée. Les deux types d'application se connectent de la même façon.

La classe sellsyConnect offre une méthode d'authentification via la classe OAuth de PHP. Voici la première partie de son code :

/*
 * @desc Sellsy Connect, offer stuff to use the api. Singleton class
 */
class sellsyConnect {

	/*
	 * the api urls
	 */
	private static $api_url = "{{url_api}}";
	private static $req_token_url = "{{url_api}}/request_token";
	private static $acc_token_url = "{{url_api}}/access_token";



	/**
	 * @desc check for token in storage or redirect to the loggin page
	 * @return type 
	 */
	public function checkApi() {

		if (!isset($_REQUEST['oauth_token']) && !sellsyTools::storageGet('step')) { 
			sellsyTools::storageSet('step', 'getRequestToken');
		}

		try {	 

			if (sellsyTools::storageGet('step') == "getRequestToken"){	
				$oauth_datas = self::$oauth_client->getRequestToken(self::$req_token_url."?oauth_callback={{oauth_callback}}");
				sellsyTools::storageSet('oauth_token_secret', $oauth_datas['oauth_token_secret']);
				sellsyTools::storageSet('step', 'getAccessToken');
				header('Location: '.$oauth_datas['authentification_url']."?oauth_token=".$oauth_datas['oauth_token']);
				exit;
			}

			if (sellsyTools::storageGet('step') == "getAccessToken"){
				self::$oauth_client->setToken($_REQUEST['oauth_token'], sellsyTools::storageGet('oauth_token_secret'));
				$oauth_datas = self::$oauth_client->getAccessToken(self::$acc_token_url, null, $_REQUEST['oauth_verifier']);
				sellsyTools::storageSet('oauth_token', $oauth_datas['oauth_token']);
				sellsyTools::storageSet('oauth_token_secret', $oauth_datas['oauth_token_secret']);
				sellsyTools::storageSet('step', 'accessApi');
			}

			if (!sellsyTools::storageGet('step')) {
				sellsyTools::storageSet('step', 'getRequestToken');
				header('Location : index.php');
			}

		} catch(OAuthException $E){
			sellsyTools::storageSet('step', 'getRequestToken');
			sellsyTools::storageSet('oauth_error', self::$oauth_client->getLastResponse());
		}
	}

}

Comme vous pouvez le voir, 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
• {{token}} - Le token de votre consumer (votre application)
• {{secret}} - Le secret de votre application
• {{oauth_callback}} - L'adresse de retour une fois que l'utilisateur s'est authentifié via la page de login de Sellsy.

L'authentification se fait via la méthode checkApi. Le processus de connexion se décompose en plusieurs étapes :

• 1.getRequestToken - Dans cette étape, nous regardons si nous avons un token de requête. Si nous n'en n'avons pas, alors nous en demandons un à l'API. Attention, un token de requête n'est valide que 5 minutes.
• 2.getAccessToken - Une fois que nous avons un token de requête, nous allons demander à le convertir en token d'accès. C'est à ce niveau que nous sommes redirigés vers la page d'authentification gérée par Sellsy. En échange du couple login/password, l'API renvoie un token et un secret d'accès. Il convient de les sauvegarder pour éviter à l'utilisateur d'avoir à se reconnecter à chaque utilisation de votre application.
• 3.accessApi - Une fois notre token d'accès acquis, nous pouvons requêter de l'information via la méthode requestApi de la classe sellsyConnect. Le processus est décrit dans la section suivante.

Ces étapes sont stockées via le storage de la classe sellsyTools. Dans la version de démonstration que nous vous fournissons, le stockage s'effectue en session. Libre à vous de le modifier.

Lorsque votre application est publique, vous n'avez plus rien à faire. Cependant si votre application est privée, il vous faut définir 3 paramètres dans le storage avant de commencer votre transaction. Voici comment cela peut être fait :

/*
 * init api
 */
require_once('class/sellsyconnect.php');
require_once('class/sellsytools.php');

sellsyTools::storageSet('oauth_token', '{{token_utilisateur}}');
sellsyTools::storageSet('oauth_token_secret', '{{secret_utilisateur}}');
sellsyTools::storageSet('step', '{{step}}');

/*
 * check if the user is logged
 */
sellsyConnect::load()->checkApi();

• {{token_utilisateur}} - Votre token utilisateur
• {{secret_utilisateur}} - Le secret de votre utilisateur
• {{step}} - Le step dans la séquence d'authentification OAuth. 'accessApi' dans notre cas

En définissant l'ensemble de ces paramètres, vous accédez directement au step 'accessApi' qui va vous permettre de requêter de l'information. Si vous avez une application privée et que vous essayez tout de même d'atteindre la page d'authentification, vous aurez une erreur.

Arrivé à ce niveau, vous êtes authentifié et vous pouvez commencer à faire des requêtes.

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 fournit la méthode requestApi qui permet de gérer cette étape. Voici son code :

/**
 * @desc request the api
 * @param type $requestSettings
 * @return type 
 */
public function requestApi($requestSettings, $showJSON=false) {

	try {
		if (sellsyTools::storageGet('step') == 'accessApi'){
			self::$oauth_client->setToken(
					sellsyTools::storageGet('oauth_token'), 
					sellsyTools::storageGet('oauth_token_secret'));
			self::$oauth_client->fetch(
					self::$api_url, array( 
						'request' => 1, 
						'io_mode' =>  'json', 
						'do_in' => json_encode($requestSettings)), OAUTH_HTTP_METHOD_POST);
			$back = json_decode(self::$oauth_client->getLastResponse());
			if ($showJSON){
				self::debug(self::$oauth_client->getLastResponse()); exit;
			}
			if ($back->status == 'error'){
				sellsyTools::storageSet('process_error', $back->error);
			} 
			return $back;
		}
	} catch(OAuthException $E){
		sellsyTools::storageSet('step', 'getRequestToken');
		sellsyTools::storageSet('oauth_error', self::$oauth_client->getLastResponse());
	}

}

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::load()->requestApi($request);

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 un 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