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

Codevoorbeeld voor het ophalen van intakeformulieren

$fields = $client->getAdditionalFields($eventId);
// retourneert - array(array(
//		'name' => 'b0657bafaec7a2c9800b923f959f8163', - veldnaam
//		'title' => 'Test digits', - veldtitel
//		'type' => 'digits', - veldtype
//		'values' => null, - beschikbare waarden voor select veldtype
//		'default' => null, - standaardwaarde voor veld
//		'is_null' => null, - is veld nullable
//		'on_main_page' => 1, 
//		'pos' => 1, - veldpositie
//		'value' => null
// )), ...)

AANGEPASTE FUNCTIES VAN SIMPLYBOOK

Als uw bedrijf specifieke extra functionaliteit nodig heeft, kunt u enkele van onze extra aangepaste functies activeren. De volledige lijst met aangepaste functies met een gedetailleerde beschrijving is beschikbaar in uw beheerdersinterface onder de link 'Aangepaste functies'. Nadat de benodigde aangepaste functie is ingeschakeld, worden de bijbehorende API-methoden geactiveerd, zodat u ze in uw code kunt gebruiken.

BOEKINGSFUNCTIONALITEIT CODEFLOW

Autoriseer in Simplybook API met behulp van de functie loginClient.getToken(companyLogin, apiKey);.

Controleer of de aangepaste functie Servicecategorieën is geactiveerd door isPluginActivated("event_category"). Zo ja, geef dan de lijst met categorieën weer met getCategoriesList().

Haal een lijst met diensten (evenementen) en uitvoerders (eenheden) op met behulp van de functies getEventList() en getUnitList(). Als de array "unit_map" beschikbaar is voor een dienst, betekent dit dat deze dienst alleen door de opgegeven uitvoerders kan worden geleverd.

Als de aangepaste functie 'Any Employee Selector' is geactiveerd (isPluginActivated("any_unit")) en er geen speciale duur is ingesteld voor de combinatie van dienstverlener en uitvoerder in de array 'unit_map', dan moet de gebruiker de optie 'Any provider' kunnen selecteren of de dienstverlener handmatig kunnen kiezen. Handmatige selectie van uitvoerders mag echter niet mogelijk zijn als getCompanyParam("any_unit__hide_other_units") is ingeschakeld.

Gebruik getStartTimeMatrix ($from als huidige datum, $to als huidige datum, $eventId, $unitId, $count als waarde voor geselecteerde deelnemers) om beschikbare tijdvakken voor een bepaalde datum op te halen. $unitId moet null zijn als de optie Alle medewerkers is geselecteerd.

Als de selectie 'Any Employee' actief is en een werknemer is geselecteerd, roep dan getAvailableUnits($eventId, $dateTime, $count) aan om de beschikbare $unitId op te halen

Als de aangepaste functie voor intakeformulieren is geactiveerd, roep dan isPluginActivated("event_field") de functie getAdditionalFields($eventId) aan om de lijst met velden op te halen die de klant moet invullen.

Roep boek($eventId, $unitId, $date, $time, $clientData, $additional, $count, $batchId) aan om een boeking te maken.