User API guide/sv

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; // mars
$performerId = 1; // Kan vara null 
$workDaysInfo = $client->getWorkCalendar($year, $month, $performerId);				
// returnerar 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),
//     ...
//);

Kodexempel för att hämta starttidsmatris

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

En annan användbar metod som du kan behöva är calculateEndTime. Varje tjänst kan ha sin egen varaktighet, och dina anställda kan ha olika arbetsscheman från dag till dag. Med den här metoden kan du visa en kund slutdatum och sluttid för den tjänst han eller hon har bokat på ett korrekt sätt.

Kodexempel för beräkning av bokningens sluttid

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

När en kund klickar på knappen Bekräfta bokning måste du anropa metoden book. Detta är huvudfunktionen som utför alla nödvändiga valideringar och registrerar en ny bokning i Simplybook-systemet. Den tar information om bokningen, kunddata som namn och telefonnummer samt några ytterligare parametrar. Se alla parametrarbeskrivningar för denna metod i listan över API-funktioner. Svaret från bokningsmetoden innehåller en unik kod och andra detaljer om den nya bokningen eller en lista över fel om några problem har uppstått, så att du kan använda denna information för att visa bokningsresultatet för kunden på ett bekvämt och intuitivt sätt.

ANVÄNDNING AV API-HEMLIG NYCKEL

I vissa fall kan bokningsmetoden kräva bekräftelse, t.ex. om du accepterar betalningar från kunder bekräftar du bokningen först efter att betalningen har kommit in. Simplybook API:s bekräftelsemetod tar boknings-id och säker signatur som parametrar (en annan metod som kräver säker signatur är cancelBookng). För att generera en säker signatur måste du använda din hemliga API-nyckel. Se hur det går till i exemplet nedan. Du hittar den hemliga nyckeln i admin-gränssnittet under länken "Inställningar" i API-anpassade funktioner i listan "Anpassade funktioner".

Kodexempel på bokning av tjänst och bekräftelse med hjälp av hemlig API-nyckel

$additionalFields = array(
	'6740d3bce747107ddb9a789cbb78abf3' => 'value1', 
	'b0657bafaec7a2c9800b923f959f8163' => 'value2'
);
$clientData = array(
	'name' => 'Kundnamn',
	'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 '
Bekräfta resultat
';
	 var_dump($result);
 }
}

Kodexempel för att hämta intagsformulär

$fields = $client->getAdditionalFields($eventId);
// returnerar - array(array(
//		'name' => 'b0657bafaec7a2c9800b923f959f8163', - fältnamn
//		'title' => 'Test digits', - fälttitel
//		'type' => 'digits', - fälttyp
//		'values' => null, - tillgängliga värden för fält av typ select
//		'default' => null, - standardvärde för fält
//		'is_null' => null, - kan fältet vara tomt
//		'on_main_page' => 1, 
//		'pos' => 1, - fältets position
//		'value' => null
// )), ...)

SIMPLYBOOK ANPASSADE FUNKTIONER

Om ditt företag behöver ytterligare funktioner kan du aktivera några av våra extra anpassade funktioner. En komplett lista över anpassade funktioner med detaljerade beskrivningar finns i administratörsgränssnittet under länken "Anpassade funktioner". När den önskade anpassade funktionen har aktiverats aktiveras motsvarande API-metoder så att du kan använda dem i din kod.

KODFLÖDE FÖR BOKNINGSFUNKTIONER

Auktorisera i Simplybook API med funktionen loginClient.getToken(companyLogin, apiKey);.

Kontrollera om tjänstekategorierna Anpassad funktion är aktiverade med isPluginActivated("event_category"). Om ja, visa listan över kategorier med getCategoriesList().

Hämta en lista över tjänster (evenemang) och utförare (enheter) med hjälp av funktionerna getEventList() och getUnitList(). Om arrayen "unit_map" är tillgänglig för en tjänst betyder det att denna tjänst endast kan tillhandahållas av angivna utförare.

Om någon anpassad funktion för val av anställd är aktiverad isPluginActivated("any_unit") och ingen särskild varaktighet är angiven för paret tjänsteleverantör-tjänsteutförare i matrisen "unit_map", ska användaren kunna välja alternativet Valfri leverantör eller välja leverantör manuellt. Manuell val av tjänsteutförare ska dock inte vara möjligt om getCompanyParam("any_unit__hide_other_units") är aktiverat.

Använd getStartTimeMatrix ($from som aktuellt datum, $to som aktuellt datum, $eventId, $unitId, $count som valt deltagarantal) för att få tillgängliga tidsluckor för ett visst datum. $unitId ska vara null om alternativet Alla anställda är valt.

Om valet "Alla anställda" är aktivt och någon anställd har valts, anropa getAvailableUnits($eventId, $dateTime, $count) för att hämta tillgängliga $unitId

Om den anpassade funktionen Intake Forms är aktiverad, anropa isPluginActivated("event_field") och funktionen getAdditionalFields($eventId) för att hämta listan över fält som kunden ska fylla i.

Ring bokning($eventId, $unitId, $date, $time, $clientData, $additional, $count, $batchId) för att göra en bokning.