api.sellsy

Using the API with Curl

Here you will find the explanation of how the class sellsyConnect (implementing curl) you can find ici

As you have seen in the 'Getting Started' section there are two types of applications: public and private. With this class you can create only private applications. Feel free to modify it to be able to use third-party authentication and therefore create public applications.

Authentication

SellsyConnect class provides an authentication method using PHP Curl class. Here is the first part of the 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:');

	}
.
.
.

You have four parameters to replace to be able to log, and, in a second time, interact with the API.

  • {{url_api}} - Api url
  • {{user_token}} - Your user token
  • {{user_secret}} - Your user secret
  • {{consumer_token}} - Your application token
  • {{consumer_secret}} - The secret of your application

In this scenario, the authentication is direct, once you have entered their information, you are connected!

Send and receive

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

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

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 response containing 3 information:

  • response - data
  • status - request status (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.

Error management

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

  • The OAuth error message - In response you will not receive formatted data type 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 (strstr($response, 'oauth_problem')){
	sellsyTools::storageSet('oauth_error', $response);
}

if ($back->status == 'error'){
	sellsyTools::storageSet('process_error', $back->error);
} 
.
.
.
  • 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.

Your turn !

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