User API guide/uk

Використовуйте наш API для розробників, щоб створити власний інтерфейс бронювання. Ви можете розробити будь-яке рішення, від найпростішого віджета до багатофункціонального додатка з функціоналом, налаштованим відповідно до специфіки вашого бізнесу.

Інтерфейс програмування додатків Simplybook використовує протокол JSON-RPC 2.0.

Перегляньте приклад інтерфейсу бронювання на основі API, а також ознайомтеся з вихідним кодом цього рішення.

АВТОРИЗАЦІЯ

Для використання методів Simplybook API необхідна автентифікація. Для авторизації в Simplybook API вам потрібно отримати ключ доступу — access-token. Щоб отримати цей access-token, ви повинні викликати метод JSON-RPC getToken на сервісі https://user-api.simplybook.me/login, передавши свій особистий API-ключ. Ви можете скопіювати свій API-ключ в адміністративному інтерфейсі: перейдіть за посиланням «Custom Features» (Налаштування) і виберіть «API Custom Feature» (Налаштування API). Потім потрібно ініціювати віддалений доступ до Simplybook API. Ваш запит повинен містити такі заголовки: «X-Company-Login», «X-Token».

Отримання токена доступу можна реалізувати як з боку клієнта, так і з боку вашого сервера, що є більш безпечним рішенням.

Ви можете використовувати бібліотеку javascript JSON-RPC-client та бібліотеку php JSON-RPC-client з наших прикладів для розробки власних рішень.

Зверніть увагу, що токен доступу діє протягом однієї години. Це зроблено з міркувань безпеки. Вам потрібно буде поновлювати його щонайменше раз на годину.

CLIENT API (ADMIN) АВТОРИЗАЦІЯ

Авторизація з боку клієнта

Отримання токен-ключа.

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

Ініціалізація JSON-RPC-клієнта.

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

Авторизація з боку сервера

Отримання токен-ключа.

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

Ініціалізація JSON-RPC-клієнта.

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

АВТОРИЗАЦІЯ API КОРИСТУВАЧА/АДМІНІСТРАТОРА (СЛУЖБА АДМІНІСТРУВАННЯ КОМПАНІЇ

Авторизація з боку клієнта

Отримання токен-ключа.

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

Ініціалізація JSON-RPC-клієнта.

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

Авторизація з боку серверного коду

Отримання токен-ключа.

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

Ініціалізація JSON-RPC-клієнта.

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

ОТРИМАННЯ ДАНИХ З СЕРВЕРА SIMPLYBOOK

Сторінка бронювання зазвичай є сторінкою, на якій клієнти вибирають необхідну послугу, співробітника та час зустрічі. Потім клієнт вводить контактну інформацію та підтверджує бронювання. Більш складні рішення можуть включати заповнення різних форм, створення групових або багаторазових бронювань тощо. Опишемо робочий процес створення найпростішої сторінки бронювання. Якщо вам потрібно додати додаткові функції на свою сторінку, перегляньте повний список методів API Simplybook.

Отже, перше, що ви повинні відобразити, це список послуг та список співробітників. Отримайте ці дані за допомогою методів getEventList та getUnitList. Обидва вони повертають список з повною інформацією про кожен елемент, що міститься в ньому, тому у вас є багато можливостей для відображення послуг та співробітників на вашій сторінці. Щоб здійснити фільтрацію співробітників, використовуйте властивість unit_map списку послуг, яка містить інформацію про співробітників, які можуть надати вибрану послугу.

Приклад коду для отримання списку послуг

$services = $client->getEventList();
// повертає масив(array(
//     'id' => 1, - ідентифікатор послуги
//     'name' => 'Service 1', - назва послуги
//     'description' => 'Опишіть свою послугу...', - опис послуги
//     'duration' => 60, - тривалість послуги
//     'hide_duration' => 0, - прапорець приховування тривалості від клієнтів,
//     'picture' => null, - ім'я файлу зображення або null
//     'picture_path' => '/uploads/apidemo/event__picture/small/', - повний шлях до зображення,
//     'position' => 1 - позиція послуги
//     'is_active' => 1, - послуга активована
//     'is_public' => 1, - послуга доступна для бронювання клієнтами
// ), ...)

Приклад коду для отримання списку виконавців послуг

$services = $client->getUnitList();
// повертає масив (array(
//    'id' => 1, - ідентифікатор виконавця
//    'name' => 'Provider 1', - ім'я виконавця
//    'phone' => '111111111', - номер телефону виконавця
//    'description' => 'Опишіть свого виконавця...', - опис виконавця
//    'email' => 'test@gmail.com', - електронна адреса виконавця,
//    'is_active' => 1, - виконавець активований
//    'is_visible' => 1, - виконавець видимий для клієнтів,
//    'picture' => null, - ім'я файлу зображення або null,
//    'picure_path' => '/uploads/apidemo/unit_group__picture/small/', - повний шлях до зображення
//    'position' => 1, - позиція виконавця
//    'qty' => 1, кількість виконавців
// ), ...)

Наступним кроком для клієнта є вибір дати та часу надання послуги. У прикладі використання API ми використовували календар Bootstrap, але ви можете використовувати цей або будь-який інший календар. Щоб встановити першу дату календаря, скористайтеся методом getFirstWorkingDay. Він може приймати ідентифікатор співробітника як параметр і повертає наступну дату, коли вибраний співробітник (або будь-який співробітник компанії за замовчуванням) доступний для бронювання. Щоб показати часові слоти в межах вибраної дати, вам потрібні методи getWorkCalendar і getStartTimeMatrix. Перший метод надає інформацію про початок і кінець робочого дня, а також про вихідні дні. Другий метод повертає список часових слотів, які можна забронювати на певну дату.

Приклад коду для отримання інформації про робочі дні

$year = 2015;
$month = 3; // березень
$performerId = 1; // може бути нульовим 
$workDaysInfo = $client->getWorkCalendar($year, $month, $performerId);				
// повертає масив (
//     '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),
//     ...
//);

Приклад коду для отримання матриці часу початку

$dateFrom = '2015-03-03';
$dateTo = '2015-03-04';
$serviceId = 1;
$performerId = 1;
$qty = 1;
$availableTime = $client->getStartTimeMatrix($dateFrom, $dateTo, $serviceId, $performerId, $qty);
// повертає масив (
//     '2015-03-03' => array('09:00:00', '09:30:00', '10:00:00', ....),
//     '2015-03-04' => масив('09:00:00', '09:30:00', '10:00:00', ....),
//);

Інший корисний метод, який може вам знадобитися, — calculateEndTime. Кожна послуга може мати свою тривалість, а також співробітники вашої компанії можуть мати різний графік роботи в різні дні. Тож за допомогою цього методу ви можете правильно показати клієнту дату та час закінчення послуги, яку він забронював.

Приклад коду для розрахунку часу закінчення бронювання

$startDateTime = '2015-03-03 09:00:00';
$serviceId = 1;
$performerId = 1;
$availableTime = $client->calculateEndTime($startDateTime, $serviceId, $performerId);
// повертає '2015-03-03 10:00:00'

Коли клієнт натискає кнопку «Підтвердити бронювання», ви повинні викликати метод book. Це основна функція, яка виконує всі необхідні перевірки та реєструє нове бронювання в системі Simplybook. Вона бере інформацію про бронювання, дані клієнта, такі як ім'я та телефон, а також деякі додаткові параметри. Дивіться опис всіх параметрів цього методу в списку функцій API. Відповідь методу book містить унікальний код та інші деталі нового бронювання або список помилок, якщо виникли проблеми, тому ви можете використовувати цю інформацію, щоб показати результат бронювання клієнту в зручний та інтуїтивно зрозумілий спосіб.

ВИКОРИСТАННЯ СЕКРЕТНОГО КЛЮЧА API

У деяких випадках метод бронювання може вимагати підтвердження, наприклад, якщо ви приймаєте платежі від клієнтів, ви підтверджуєте бронювання тільки після того, як платіж вже надійшов. Метод Simplybook API confirmBookng приймає ідентифікатор бронювання та безпечний підпис як параметри (інший метод, який вимагає безпечного підпису, - cancelBookng). Для генерації безпечного підпису слід використовувати ваш секретний ключ API. Дивіться, як це можна зробити, у прикладі нижче. Секретний ключ можна знайти в адміністративному інтерфейсі за посиланням «Налаштування» в розділі «Налаштування API» у списку «Налаштування».

Приклад коду бронювання послуги та її підтвердження за допомогою секретного API-ключа

$additionalFields = array(
	'6740d3bce747107ddb9a789cbb78abf3' => 'value1', 
	'b0657bafaec7a2c9800b923f959f8163' => 'value2'
);
$clientData = array(
	'name' => 'Ім'я клієнта',
	'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 '
Confirm result
';
	 var_dump($result);
 }
}

Приклад коду для отримання форм для введення даних

$fields = $client->getAdditionalFields($eventId);
// повертає - масив(масив(
//		'name' => 'b0657bafaec7a2c9800b923f959f8163', - назва поля
//		'title' => 'Test digits', - назва поля
//		'type' => 'digits', - тип поля
//		'values' => null, - доступні значення для поля типу select
//		'default' => null, - значення за замовчуванням для поля
//		'is_null' => null, - чи поле може бути нульовим
//		'on_main_page' => 1, 
//		'pos' => 1, - позиція поля
//		'value' => null
// )), ...)

ПЕРСОНАЛЬНІ ФУНКЦІЇ SIMPLYBOOK

Якщо ваша компанія потребує додаткових функцій, ви можете активувати деякі з наших додаткових функцій. Повний перелік функцій з докладним описом доступний в адміністративному інтерфейсі за посиланням «Custom Feature» (Додаткові функції). Після увімкнення необхідної функції будуть активовані відповідні методи API, які ви зможете використовувати у своєму коді.

ФУНКЦІОНАЛЬНІСТЬ БРОНЮВАННЯ КОДОВИЙ ПОТІК

Авторизуйтесь в Simplybook API за допомогою функції loginClient.getToken(companyLogin, apiKey);.

Перевірте, чи активована функція «Категорії послуг» за допомогою isPluginActivated("event_category"). Якщо так, то відобразіть список категорій getCategoriesList().

Отримати список послуг (подій) та виконавців (одиниць) за допомогою функцій getEventList() та getUnitList(). Якщо для послуги доступний масив "unit_map", це означає, що ця послуга може бути надана тільки зазначеними виконавцями.

Якщо активовано будь-яку спеціальну функцію вибору співробітника isPluginActivated("any_unit") і в масиві "unit_map" не встановлено спеціальний термін для пари "послуга-виконавець", то користувачеві слід дозволити вибрати будь-який варіант постачальника або вибрати постачальника вручну. Але ручний вибір виконавців не повинен бути можливим, якщо активовано getCompanyParam("any_unit__hide_other_units").

Використовуйте getStartTimeMatrix ($from як поточну дату, $to як поточну дату, $eventId, $unitId, $count як значення вибраних учасників), щоб отримати доступні часові слоти для заданої дати. $unitId повинен бути нульовим, якщо вибрано опцію «Будь-який співробітник».

Якщо активний селектор «Будь-який співробітник» і було вибрано будь-якого співробітника, викличте getAvailableUnits($eventId, $dateTime, $count), щоб отримати доступний $unitId

Якщо активована функція «Налаштування форм для нових клієнтів», викличте функцію isPluginActivated("event_field") getAdditionalFields($eventId), щоб отримати список полів, які клієнт повинен заповнити.

Викличте книгу ($eventId, $unitId, $date, $time, $clientData, $additional, $count, $batchId), щоб зробити бронювання.