註冊

API Documentation 技術文件

取得授權

使用 SimplyBook.me 的 API 需要取得授權。您必須取得一組存取金鑰——即授權碼，以取得 SimplyBook.me API 中的授權。為了取得這個授權碼，您必須在 https://user-api.simplybook.me/login 服務上透過您個人的 API 金鑰，以呼叫 JSON-RPC 方法 getToken。您可以從後台管理介面上複製您的 API 金鑰，操作步驟為：到「客製化功能」的頁面，找到 API 串接客製化功能，並點擊「設定」。 接著您必須將遠端存取初始化至 SimplyBook.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
        )
    ));

從 SimplyBook.me 伺服器取得相關數據

預約網頁通常是一個讓顧客選擇他們所需的服務項目、員工，或是指定預約時間的網頁，當確認後，顧客會輸入一些聯絡資訊並確認預約。較複雜的解決方案可包含加入不同的備註欄位、做團體或週期性預約等等。您可以透過 SimplyBook.me 輕鬆打造專屬預約網頁。當然，如果您需要為您的頁面添加一些額外的功能，請查看 SimplyBook.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 模組。 這是執行所有必要的驗證和在 SimplyBook.me 系統中註冊新預約的主要功能。它需要顧客預約的資訊（如名稱、電話和一些額外的參數）。在 API 功能列表中查看此模組的所有參數說明。 而 book 模組的回應含有一組獨特的代碼以及這個新預約的其他細節，如果出現任何問題，亦會回傳錯誤的清單，所以您可使用這個資訊來以便利、直觀的方式將預約結果展示給客戶。


使用 API 密鑰

某些情況下，book 模組可能會需要確認動作。例如，如果您接受客戶的付款，則您僅在收到款項後才確認該預約。 SimplyBook.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
    // )), ...)

SimplyBook.me 提供的客製化功能

如果您的公司需要一些特定的額外功能，您可啟用我們的客製化功能。您可於管理介面的「客製化功能」頁面查看完整的客製化功能清單及具體操作方法。啟用所需的客製化功能之後，相應的 API 模組亦會啟動，讓您可以彈性使用於您的程式碼中。

預約功能的程式碼流程

在 SimplyBook.me 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 as current date, $to as current date, $eventId, $unitId, $count as selected participants value )來取得特定日期的可選擇時段。如果有選擇任何員工的選項，則 $unitId 應該會是零。


如果有啟用員工篩選器而且有選擇任何員工，則呼叫getAvailableUnits($eventId, $dateTime, $count)來取得可選擇的 $unitId。


如果有啟用備註欄位客製功能isPluginActivated('event_field')，則呼叫getAdditionalFields($eventId)功能以取得欄位清單來讓顧客填寫。


呼叫book($eventId, $unitId, $date, $time, $clientData, $additional, $count, $batchId)來做預約的動作。


為何數以千計的客戶都選擇使用 SimplyBook.me 的 API 呢？

簡單俐落的介面，輕鬆打造專屬的預約系統

輕鬆的加入所有需要的客製化功能

線上預約即時更新 - 您的顧客可以 24 小時不分日夜預約您的服務。

我們整合多種實用功能，打造專屬預約管理 App 應用，點擊這裡查看更多 相關預約管理功能。

客戶支援中心 需要協助嗎？
開發人員

保持完善的顧客體驗，讓顧客在瀏覽您的服務時，即可直接預約您提供的服務！

提供您的客戶發現在地商家時會想採取的動作，藉此讓您的網站或應用程式更加貼切、迷人、更有效益。我們的 API 讓您輕鬆在您的網頁上直接添加一個「現在預約」的按鈕，以讓您的客戶能夠不分日夜做即時預約。 我們提供一個更妥善、適切及有效的方式，讓您的顧客在瀏覽您的網站或 APP 時，能夠直接預約您的服務，不用再被引導到其他網頁來輸入資料。SimplyBook.me 提供完整的 API 串接，您可以在既有的官網中加入「立即預約」的按鈕，讓顧客隨時隨地預約您的服務。

我的的 API 提供您所需的預約數據存取權限，讓您架構並客製化合適的線上預約系統。

藉由將顧客連結至您的營業時間表，我們會創造一個全新的交易層面。我們相信直接在您的應用程式或網站上預約將允許我們提供您實際的有效顧客，而不僅是潛在顧客。