Obecnie panująca sytuacja, która ogranicza możliwości wykonywania działalności tradycyjnymi kanałami spowodowała, że część firm realizację swoich usług przeniosła do Internetu.
Coraz bardziej popularne stają się w związku z tym konsultacje oraz szkolenia i kursy online.
W związku z wieloma zapytaniami, postanowiliśmy przygotować krótką instrukcję jak można wykorzystać nasz system do zapisów online oraz integracji rezerwacji z zewnętrznymi systemami szkoleniowymi.
Odpowiednio konfigurując usługę możemy wyświetlić po stronie formularza rezerwacyjnego klasyczny wybór dnia i godziny, ale również wybór jedynie samego dnia lub dedykowanych terminów za pomocą rozwijanej listy wyboru.
Podstawowym typem usługi jest usługa stała, która pozwala na wyświetlanie dostępności w oparciu o godziny otwarcia firmy. Dodatkowo można skorzystać z usługi okresowej, która pozwala na utworzenie indywidualnego grafiku dostępności. Obie te formy po stronie formularza rezerwacyjnego pozwalają użytkownikom na wybór konkretnego dnia, a następnie godziny otrzymując w ten sposób konkretny termin realizacji usługi.
W niektórych przypadkach terminem rezerwacji jest wybór jedynie konkretnego dnia. To również możemy osiągnąć odpowiednio konfigurując formularz. Wystarczy wejść w:
Ustawienia → Wtyczka → Wyświetlaj dostępne godziny → Wybieramy „Tylko pierwszą z dostępnych” → Następne odznaczamy „Ukryj wybór godziny”
Uwaga! Należy pamiętać, że ta funkcja działa tylko we wtyczce Monthly Box.
Tym sposobem użytkownik wybiera jedynie dzień rezerwacji i bez konieczności wyboru godziny może przejść do kolejnego kroku składania rezerwacji.
Ostatnim sposobem jaki może być przydatny jest wybór konkretnego terminu rezerwacji, który wcześniej został odgórnie ustalony przez administratora systemu.
W tym celu możemy skorzystać z tzw. usługi terminowej. Pozwala ona na dodanie konkretnych terminów w jakich przewidujemy możliwość realizacji usługi.
Tak dodane terminy po stronie formularza rezerwacyjnego wyświetlają się za pomocą rozwijanej listy wyboru. Wystarczy wybrać interesujący nas termin, a dzień i godzina przypiszą się automatycznie do składanej rezerwacji.
Ten typ usługi zazwyczaj wykorzystywany do organizowania eventów doskonale sprawdzi się również w przypadku jeśli chcemy ograniczyć liczbę terminów dostępności usługi.
Całość uzupełnia możliwość podpięcia płatności online, które mogą pełnić funkcję potwierdzenia złożonej przez klienta rezerwacji i tym samym realizacji konsultacji czy szkolenia online.
Poniżej zamieściliśmy krótką instrukcję jak można wykorzystać nasz system do zapisów online oraz integracji z zewnętrznymi systemami szkoleniowymi.
Do tego celu wykorzystamy jeden z najpopularniejszych systemów do prowadzenia webinarów w Polsce - ClickMeeting.
Oczywiście poniższy tutorial pozwoli Ci zintegrować Bookero z każdym innym systemem do prowadzenia spotkań online, który posiada swoje API.
TUTORIAL
W celu zintegrowania Bookero z ClickMeeting należy zbudować aplikację pośrednią, która będzie pobierała aktualne rezerwacje z Bookero, sprawdzała status płatności, a następnie przesyłała dane zapisanego użytkownika do ClickMeeting.
Aby umożliwić komunikację, stworzymy nową klasę BookeroApi, w której wykorzystamy gotową bibliotekę od ClickMeeting. Biblioteka ta ułatwia wysyłanie zapytań do API. Znajdziemy ją tutaj: https://github.com/ClickMeeting/DevZone/tree/master/API/examples/PHP
Budowę klasy BookeroApi, zaczniemy od inicjacji potrzebnych atrybutów:
/*
* BOOKERO SETTINGS
*/
private $bookero_id = '*******';
private $api_key = '**********************************';
private $api_url = 'https://www.bookero.pl/api/web/v1/';
/*
* CLICK MEETING SETTINGS
*/
private $click_meeting_api_key = 'CLICK_MEETING_API_KEY';
- bookero_id -> ID Wtyczki Bookero, które można znaleźć w panelu w sekcji Integracje
- api_key -> Klucz API, który także jest dostępny w panelu w sekcji Integracje
- api_url -> Adres URL do API Bookero
- click_meeting_api_key -> API Key do ustanowienia połączenia z API ClickMeeting
Pierwszą metodę, którą musimy napisać, to metoda odpytująca API Bookero.
private function sendRequest(array $data, string $method) : ?stdClass{
// Przygotuj podstawowa tablice do zapytania api
$api_data = [
'bookero_id' => $this->bookero_id,
'api_key' => $this->api_key,
];
// Dodaj dodatkowe pola do zapytania
foreach($data as $key => $value){
$api_data[$key] = $value;
}
try{
// Przygotuj zapytanie POST i wysli do API
$api_url = $this->api_url.$method;
$ch = curl_init($api_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $api_data);
$response = curl_exec($ch);
curl_close($ch);
// Przygotuj obiekt ze zwroconych danych w formacie JSON
$return_data = json_decode($response);
return $return_data;
}
catch(Exception $e){
return null;
}
}
Każde zapytanie wysyłane do API Bookero musi być autoryzowane parametrami bookero_id oraz api_key. Kolejne dane, zależnie od zapytania, są dopisywane do tablicy $api_data z przekazanej jako parametr tablicy $data, która jest tablicą asocjacyjną, gdzie parujemy nazwę parametru z jego wartością.
W dalszej części metody wysyłamy zapytanie do API Bookero z wykorzystaniem cURL. Zwrócony wynik konwertujemy na obiekt JSON.
Kolejne dwie metody jakie przygotujemy, będą umożliwiały pobranie listy rezerwacji oraz pojedynczą rezerwację:
public function getItems(array $data = []) : ?stdClass{
return $this->sendRequest($data, 'inquiries/index');
}
public function getItem(int $id) : ?stdClass{
return $this->sendRequest(['id' => $id], 'inquiries/item');
}
Jak spojrzymy na metodę sendRequest, przyjmuje ona jeszcze jeden parametr $method. Jest to nazwa metody jaką chcemy wykonać przy pomocy API. W naszym przykładzie wykorzystamy dwie:
- inquiries/index -> Metoda pobiera listę rezerwacji. Możemy dodatkowo filtrować listę po dacie rozpoczęcia usługi. W tym celu do tablicy $data możemy przekazać parametry start_from oraz start_to, które określają w jakim zakresie dat chcemy znaleźć rozpoczynające się rezerwacje. Format daty jaki jest wymagany to YYYY-mm-dd. Zwrócone dane są podzielone na strony po 20 elementów. W celu pobrania kolejnej strony wyników, należy przesyłać parametr page, gdzie jako wartość przypisujemy numer strony, którą chcemy pozyskać.
- inquiries/item -> Metoda pobiera szczegóły konkretnej rezerwacji. W tym przypadku do tablicy przekazujemy tylko jedną wartość - $id rezerwacji.
Ostatnia metoda, jaką wykonamy w naszej klasie, będzie służyła do zapisania użytkownika do pokoju webinarium w ClickMeeting:
public function registerClickMeetingUser(array $data, int $room_id) : ?stdClass{
try{
// Utworz nowa instancje Rest API ClickMeeting
$clickMeetingApi = new ClickMeetingRestClient(['api_key' => $this->click_meeting_api_key]);
// Zarejestruj nowego usera do wybranego pokoju
$registration = $clickMeetingApi->addConferenceRegistration($room_id, $data);
}
catch(Exception $e){
return null;
}
return $registration;
}
W tej metodzie tworzymy nowy obiekt helpera do komunikacji z API ClickMeeting, który został wspomniany wyżej. Do konstruktora musimy podać tablicę z kluczem API. Następnie wykonujemy metodę addConferenceRegistration, gdzie jako parametry podajemy ID pokoju webinarium oraz tablicę z danymi uczestnika. Przykład tablicy poniżej:
$data = [
'registration' => [
1 => 'Imię',
2 => 'Nazwisko',
3 => 'Adres e-mail',
],
];
Mamy już wszystkie metody, których potrzebujemy. Możemy teraz przekazywać użytkowników, którzy zapisali się na webinarium w Bookero oraz opłacili uczestnictwo do ClickMeeting.
Jak może wyglądać skrypt wykorzystujący utworzoną klasę? Poniżej przykład:
require_once('classes/ClickMeetingRestClient.php');
require_once('classes/BookeroApi.php');
$bookero = new BookeroApi();
$room_id = 0; // ID POKOJU CLICK MEETING
$inquiries = $bookero->getItems([
'page' => 1, // Strona wynikow listy rezerwacji
'start_from' => date('Y-m-d')
]);
foreach($inquiries as $inquiry){
$is_inquiry_sync = false;
/*
* ---- KOD DO UZUPEŁNIENIA ----
* SPRAWDZ CZY inquiry->id istnieje już w tabeli z rejestracjami uzytkownikow
* Jesli rezerwacja zostala juz zarejestrowana w click meeting ustaw na true. Jesli nie, zostaw false
*
*/
// Sprawdzamy czy rezerwacja jest opłacona
if($is_inquiry_sync === false){
if(isset($inquiry->payment->status) && $inquiry->payment->status == 'COMPLETED'){
$name = explode(' ', $inquiry->name);
$data = [
'registration' => [
1 => $name[0],
2 => isset($name[1]) ? $name[1] : '',
3 => $inquiry->email,
],
];
$registration = $bookero->registerClickMeetingUser($data, $room_id);
if(is_object($registration) && isset($registration->status) && $registration->status == "OK"){
/*
* ---- KOD DO UZUPEŁNIENIA ----
* DODAJ DO TABELI Z REJESTRACJAMI $inquiry->id jako rezerwacja, która została przesłana do clickmeeting
*/
}
}
}
}
Przeanalizujmy zasadę działania skryptu od samej góry. W pierwszej kolejności pobieramy wszystkie przyszłe rezerwacje.
Następnie przechodząc przez wszystkie rezerwacje, sprawdzamy czy dana rezerwacja została już zintegrowana z ClickMeeting. W tym celu, najlepiej jest stworzyć jakąś tabelę w bazie danych, która będzie przechowywała ID rezerwacji, które zostały poprawnie przekazane do ClickMeeting. Kod weryfikujący powinien zostać umieszczony w miejscu, gdzie wskazuje na to komentarz:
/*
* ---- KOD DO UZUPEŁNIENIA ----
* SPRAWDZ CZY inquiry->id istnieje już w tabeli z rejestracjami uzytkownikow
* Jesli rezerwacja zostala juz zarejestrowana w click meeting ustaw na true. Jesli nie, zostaw false
*
*/
Następnie jeśli rezerwacja jeszcze nie była przekazana do ClickMeeting, sprawdzamy czy rezerwacja ma płatność oraz czy płatność została zakończona. Jeśli tak, przygotowujemy dane do przesłania do ClickMeeting, po czym wykonujemy metodę registerClickMeetingUser. ClickMeeting, jeśli wszystko pójdzie ok, zwraca obiekt, który posiada atrybut status z wartością równą „OK”. Po otrzymaniu takiego komunikatu powinniśmy dodać do tablicy zintegrowanych rezerwacji kolejny wpis.
Zwróć też uwagę na poniższą część kodu:
$name = explode(' ', $inquiry->name);
$data = [
'registration' => [
1 => $name[0],
2 => isset($name[1]) ? $name[1] : '',
3 => $inquiry->email,
],
];
ClickMeeting wymaga osobnych pól na imię i nazwisko. Bookero przechowuje te dane w jednym polu. Musimy zatem rozbić wartość name z Bookero na dwie wartości. Wykorzystujemy tutaj metodę explode i rozbijamy ciąg znaków po spacji. W ten sposób powinna powstać tablica z dwoma elementami, gdzie imię jest pierwszym elementem, nazwisko zaś drugim.
To wszystko co musimy wykonać w ramach integracji. Mamy nadzieję, że powyższy tutorial pozwoli Ci zintegrować Bookero nie tylko z ClickMeeting ale także z każdym innym systemem do prowadzenia spotkań online, który posiada swoje API.
