Användar-API-guide

Använd vårt utvecklings-API för att skapa ditt eget bokningsgränssnitt. Du kan utforma vilken lösning du vill, från den enklaste widgeten till en multifunktionell applikation med funktioner anpassade efter just ditt företag.

Simplybook Application Programming Interface använder JSON-RPC 2.0-protokollet.

Se ett exempel på ett API-baserat bokningsgränssnitt och läs även källkoden för denna lösning.

AUKTORISERING

Användning av Simplybook API-metoder kräver autentisering. För att auktorisera i Simplybook API måste du skaffa en åtkomstnyckel – access-token. För att få denna access-token måste du anropa JSON-RPC-metoden getToken på https://user-api.simplybook.me/login service och ange din personliga API-nyckel. Du kan kopiera din API-nyckel i admin-gränssnittet: gå till länken "Anpassade funktioner" och välj API-anpassad funktion "Inställningar". Sedan måste du initiera fjärråtkomst till Simplybook API. Din begäran ska innehålla följande rubriker: "X-Company-Login", "X-Token".

Åtkomsttoken kan implementeras antingen från klientsidan eller från din server, vilket är den säkrare lösningen.

Du kan använda javascript JSON-RPC-klientbibliotek och php JSON-RPC-klientbibliotek från våra exempel för att utveckla egna lösningar.

Observera att åtkomsttoken är giltigt i en timme. Detta görs av säkerhetsskäl. Du måste generera det på nytt minst en gång per timme.

KLIENT-API (FÖRETAGETS OFFENTLIGA TJÄNST) AUTORISERING

Auktorisering från klientens kod

Hämta token-nyckeln.

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 av JSON-RPC-klient.

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

Auktorisering från serverns kod

Hämta token-nyckeln.

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

Initialisering av JSON-RPC-klient.

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

ANVÄNDARE/ADMIN API (FÖRETAGSADMINISTRATIONSTJÄNST) AUTORISATION

Auktorisering från klientens kod

Hämta token-nyckeln.

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

Auktorisering från serverns kod

Hämta token-nyckeln.

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

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

HÄMTA DATA FRÅN SIMPLYBOOK-SERVER

En bokningssida är vanligtvis en sida där kunder väljer den tjänst de behöver, en anställd och en tid för sitt möte. Därefter anger kunden sina kontaktuppgifter och bekräftar bokningen. Mer komplexa lösningar kan innefatta ifyllande av olika intagsformulär, gruppbokningar, bokningar av flera tider och så vidare. Låt oss beskriva arbetsflödet för att skapa den enklaste bokningssidan. Om du sedan behöver lägga till ytterligare funktioner till din sida hittar du en fullständig lista över Simplybook API-metoder här.

Det första du bör visa är listan över tjänster och listan över anställda. Hämta dessa data med metoderna getEventList och getUnitList. Båda returnerar en lista med fullständig information om varje objekt i listan, så du har många möjligheter att visa tjänster och anställda på din sida. För att filtrera anställda använder du egenskapen unit_map i tjänstelistan, som innehåller information om anställda som kan tillhandahålla den valda tjänsten.

Kodexempel för att hämta tjänstelistan

$services = $client->getEventList();
// returnerar array(array(
//     'id' => 1, - tjänst-id
//     'name' => 'Service 1', - tjänstens namn
//     'description' => 'Beskriv din tjänst...', - tjänstens beskrivning
//     'duration' => 60, - tjänstens varaktighet
//     'hide_duration' => 0, - flagga för att dölja varaktighet för kunder,
//     'picture' => null, - filnamn på bild eller null
//     'picture_path' => '/uploads/apidemo/event__picture/small/', - fullständig sökväg till bild,
//     'position' => 1 - tjänstens position
//     'is_active' => 1, - tjänsten är aktiverad
//     'is_public' => 1, - tjänsten får bokas av kunder
// ), ...)

Kodexempel för att hämta en lista över tjänsteleverantörer

$services = $client->getUnitList();
// returnerar array(array(
//    'id' => 1, - leverantörs-id
//    'name' => 'Provider 1', - utförarens namn
//    'phone' => '111111111', - utförarens telefonnummer
//    'description' => 'Beskriv din utförare...', - beskrivning av utföraren
//    'email' => 'test@gmail.com', - utförarens e-postadress,
//    'is_active' => 1, - utföraren är aktiv
//    'is_visible' => 1, - artisten är synlig för kunder,
//    'picture' => null, - filnamn på bild eller null,
//    'picure_path' => '/uploads/apidemo/unit_group__picture/small/', - fullständig sökväg till bild
//    'position' => 1, - artistens position
//    'qty' => 1, antal artister
// ), ...)

Nästa steg för en kund är att välja datum och tid för sin tjänst. Vi har använt en Bootstrap-datumväljare i API-användningsexemplet, men du kan också använda denna eller någon annan kalender. För att ställa in första datum i kalendern använder du metoden getFirstWorkingDay. Den kan ta anställd-id som parameter och returnerar nästa datum när den valda anställda (eller någon anställd i företaget som standard) är tillgänglig för bokning. För att visa tidsluckor inom ett valt datum behöver du metoderna getWorkCalendar och getStartTimeMatrix. Den första metoden ger dig information om arbetsdagens start- och sluttid samt om lediga dagar. Den andra returnerar en lista över tidsluckor som kan bokas för ett visst datum.

Kodexempel för att hämta information om arbetsdagar

$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.