Information importante

Pour pouvoir communiquer avec notre API, votre client API doit supporter l‘extension TLS SNI. Plus d'informations sur notre blog.

Attention !

Cette classe utilisant OAuth pour intéragir avec l'API, OAuth doit être installé sur votre serveur.

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

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 ($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());
}
.
.
.
				
  • 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 les sections concernées.