OAuth 2.0 également disponible !

Avec la seconde version notre API, nous avons amélioré l'authentification en passant au protocole OAuth 2.0, pour unifier son application, nous avons rajouté la possibilité de se connecter à l'API Sellsy (1ère version) avec ce protocole.

La procédure de connection via OAuth 2.0 est détaillée sur la documentation de notre seconde version de l'API Sellsy


Warning !

This class use Oauth in order to communicate with the API. Oauth should be installed on your server

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

Warning

Depending on methods the parameters array and the response may vary. See the description of the methods and their answers.

Using the Sellsy API you can be faced with two types of errors:

  • OAuth error - In response you will not receive formatted data but a string (oauth_problem = {{problem}})
    oauth_problem=signature_invalid
    oauth_problem=consumer_key_refused
  • API error message - The response is JSON formatted, so you have the status in the JSON response: status: error and error: {{error_message}}
    {"response":null,"error":{"code":"E_IO_MODE_DONT_EXIST","message":"IO_MODE jsone doest not exist","more":"jsone"},"status":"error"}

SellsyConnect and sellsyTools classes provide a simple management of these errors. We can find it in the requestApi method of sellsyConnect class:

.
.
.
	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());
}
.
.
.
				
  • API errors are stored in process_error to be used later in the transaction.
  • OAuth errors are stored in oauth_error and the connection step is reset to getRequestToken. This means that the user has been disconnected.

sellsyTools class have a method to show errors ShowErrors.

You now have all the info to start developing your application. You can find all the methods, their parameters and response formats in the the relevant section.