Gebruikershandleiding API

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.

Codevoorbeeld voor het ophalen van de lijst met services

$services = $client->getEventList();
// retourneert array(array(
//     'id' => 1, - service-id
//     'name' => 'Service 1', - naam van de service
//     'description' => 'Beschrijf uw service...', - beschrijving van de service
//     'duration' => 60, - duur van de service
//     'hide_duration' => 0, - vlag om duur voor klanten te verbergen,
//     'picture' => null, - bestandsnaam van de afbeelding of null
//     'picture_path' => '/uploads/apidemo/event__picture/small/', - volledig pad naar afbeelding,
//     'position' => 1 - positie van dienst
//     'is_active' => 1, - de dienst is geactiveerd
//     'is_public' => 1, - de dienst kan door klanten worden geboekt
// ), ...)

Codevoorbeeld voor het ophalen van een lijst met dienstverleners

$services = $client->getUnitList();
// retourneert array(array(
//    'id' => 1, - id van de dienstverlener
//    'name' => 'Provider 1', - naam van de uitvoerder
//    'phone' => '111111111', - telefoonnummer van de uitvoerder
//    'description' => 'Beschrijf uw uitvoerder...', - beschrijving van de uitvoerder
//    'email' => 'test@gmail.com', - e-mailadres van de uitvoerder,
//    'is_active' => 1, - de uitvoerder is geactiveerd
//    'is_visible' => 1, - de artiest is zichtbaar voor klanten,
//    'picture' => null, - bestandsnaam van foto of null,
//    'picure_path' => '/uploads/apidemo/unit_group__picture/small/', - volledig pad naar foto
//    'position' => 1, - positie van artiest
//    'qty' => 1, aantal artiesten
// ), ...)

De volgende stap voor een klant is het kiezen van een datum en tijdstip voor zijn dienst. We hebben een Bootstrap-datumkiezer gebruikt in het API-gebruikvoorbeeld, maar u kunt ook deze of een andere kalender gebruiken. Om de eerste datum van uw kalender in te stellen, gebruikt u de methode getFirstWorkingDay. Deze methode kan het werknemers-id als parameter gebruiken en geeft de volgende datum terug waarop de geselecteerde werknemer (of standaard alle werknemers in het bedrijf) beschikbaar is voor boeking. Om tijdvakken binnen een geselecteerde datum weer te geven, hebt u de methoden getWorkCalendar en getStartTimeMatrix nodig. De eerste methode geeft u informatie over de begin- en eindtijd van de werkdag en over vrije dagen. De tweede methode retourneert de lijst met tijdvakken die voor een bepaalde datum kunnen worden geboekt.

Codevoorbeeld voor het ophalen van informatie over werkdagen

$jaar = 2015;
$maand = 3; // maart
$artiestId = 1; // kan null zijn 
$werkdagenInfo = $client->getWorkCalendar($jaar, $maand, $artiestId);				
// retourneert array(
//     '2015-03-01' => array('van' => '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),
//     ...
//);

Codevoorbeeld voor het ophalen van de starttijdmatrix

$dateFrom = '2015-03-03';
$dateTo = '2015-03-04';
$serviceId = 1;
$performerId = 1;
$qty = 1;
$availableTime = $client->getStartTimeMatrix($dateFrom, $dateTo, $serviceId, $performerId, $qty);
// retourneert 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', ....),
//);

Een andere handige methode die u wellicht nodig hebt, is calculateEndTime. Elke dienst kan een eigen duur hebben, en ook de werknemers van uw bedrijf kunnen van dag tot dag verschillende werktijden hebben. Met deze methode kunt u een klant op de juiste manier de einddatum en -tijd van de door hem geboekte dienst tonen.

Codevoorbeeld voor het berekenen van de eindtijd van een boeking

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

Wanneer een klant op de knop 'Boeking bevestigen' klikt, moet u de methode 'book' aanroepen. Dit is de belangrijkste functie die alle noodzakelijke validaties uitvoert en een nieuwe boeking registreert in het Simplybook-systeem. Deze functie verzamelt informatie over de boeking, klantgegevens zoals naam en telefoonnummer en enkele aanvullende parameters. Zie alle parameterbeschrijvingen van deze methode in de lijst met API-functies. Het antwoord van de boekingsmethode bevat een unieke code en andere details van de nieuwe boeking of een lijst met fouten als er problemen zijn opgetreden, zodat u deze informatie kunt gebruiken om het boekingsresultaat op een handige en intuïtieve manier aan een klant te tonen.

GEBRUIK VAN API SECRET KEY

In sommige gevallen kan de boekingsmethode om bevestiging vragen, bijvoorbeeld als u betalingen van klanten accepteert en u de boeking pas bevestigt nadat de betaling is ontvangen. De Simplybook API-methode confirmBookng gebruikt het boekingsnummer en een beveiligde handtekening als parameters (een andere methode die een beveiligde handtekening vereist is cancelBookng). Voor het genereren van een beveiligde handtekening moet u uw geheime API-sleutel gebruiken. Zie het onderstaande voorbeeld voor hoe u dit kunt doen. U vindt de geheime sleutel in de beheerdersinterface onder de link 'Instellingen' van API Custom Feature in de lijst 'Custom Features'.

Codevoorbeeld van het boeken van een dienst en de bevestiging daarvan met behulp van een geheime API-sleutel

$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);

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.