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 (ДЕРЖАВНА СЛУЖБА) АВТОРИЗАЦІЯ

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

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

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

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.