注册

API Documentation 技术文件

使用我们的开发人员 API 来创建您自己的预约界面。从最简单的小部件到多功能的应用程序，您可依据您特定的业务来客制任何的解决方案。

SimplyВook.me 应用程序界面（API）使用的是 JSON-RPC 2.0 协定。

看看以 API 架设的预约界面之范例，并且查看这个解决方案的程序代码。

授权

Simplybook API methods require an authentication. To authorize in Simplybook API you need to get an access key — access-token. In order to get this access-token you should call the JSON-RPC method getToken on http://user-api.simplybook.me/login service passing your personal API-key. You can copy your API-key at admin interface: go to the 'Plugins' link and select API plugin 'Settings'. 接着您必须将远程访问初始化至 SimplyВook.me API。您的请求应包含下面标题：'X-Company-Login', 'X-Token'。

授权码的取得可由客户端或由您的服务器来执行，然而后者是两者中较安全的解决方案。

您可使用我们的范例中的 javascript JSON-RPC-客户端链接库与 php JSON-RPC-客户端链接库来开发您自己的解决方案。


客户端 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);

Initialization JSON-RPC-client


    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': {$api_url} + '/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
        )
    ));

从 SimplyВook.me 服务器取得数据

预约页面通常是一个让客户选择他们所需的服务、员工，以及他们的会议时间的页面。客户会接着输入一些联络信息并确认预约。较复杂的解决方案可包含填入不同的额外字段、做团体或多次预约等等。让我们描述一下创建最简单的预约页面之工作流程。然后，如果您需要为您的页面添加一些额外的功能，则请参阅这里的 SimplyВook.me API 方法之完整列表。

所以您应展示的第一项信息为服务列表及员工列表，使用 getEventList 及 getUnitList 方法来取得这个数据。两者皆会回传一个清单，内含其中每项对象的完整信息，所以您会有许多可能性来选择如何在您的页面上展示服务与员工。欲做员工筛选，使用服务清单的 unit_map 性能，其含有可以提供所选服务之员工的信息。

取得服务列表的范例代码


    $services = $client->getEventList();
    // returns array(array(
    //     'id' => 1, - service id
    //     'name' => 'Service 1', - service's name
    //     'description' => 'Describe your service...', - service description
    //     'duration' => 60, - service duration
    //     'hide_duration' => 0, - Hide duration to clients flag,
    //     'picture' => null, - file name of picture or null
    //     'picture_path' => '/uploads/apidemo/event__picture/small/', - full path to picture,
    //     'position' => 1 - service position
    //     'is_active' => 1, - the service is activated
    //     'is_public' => 1, - the service is allowed to book by clients
    // ), ...)

取得服务执行者列表的范例代码


    $services = $client->getUnitList();
    // returns array(array(
    //    'id' => 1, - performer id
    //    'name' => 'Provider 1', - performer name
    //    'phone' => '111111111', - perfomer phone number
    //    'description' => 'Describe your performer...', - performer description
    //    'email' => 'test@gmail.com', - perfomer email,
    //    'is_active' => 1, - the performer is activated
    //    'is_visible' => 1, - the perfomer is visible for clients,
    //    'picture' => null, - file name of picture or null,
    //    'picure_path' => '/uploads/apidemo/unit_group__picture/small/', - full path to picture
    //    'position' => 1, - performer position
    //    'qty' => 1, performer quantity
    // ), ...)

客户的下一步是选择想要的服务日期与时间。我们在 API 使用范例中使用了一个 Bootstrap 日期选择器，您可以使用之或是任何其他的日历。 欲设定您日历的第一天，使用 getFirstWorkingDay 方法。其可用员工 ID 作为参数并回传所选员工（预设则为任何员工）可做预约的下一天之日期。{""|t} 欲显示所选日期中的时段，您需要 getWorkCalendar 及 getStartTimeMatrix 方法。第一个方法给您工作日的开始及结束时间以及休息日的信息，第二个方法则回传一个特定日期中可预约的时段之清单。

取得工作日信息的范例代码


    $year = 2020;
    $month = 3; // March
    $performerId = 1; // Can be null
    $workDaysInfo = $client->getWorkCalendar($year, $month, $performerId);
    // returns array(
    //     '2020-03-01' => array('from' => '09:00:00', 'to' => '18:00:00', 'is_day_off' => 0),
    //     '2020-03-02' => array('from' => '09:00:00', 'to' => '18:00:00', 'is_day_off' => 0),
    //     ...
    //);

取得开始时间矩阵的范例代码


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

另一个您可能会需要的实用方法为 calculateEndTime。每个服务皆可有自己的服务时间长度，您的员工每天亦可能有不同的工作时段。使用这个方法，您就可以为客户正确地显示其所预约的服务之结束日期与时间。

计算预约结束时间的范例代码


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

当一位客户点击确认预约的按钮时，您必须呼叫 book 方法。 这是执行所有必要的验证和在 SimplyВook.me 系统中注册新预约的主要功能。它需要与预约及客户数据（如名称、电话和一些额外的参数）相关的信息。在 API 功能列表中查看此方法的所有参数说明。 本 book 方法的回应含有一组独特的代码以及这个新预约的其他细节，如果出现任何问题，亦会回传错误的清单，所以您可使用这个信息来以便利、直观的方式将预约结果展示给客户。


使用 API 密钥

某些情况下，book 方法可能会需要确认动作。例如，如果您接受客户的付款，则您仅在收到款项后才确认该预约。 SimplyВook.me API 的 confirmBookng 方法搜集预约 ID 以及安全签名以作为参数。（cancelBookng 是另一个需要安全签名的方法。） 您必需使用您的 API 密钥来产生安全签名。欲知如何完成这个动作，请见下面的范例。您可开启管里界面的「客制功能」页面，然后从 API 客制功能的「设定」内取得这组密钥。

服务预约以及使用 API 密钥来确认之范例代码


    $additionalFields = array(
	'6740d3bce747107ddb9a789cbb78abf3' => 'value1',
	'b0657bafaec7a2c9800b923f959f8163' => 'value2'
    );

    $clientData = array(
        'name' => 'Client 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 '<br>Confirm result</b><br />';
           var_dump($result);
        }
    }

取得额外字段的范例代码


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

SimplyВook.me 客制功能

如果您的公司需要一些特定的额外功能，您可启用一些我们的额外客制功能。您可于管理界面的「客制功能」页面查看完整的客制功能列表及详细描述。启用所需的客制功能之后，相应的 API 方法亦会启动，供您使用于您的代码中。

预约功能代码流

在 SimplyВook.me API 中使用 loginClient.getToken(companyLogin, apiKey); 功能来授权。


Check if Service categories plugin 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 plugin 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 Additional fields plugin 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.


为何数以千计的客户都选择使用 SimplyВook.me API 呢？

简单利落的界面，轻松打造您自己的预约服务。

您可轻易地置入所有您需要的功能。

实时排程——您的客户能够天天 24 小时随时随地与您预约。

我们集成多种实用功能，打造专属预约管理 App 应用，点击这里查看更多 相关预约管理功能。

支持中心 需要协助吗？
开发人员

让您的客户不用离开您的应用程序就能预约服务！

提供您的客户发现在地商家时会想采取的动作，藉此让您的网站或应用程序更加贴切、迷人、更有效益。我们的 API 让您轻松在您的网页上直接添加一个「现在预约」的按钮，以让您的客户能够不分日夜做实时预约。

我们的 API 提供您所有需要的预约数据之访问权限，让您架构并配置适合您的客户群之预约功能。

藉由将客户连结至您的营业时间表，我们会创造一个全新的交易层面。我们相信直接在您的应用程序或网站上预约将允许我们提供您实际的有效客户，而不仅是潜在客户。