API Documentation

Introduction

At PlanSo we try to be as open as possible to other systems. We therefore created a set of API methods external applications can interact with.

In this page we’ll provide details to the most used methods and how to connect to our API.

To make your life easier you can use our base API class to get a head start when developing with php. You can download this class via the following link: class.planso.api.zip

Authentication

To authenticate against our API we provide our users with a custom 128bit API Key and a 128bit API password. Users can strengthen the password using a custom salt string to further improve the security when dealing with the API. In order for a successful API connect and as an added security measure you also need your company token. So please have all three credentials handy before you start.

Making your first API call

The PlanSo API is accessed via the following url:

https://[COMPANYTOKEN].planso.de/api/v2/[METHOD]

When posting to that url you’ll have to set the following headers:

Apikey: [YOUR-PERSONAL-API-KEY]
Apipass: [YOUR-PERSONAL-API-PASSWORD]

Sending these headers can easily be accomplished using curl for example. To submit a simple API call you can use the method methods_table_list_tables as it does not require any further parameters. The full coll to this method would look like:

Request URL:https://[COMPANYTOKEN].planso.de/api/v2/methods_table_list_tables
Request Headers
	Apikey: [YOUR-PERSONAL-API-KEY]
	Apipass: [YOUR-PERSONAL-API-PASSWORD]

The above request will return a JSON object containing all tables available for the instance beeing called.

Putting it in action

The following curl request scheme shows how to use the api directly:

curl -d "[PARAMETERS]" -X POST "https://[TOKEN].planso.de/api/v2/[METHOD]" -H "Apikey: [APIKEY]" -H "Apipass: [APIPASS]"

And the following line will serve the same result as the php example above:

curl -X POST "https://[token].planso.de/api/v2/methods_table_list_tables" -H "Apikey: [APIKEY]" -H "Apipass: [APIPASS]"

Example code

The following PHP Code represents the example above using our API Class.

<?php

$planso_api_parameters = array(
	'apikey' => 'YOUR-API-KEY',
	'apipass' => 'YOUR-API-PASSWORD',
	'token' => 'YOUR-COMPANYTOKEN',
	'method' => 'methods_table_list_field',
	'parameter' => array(
		'tableID' => 1,
		'fieldID' => 1
	)
);
require_once('/PATH-TO-YOUR/class.planso.api.php');

$api = new PlanSo_Api();
$api->parameters = $planso_api_parameters;

$r = $api->call();
if($r['success']){
	echo '<h1>Successful API call</h1>';
	exit( $r['response'] );
} else {
	echo '<h1>Unsuccessful API call</h1>';
	exit( $r['response'] );
}
?>

Methods

The following methods are currentyl open to developers. This list will be constantly extended and information provided here will likely change over time. We will not change the methods themselves however.

Table, field and data manipulation methods

Method: methods_table_list_tables

Parameter: -

This method returns a JSON object containing all tables available.

[
{
“ID”:”201″,
“name”:”Table name”,
“description”:”Some description”,
“help”:””
},
{
“ID”:”226″,
“name”:”Second Table Name”,
“description”:””,
“help”:””
}
]

Method: methods_table_list_fields

Parameter: tableID

Lists all fields contained in the table specified by tableID and returns a JSON object containing all fields with all field details.

[
{
“table_name”:”Salutations”,
“table_description”:””,
“table_help”:””,
“rights_table_view”:”1″,
“rights_row_add”:”1″,
“rights_row_archive”:”0″,
“rights_row_del”:”0″,
“ID”:”1″,
“companyID”:”1″,
“name”:”Salutation”,
“label”:”Salutation”,
“description”:””,
“help”:””,
“fieldset”:null,
“type”:”text”,
“datatype”:”varchar”,
“dataformat”:”0″,
“ismulti”:”0″,
“txtformat”:”0″,
“dataunit”:””,
“minlength”:”0″,
“maxlength”:”25″,
“realprecision”:”0″,
“default_value”:””,
“relation”:”0″,
“jsondata”:null,
“required”:”0″,
“isunique”:”0″,
“inputtemplate”:null,
“viewtemplate”:null,
“rights_add”:”null”,
“rights_archive”:”0″,
“rights_del”:”0″,
“rights_edit”:”1″,
“rights_view”:”0″,
“online”:”1″
},
{

}

]

Method: methods_table_list_field

Parameter: tableID, fieldName | fieldID

Returns a JSON object containing the details of the field specified by fieldName or fieldID. The field identifier has to match the tableID i.e. the field has to be a sibling of the table specified.

[
{
“table_name”:”Salutations”,
“table_description”:””,
“table_help”:””,
“rights_table_view”:”1″,
“rights_row_add”:”1″,
“rights_row_archive”:”0″,
“rights_row_del”:”0″,
“ID”:”1″,
“companyID”:”1″,
“name”:”Salutation”,
“label”:”Salutation”,
“description”:””,
“help”:””,
“fieldset”:null,
“type”:”text”,
“datatype”:”varchar”,
“dataformat”:”0″,
“ismulti”:”0″,
“txtformat”:”0″,
“dataunit”:””,
“minlength”:”0″,
“maxlength”:”25″,
“realprecision”:”0″,
“default_value”:””,
“relation”:”0″,
“jsondata”:null,
“required”:”0″,
“isunique”:”0″,
“inputtemplate”:null,
“viewtemplate”:null,
“rights_add”:”null”,
“rights_archive”:”0″,
“rights_del”:”0″,
“rights_edit”:”1″,
“rights_view”:”0″,
“online”:”1″
}
]

Method: methods_table_create_field

Parameter: tableID, name, [label, description, help, fieldset, type, datatype, dataformat, ismulti, txtformat, dataunit, minlength, maxlength, realprecision, default_value, relation, jsondata, required, isunique, inputtemplate, viewtemplate, rights_add, rights_archive, rights_del, rights_edit, rights_view, online]

Creates a new field within tableID

{
“fieldID” : 1,
“fieldName” “specified name”
}

Method: methods_table_create_table

Parameter: name, [description, parentID, rights_table_view, rights_row_add, rights_row_archive, rights_row_del, online]

Creates a new table

{
“tableID” : 1
}

Method: methods_table_save_table_data

Parameter: tableID, oper=add|update,id=_empty|int, at least one field name

This method lets you manipulate a dataset within a table. Depending on the 'oper' parameter this method either adds (add) or updates (update) one row. If you use oper you need to specify the id with a valid integer id of the row you'd like to update. In both cases you need to pass additional parameter value pairs for each field that you'd like to update.

{
“rowID” : 1
}

Method: return_table_data

Parameter: tableID, _search, rows, page, sidx, sort

This method returns data from any table. Using parameters ``rows`` for the number of results to return and ``page`` for the page to be displayed (starting with 1) you can realize paginated results. ``sidx`` contains the sorting column. By default this will be ``ID``. ``sort`` allows you to define the result order. And ``_search`` can contain a search object to find any result.

{
“ID” : 1,
“col1”:…
“col2”:…
}

Method: methods_table_create_menu

Parameter: name,tableID

Create a new menu item linking to the table specified by tableID

{
“menuID” : 1
}

Serviceplanner methods

Method: serviceplanner_check_date_for_availability

Parameter: date=2015-12-31|31.12.2015, duration=00:30:00

Returns JSON object with available time slots of duration on selected date

{
“by_section”:{
“1”:[
{
“label”:”Section name”,
“section_id”:”1″,
“start_date”:”2015-03-09 09:40:00″,
“available_time”:”00:50″,
“available_time_seconds”:”3000″,
“end_date”:”2015-03-09 10:30:00″
}
]
},
“combined”:[
{
“label”:”Section name”,
“section_id”:”1″,
“start_date”:”2015-03-09 09:40:00″,
“available_time”:”00:50″,
“available_time_seconds”:”3000″,
“end_date”:”2015-03-09 10:30:00″
}
],
“execution_time”:0.48928308486938
}