Using the API with OAuth

Here you will find the explanation of how thesellsyConnect class (implementing OAuth). You can download it here

This class allows you to create private and public applications.

As you have seen in the 'Getting Started' there are two types of applications: public and private. The two types of applications connect in the same way.

SellsyConnect class provides a method of authentication via OAuth PHP class. Here is the first part of the 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());
		}
	}

}

As you can see, you have to replace four parameters to be able to log in, and, in a second time, interact with the API.

• {{url_api}} - Api url
• {{token}} - Consumer token (your application)
• {{secret}} - The secret of your application
• {{oauth_callback}} - The callback url after the user login in into the login page

Authentication is done via the checkApi method. The connection process is divided into several steps:

• 1.getRequestToken - In this step, we see if we have a token request. If not, we then ask one to the API. Attention, a request token is valid only for 5 minutes.
• 2.getAccessToken - Once we have a request token, we will ask to convert it to access token. At this level we are redirected to the login page managed by Sellsy. In exchange for the login / password, the API returns an access token and secret. You should save it to avoid the user having to reconnect every time you use your application.
• 3.accessApi - Once we retrieved the access token, we can start querying information via the requestApi method from the sellsyConnect class. The process is described in the next section.

These steps are stored via the storage of sellsyTools class. In the demo we provide, the storage is done in session. Feel free to edit it.

When your application is public, you have nothing more to do. However, if your application is private, you must set three parameters in storage before you begin your transaction. Here's how it can be done:

/*
 * 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}} - Your user token
• {{secret_utilisateur}} - Your user secret
• {{step}} - The step in the OAuth authentication sequence. 'accessApi 'in our case

When all these settings are defined, you directly access the 'accessApi' step which will allow you to query information. If you have a private application and still try to reach the login page, you will get an error.

At this level, you are authenticated and you can start making requests.

Once connected, ie when you have your access token / secret, you can call the API methods. sellsyConnect class provides the requestApi method to manage this step. Here is the 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());
	}

}

This function takes an array as parameter that will define which API method we want to use and with what parameters. Here's, for example, how to retrieve a list of customers with pagination and a search parameter:

$requestSettings = array(
	'method' => 'Client.getList',
	'params' => array(
		'search' => array(
			'contains' => 'TESTDOCUMENTATION',
		),
		'pagination' => array (
			'pagenum'	=> 1,
			'nbperpage'	=> 10
		)
	)
);

$clientsListing = sellsyConnect::load()->requestApi($request);

In response you will receive a response encoded wit the IO_mode that you specified. For example:

{"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"}

You receive a JSON containing 3 information:

• response - data
• status - the status of our request (success / error)
• error - the error message if there is one