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', ....),
//);

En anden nyttig metode, du muligvis har brug for, er calculateEndTime. Hver service kan have sin egen varighed, og dine medarbejdere har muligvis forskellige arbejdsplaner fra dag til dag. Ved hjælp af denne metode kan du vise en kunde den korrekte slutdato og -tid for den service, han har reserveret.

Kodeeksempel på beregning af bookingens sluttidspunkt

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

Når en klient klikker på knappen "Bekræft booking", skal du kalde book-metoden. Dette er den vigtigste funktion, der udfører alle nødvendige valideringer og registrerer en ny booking i Simplybook-systemet. Den tager oplysninger om bookingen, klientdata som navn og telefonnummer samt nogle yderligere parametre. Se alle parametre for denne metode i listen over API-funktioner. Book-metodens svar indeholder en unik kode og andre detaljer om den nye booking eller en liste over fejl, hvis der opstod problemer, så du kan bruge disse oplysninger til at vise bookingsresultatet til en kunde på en praktisk og intuitiv måde.

BRUG AF API-HEMMELIG NØGLE

I nogle tilfælde kan bogmetoden kræve bekræftelse, f.eks. hvis du accepterer betalinger fra kunder, bekræfter du først bookingen, når betalingen er modtaget. Simplybook API-metoden confirmBookng tager booking-id og sikker signatur som parametre (en anden metode, der kræver sikker signatur, er cancelBookng). Til generering af sikker signatur skal din hemmelige API-nøgle bruges. Se hvordan det kan gøres i eksemplet nedenfor. Du finder den hemmelige nøgle i admin-grænsefladen under linket 'Indstillinger' i API Custom Feature i listen 'Custom Features'.

Kodeeksempel på servicebooking og bekræftelse ved hjælp af hemmelig API-nøgle

$additionalFields = array(
	'6740d3bce747107ddb9a789cbb78abf3' => 'value1', 
	'b0657bafaec7a2c9800b923f959f8163' => 'value2'
);
$clientData = array(
	'name' => 'Kundens navn',
	'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æft resultat
';
	 var_dump($result);
 }
}

Kodeeksempel på hentning af indtastningsformularer

$fields = $client->getAdditionalFields($eventId);
// returnerer - array(array(
//		'name' => 'b0657bafaec7a2c9800b923f959f8163', - feltnavn
//		'title' => 'Test digits', - feltnavn
//		'type' => 'digits', - felttype
//		'values' => null, - tilgængelige værdier for valgfeltstype
//		'default' => null, - standardværdi for felt
//		'is_null' => null, - er feltet nullable
//		'on_main_page' => 1, 
//		'pos' => 1, - feltposition
//		'value' => null
// )), ...)

SIMPLYBOOK CUSTOM-FUNKTIONER

Hvis din virksomhed har behov for yderligere funktionalitet, kan du aktivere nogle af vores ekstra tilpassede funktioner. Den komplette liste over tilpassede funktioner med detaljeret beskrivelse findes i din administrationsgrænseflade under linket 'Tilpassede funktioner'. Når den nødvendige tilpassede funktion er aktiveret, aktiveres de tilhørende API-metoder, så du kan bruge dem i din kode.

KODEFLOW FOR BOOKINGFUNKTIONER

Autoriser i Simplybook API ved hjælp af funktionen loginClient.getToken(companyLogin, apiKey);.

Kontroller, om servicekategorier Custom Feature er aktiveret ved hjælp af isPluginActivated("event_category"). Hvis ja, vis listen over kategorier getCategoriesList().

Få en liste over tjenester (begivenheder) og udøvere (enheder) ved hjælp af funktionerne getEventList() og getUnitList(). Hvis arrayet "unit_map" er tilgængeligt for en tjeneste, betyder det, at denne tjeneste kun kan leveres af de angivne udøvere.

Hvis en hvilken som helst medarbejderudvælger-tilføjelsesfunktion er aktiveret isPluginActivated("any_unit") og der ikke er angivet nogen særlig varighed for serviceudbyder-parret i "unit_map"-arrayet, skal brugeren have mulighed for at vælge en hvilken som helst udbyder eller vælge udbyder manuelt. Manuel udvælgelse af udbydere bør dog ikke være mulig, hvis getCompanyParam("any_unit__hide_other_units") er aktiveret.

Brug getStartTimeMatrix ($from som aktuel dato, $to som aktuel dato, $eventId, $unitId, $count som valgt deltagerantal) for at få tilgængelige tidsintervaller for den angivne dato. $unitId skal være null, hvis indstillingen Alle medarbejdere er valgt.

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.