User API guide/nl

Gebruik onze ontwikkelaars-API om uw eigen boekingsinterface te maken. U kunt elke gewenste oplossing ontwerpen, van de eenvoudigste widget tot een multifunctionele applicatie met functionaliteit die is aangepast aan uw bedrijfsspecifieke behoeften.

De applicatieprogrammeerinterface van Simplybook maakt gebruik van het JSON-RPC 2.0-protocol.

Bekijk een voorbeeld van een API-gebaseerde boekingsinterface en lees ook de broncode van deze oplossing.

AUTORISATIE

Voor het gebruik van Simplybook API-methoden is authenticatie vereist. Om autorisatie te verkrijgen in Simplybook API, moet u een toegangssleutel (access-token) aanvragen. Om deze access-token te verkrijgen, moet u de JSON-RPC-methode getToken aanroepen op https://user-api.simplybook.me/login service en uw persoonlijke API-sleutel doorgeven. U kunt uw API-sleutel kopiëren in de beheerdersinterface: ga naar de link 'Aangepaste functies' en selecteer API-aangepaste functie 'Instellingen'. Vervolgens moet u externe toegang tot de Simplybook API initialiseren. Uw verzoek moet de volgende headers bevatten: 'X-Company-Login', 'X-Token'.

Het verkrijgen van de toegangstoken kan worden geïmplementeerd vanaf de client of vanaf uw server, wat de veiligere oplossing is.

U kunt de JavaScript JSON-RPC-clientbibliotheek en de PHP JSON-RPC-clientbibliotheek uit onze voorbeelden gebruiken voor het ontwikkelen van uw eigen oplossing.

Houd er rekening mee dat de toegangstoken één uur geldig is. Dit is om veiligheidsredenen. U moet deze minstens één keer per uur opnieuw genereren.

CLIENT API (OPENBARE DIENST VAN HET BEDRIJF) AUTORISATIE

Autorisatie vanuit de code van de klant

De token-sleutel ophalen.

var loginClient = new JSONRpcClient({
	'url': 'https://user-api.simplybook.me' + '/login',
	'onerror': function (error) {},
});
var token = loginClient.getToken(YOUR_COMPANY_LOGIN, YOUR_API_KEY);

Initialisatie JSON-RPC-client.

this.client = new JSONRpcClient({
	'url': 'https://user-api.simplybook.me',
	'headers': {
		'X-Company-Login': YOUR_COMPANY_LOGIN,
		'X-Token': token
	},
	'onerror': function (error) {}
});

Autorisatie vanuit de servercode

De token-sleutel ophalen.

$loginClient = new JsonRpcClient('https://user-api.simplybook.me' . '/login/');
$token = $loginClient->getToken(YOUR_COMPANY_LOGIN, YOUR_API_KEY);

Initialisatie JSON-RPC-client.

$client = new JsonRpcClient('https://user-api.simplybook.me' . '/', array(
   'headers' => array(
       'X-Company-Login: ' . YOUR_COMPANY_LOGIN,
       'X-Token: ' . $token
   )
));

GEBRUIKER/BEHEERDER API (BEDRIJFSBEHEERDIENST) AUTORISATIE

Autorisatie vanuit de code van de klant

De token-sleutel ophalen.

var loginClient = new JSONRpcClient({
'url': 'https://user-api.simplybook.me' + '/login',
'onerror': function (error) {},
});
var token = loginClient.getUserToken(YOUR_COMPANY_LOGIN, YOUR_USER_LOGIN, YOUR_USER_PASSWORD);

Initialisatie JSON-RPC-client.

this.client = new JSONRpcClient({
'url': 'https://user-api.simplybook.me' + '/admin/',
'headers': {
'X-Company-Login': YOUR_COMPANY_LOGIN,
'X-User-Token': token
},
'onerror': function (error) {}
});

Autorisatie vanuit de servercode

De token-sleutel ophalen.

$loginClient = new JsonRpcClient('https://user-api.simplybook.me' . '/login/');
$token = $loginClient->getUserToken(YOUR_COMPANY_LOGIN, YOUR_USER_LOGIN, YOUR_USER_PASSWORD);

Initialisatie JSON-RPC-client.

$client = new JsonRpcClient('https://user-api.simplybook.me' . '/admin/', array(
'headers' => array(
'X-Company-Login: ' . YOUR_COMPANY_LOGIN,
'X-User-Token: ' . $token
)
));

GEGEVENS OPVRAGEN VAN DE SIMPLYBOOK-SERVER

Een boekingspagina is meestal een pagina waar klanten de gewenste dienst, een medewerker en een tijdstip voor hun afspraak kiezen. Vervolgens vult de klant enkele contactgegevens in en bevestigt hij de boeking. Complexere oplossingen kunnen het invullen van verschillende intakeformulieren, het maken van groeps- of meervoudige boekingen enzovoort omvatten. Laten we de workflow voor het maken van de eenvoudigste boekingspagina beschrijven. Als u vervolgens extra functionaliteit aan uw pagina wilt toevoegen, vindt u hier de volledige lijst met Simplybook API-methoden.

Het eerste wat u dus moet weergeven, is de lijst met diensten en de lijst met werknemers. Haal deze gegevens op met de methoden getEventList en getUnitList. Beide methoden retourneren een lijst met volledige informatie over elk item in de lijst, zodat u veel mogelijkheden hebt om diensten en werknemers op uw pagina weer te geven. Om werknemers te filteren, gebruikt u de eigenschap unit_map van de dienstenlijst. Deze bevat informatie over werknemers die de geselecteerde dienst kunnen leveren.

Code example of getting services list

$services = $client->getEventList();
// returns array(array(
//     'id' => 1, - service id
//     'name' => 'Service 1', - service's name
//     'description' => 'Describe your service...', - service description
//     'duration' => 60, - service duration
//     'hide_duration' => 0, - Hide duration to clients flag,
//     'picture' => null, - file name of picture or null
//     'picture_path' => '/uploads/apidemo/event__picture/small/', - full path to picture,
//     'position' => 1 - service position
//     'is_active' => 1, - the service is activated
//     'is_public' => 1, - the service is allowed to book by clients
// ), ...)

Code example of getting service performers list

$services = $client->getUnitList();
// returns array(array(
//    'id' => 1, - performer id
//    'name' => 'Provider 1', - performer name
//    'phone' => '111111111', - perfomer phone number
//    'description' => 'Describe your performer...', - performer description
//    'email' => 'test@gmail.com', - perfomer email,
//    'is_active' => 1, - the performer is activated
//    'is_visible' => 1, - the perfomer is visible for clients,
//    'picture' => null, - file name of picture or null,
//    'picure_path' => '/uploads/apidemo/unit_group__picture/small/', - full path to picture
//    'position' => 1, - performer position
//    'qty' => 1, performer quantity
// ), ...)

The next step to a client is to pick a date and time of his service. We've used a Bootstrap date-picker in API-usage example, you can also use this or any other calendar. To set your calendar first date use getFirstWorkingDay method. It can take employee id as a parameter and returns the next date when the selected employee (or any employee in the company by default) is avaiable for booking. To show time slots inside a selected date you need getWorkCalendar and getStartTimeMatrix methods. The first method give you an information about working day start and end time, and about day-offs. And the second one returns the list of time-slots which can be booked for a certain date.

Code example of getting work days info

$year = 2015; $month = 3; // March $performerId = 1; // Can be null $workDaysInfo = $client->getWorkCalendar($year, $month, $performerId); // returns array( // '2015-03-01' => array('from' => '09:00:00', 'to' => '18:00:00', 'is_day_off' => 0), // '2015-03-02' => array('from' => '09:00:00', 'to' => '18:00:00', 'is_day_off' => 0), // ... //);

Code example of getting start time matrix

$dateFrom = '2015-03-03';
$dateTo = '2015-03-04';
$serviceId = 1;
$performerId = 1;
$qty = 1;
$availableTime = $client->getStartTimeMatrix($dateFrom, $dateTo, $serviceId, $performerId, $qty);
// returns array(
//     '2015-03-03' => array('09:00:00', '09:30:00', '10:00:00', ....),
//     '2015-03-04' => array('09:00:00', '09:30:00', '10:00:00', ....),
//);

Another usefull method you may need is calculateEndTime. Each service can have its own duration, also your company's employees possible have different work schedule form day to day. So using this method you can show to a client an end date and time of the service he've booked in a correct way.

Code example of calculating booking end time

$startDateTime = '2015-03-03 09:00:00';
$serviceId = 1;
$performerId = 1;
$availableTime = $client->calculateEndTime($startDateTime, $serviceId, $performerId);
// returns '2015-03-03 10:00:00'

When a client clicks confirm booking button you have to call book method. This is the main function which performs all necessary validations and registers a new booking in Simplybook system. It takes information about booking, client data like name and phone and some additional params. See all params descriptions of this method in API functions list. The book method responce contains an uniqe code and other details of the new booking or the list of errors if some problems occured, so you can use this information to show booking result to a client in convinient and intuitive way.

USING OF API SECRET KEY

In some cases the book method may require the confirmation, e.g. if your accept payments from clients you confirm booking only after the payment is already came. The Simplybook API confirmBookng method takes booking-id and secure signature as params (another method which requires secure signature is cancelBookng). For the secure signature generation your secret API-key should be used. See how it can be done in the example below. You can find the secret key at admin interface under 'Settings' link of API Custom Feature in 'Custom Features' list.

Code example of service booking and its confirmation using secret API key

$additionalFields = array(
	'6740d3bce747107ddb9a789cbb78abf3' => 'value1', 
	'b0657bafaec7a2c9800b923f959f8163' => 'value2'
);
$clientData = array(
	'name' => 'Client name',
	'email' => 'client@email.com',
	'phone' => '+13152108338'
);
		
$bookingsInfo = $client->book($eventId, $unitId, $date, $time, $clientData, $additionalFields);
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
if ($bookingsInfo->require_confirm) {
   foreach ($bookingsInfo->bookings as $booking) {
	   $sign = md5($booking->id . $booking->hash . YOUR_API_SECRET_KEY);
	   $result = $client->confirmBooking($booking->id, $sign);
	   echo '
Confirm result
';
	   var_dump($result);
    }
}

Code example of getting intake forms

$fields = $client->getAdditionalFields($eventId);
// returns - array(array(
//		'name' => 'b0657bafaec7a2c9800b923f959f8163', - field name
//		'title' => 'Test digits', - field title
//		'type' => 'digits', - field type
//		'values' => null, - available values for select field type
//		'default' => null, - default value for field
//		'is_null' => null, - is filed nullable
//		'on_main_page' => 1, 
//		'pos' => 1, - field position
//		'value' => null
// )), ...)

SIMPLYBOOK CUSTOM FEATURES

If your company specific requires some additional functionality you can activate some of our additional Custom Features. The complete Custom Features list with detailed description is avaiable in your admin interface under the 'Custom Feature' link. After the necessary Custom Feature is enabled the corresponding API methods will be activated so you can use them in your code.

BOOKING FUNCTIONALITY CODEFLOW

Authorize in Simplybook API using loginClient.getToken(companyLogin, apiKey); function.

Check if Service categories Custom Feature is activated by isPluginActivated("event_category") if yes then display list of categories getCategoriesList().

Get list of services (events) and performers (units) using getEventList() and getUnitList() functions. If "unit_map" array is available for service it means this service can be provided by given performers only.

If Any Employee Selector Custom Feature is activated isPluginActivated("any_unit") and no special duration is set for service-performer pair in "unit_map" array then user should be allowed to select Any provider option or choose provider manually. But manual selection of performers should not be possible if getCompanyParam("any_unit__hide_other_units") is enabled.

Use getStartTimeMatrix ($from as current date, $to as current date, $eventId, $unitId, $count as selected participants value ) to get available timeslots for given date. $unitId should be null if Any employee option is selected.

If Any Employee selector is active and Any employee was selected call getAvailableUnits($eventId, $dateTime, $count) to get available $unitId

If Intake Forms Custom Feature is activated isPluginActivated("event_field") call getAdditionalFields($eventId) function to get list of fields for client to fill.

Call book($eventId, $unitId, $date, $time, $clientData, $additional, $count, $batchId) to make a booking.