User API guide/da

Brug vores udvikler-API til at oprette din egen bookinggrænseflade. Du kan designe enhver løsning, du ønsker, lige fra den enkleste widget til multifunktionelle applikationer med funktionalitet, der er tilpasset din virksomheds specifikke behov.

Simplybook Application Programming Interface bruger JSON-RPC 2.0-protokollen.

Se et eksempel på en API-baseret bookinggrænseflade, og læs også kildekoden til denne løsning.

AUTORISATION

Brug af Simplybook API-metoder kræver godkendelse. For at godkende i Simplybook API skal du få en adgangsnøgle — adgangstoken. For at få denne adgangstoken skal du kalde JSON-RPC-metoden getToken på https://user-api.simplybook.me/login service og indtaste din personlige API-nøgle. Du kan kopiere din API-nøgle i admin-grænsefladen: gå til linket 'Custom Features' og vælg API Custom Feature 'Settings'. Derefter skal du initialisere fjernadgang til Simplybook API. Din anmodning skal indeholde følgende headere: 'X-Company-Login', 'X-Token'.

Adgangstoken kan implementeres enten fra klientsiden eller fra din server, hvilket er den mest sikre løsning.

Du kan bruge javascript JSON-RPC-klientbibliotek og php JSON-RPC-klientbibliotek fra vores eksempler til udvikling af din egen løsning.

Bemærk, at adgangstokenet er gyldigt i én time. Dette er af sikkerhedsmæssige årsager. Du skal genoprette det mindst én gang i timen.

KLIENT-API (OFFENTLIG TJENESTE) AUTORISATION

Autorisation fra klientens kode

Hent token-nøglen.

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

Initialisering af JSON-RPC-klient.

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

Autorisation fra serverkode

Hentning af token-nøglen.

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

Initialisering af JSON-RPC-klient.

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

BRUGER/ADMIN API (VIRKSOMHEDSADMINISTRATIONSTJENESTE) AUTORISATION

Autorisation fra klientens kode

Hent token-nøglen.

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

Initialisering af JSON-RPC-klient.

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

Autorisation fra serversiden

Hent token-nøglen.

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

Initialisering af JSON-RPC-klient.

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

HENTNING AF DATA FRA SIMPLYBOOK-SERVEREN

En reservationsside er normalt en side, hvor kunder vælger den service, de har brug for, en medarbejder og et tidspunkt for deres møde. Derefter indtaster kunden nogle kontaktoplysninger og bekræfter reservationen. De mere komplekse løsninger kan omfatte udfyldelse af forskellige indtastningsformularer, oprettelse af gruppe- eller flergangsreservationer osv. Lad os beskrive arbejdsgangen for oprettelse af den enkleste reservationsside. Hvis du derefter har brug for at tilføje ekstra funktionalitet til din side, kan du se den fulde liste over Simplybook API-metoder her.

Så det første, du skal vise, er listen over tjenester og listen over medarbejdere. Hent disse data ved hjælp af metoderne getEventList og getUnitList. De returnerer begge en liste med komplette oplysninger om hvert element i listen, så du har mange muligheder for at vise tjenester og medarbejdere på din side. For at filtrere medarbejdere skal du bruge egenskaben unit_map i tjenestelisten, som indeholder oplysninger om medarbejdere, der kan levere den valgte tjeneste.

Kodeeksempel på hentning af serviceliste

$services = $client->getEventList();
// returnerer array(array(
//     'id' => 1, - service-id
//     'name' => 'Service 1', - servicens navn
//     'description' => 'Beskriv din service...', - servicebeskrivelse
//     'duration' => 60, - servicens varighed
//     'hide_duration' => 0, - Skjul varighed for klienter flag,
//     'picture' => null, - filnavn på billede eller null
//     'picture_path' => '/uploads/apidemo/event__picture/small/', - fuld sti til billede,
//     'position' => 1 - serviceposition
//     'is_active' => 1, - tjenesten er aktiveret
//     'is_public' => 1, - tjenesten kan bookes af klienter
// ), ...)

Kodeeksempel på hentning af liste over tjenesteudbydere

$services = $client->getUnitList();
// returnerer array(array(
//    'id' => 1, - udbyder-id
//    'name' => 'Udbyder 1', - udbyderens navn
//    'phone' => '111111111', - udbyderens telefonnummer
//    'description' => 'Beskriv din udbyder...', - udbyderens beskrivelse
//    'email' => 'test@gmail.com', - udbyderens e-mail,
//    'is_active' => 1, - udbyderen er aktiveret
//    'is_visible' => 1, - udøveren er synlig for kunder,
//    'picture' => null, - filnavn på billede eller null,
//    'picure_path' => '/uploads/apidemo/unit_group__picture/small/', - fuld sti til billede
//    'position' => 1, - udøverens position
//    'qty' => 1, antal udøvere
// ), ...)

Det næste trin for en kunde er at vælge en dato og et tidspunkt for sin service. Vi har brugt en Bootstrap-datovælger i API-brugseksemplet, men du kan også bruge denne eller en anden kalender. For at indstille din kalenders første dato skal du bruge metoden getFirstWorkingDay. Den kan tage medarbejder-id som parameter og returnerer den næste dato, hvor den valgte medarbejder (eller en hvilken som helst medarbejder i virksomheden som standard) er tilgængelig for booking. For at vise tidsintervaller inden for en valgt dato skal du bruge metoderne getWorkCalendar og getStartTimeMatrix. Den første metode giver dig oplysninger om arbejdsdagens start- og sluttidspunkt samt om fridage. Den anden returnerer listen over tidsintervaller, der kan bookes for en bestemt dato.

Kodeeksempel på hentning af oplysninger om arbejdsdage

$år = 2015;
$måned = 3; // marts
$performerId = 1; // Kan være null 
$workDaysInfo = $client->getWorkCalendar($år, $måned, $performerId);				
// returnerer array(
//     '2015-03-01' => array('fra' => '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),
//     ...
//);

Kodeeksempel på hentning af starttidsmatrix

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