In addition to other available integration methods, the Lock.me system also offers integration after the API.

    Who is this article aimed at?

    This article is aimed at technical people looking to integrate with Lockme themselves. If you don't know what the API is, check out articles on other forms of integration:

    Before you get started

    • Your account must have partner privileges.
    • The documentation for the new Lockme API is based on the OAuth2 security protocol.
    • Lockme API Documentation.
    • You can use the following library to make your work easier: Lockme PHP SDK.
    • NOTE: Authorization and OAuth calls are not yet functional in this documentation.

    What operations are possible within the API?

    The operations that we currently provide through our API are:

    • managing reservations (viewing, adding, editing, deleting, moving) - important: reservations paid via lockme cannot be deleted from the API.
    • handling webhook messages (downloading, marking as handled).
    • viewing departments and rooms.
    • management of weekly room settings (viewing, editing).
    • managing room calendar exceptions (viewing, adding, editing, deleting).

    What are the requirements of our library and how to install it?

    You can find the current details of our SDK here > https://packagist.org/packages/lustmored/lockme-sdk

    It requires PHP version 7.2 minimum to work (we recommend at least 8.1 - requirements may change in future versions!). To install it, use Composer (https://getcomposer.org) and the command:

    composer require lustmored/lockme-sdk
    

    What is a redirect URI?

    Redirect URI is the address to which the user will be redirected when connecting to the application (after accepting the data transfer). This parameter also has an authorization function when connecting to the API. Therefore, its value must be consistent with the one defined in the panel. In the absence of a user-based authorization mechanism, and using only tokens, the value of this parameter should remain the default and be configured accordingly on the client side as well.

    How to create API applications?

    1. Go to the Lock.me Cockpit (your account must have partner privileges).
    2. Go to "Reservations" > "API applications."
    3. In the upper right corner, click "Add."
    4. Then select a partner.
    5. Enter the internal name of the application (e.g. My Application 1).
    6. Enter the URI of the redirect.
    7. Click "Add."

    image

    How do our webhooks work?

    • Our webhooks send 3 types of events to defined addresses. These are add, edit and delete bookings. Each message on the webhook contains an X-MessageId header, which contains the ID of the message.
    • In order to serve the message, it must be retrieved (endpoint: GET /message/{messageid} in the API), and once served, it must be marked as read (POST /message/{messageid}).
    • In case the message is not marked as read, it will be resent a few times, at increasing intervals.
    • Each message contains the event metadata (room ID, reservation and action type - add/edit/delete) and reservation data from the time the message was generated.
    • For detailed information on webhooks, see the article > https://lock.me/en/docs/article/webhooks-configuration

    Example of connection code using our SDK

    The following code snippet requires a created API application and a token, generated from the panel. To handle full OAuth2 user authentication, we encourage you to read the documentation here > https://oauth2-client.thephpleague.com/ (our SDK runs on the league/oauth2-client library).

    In order to maintain the continuity of the connection, callbacks that read and write the token (in this case to the token.json file) should be passed to the loadAccessToken method. IMPORTANT: Remember that the token should not be placed on the server in a publicly accessible location.

    <?php
    
    use Lockme\SDK\Lockme;
    
    include 'vendor/autoload.php';
    
    $sdk = new Lockme([
        "clientId" => '[client ID from cockpit]',
        'clientSecret' => '[client secret from cockpit]',
        'redirectUri' => '[redirect URI from cockpit]',
    ]);
    
    try {
        $sdk->loadAccessToken(
            fn() => file_get_contents('token.json'),
            fn($token) => file_put_contents('token.json', json_encode($token))
        );
        // Connection is established
        var_dump($sdk->Test());
    }catch(Exception $e){
        var_dump($e->getMessage());
    }
    

    An example of handling a message using our SDK

    In the following code snippet, we assume that the $sdk variable has been initialized according to the "example connection code" section:

    <?php
    
    use Lockme;
    
    // Initialize SDK as $sdk here
    
    assert($sdk instanceof Lockme);
    
    try {
        $messageid = $_SERVER['HTTP_X_MESSAGEID'];
        // Fetch message data
        $message = $sdk->GetMessage((int) $messageid);
    
        // Handle message however you need
        store_to_db($message);
    
        // Mark message as handled
        $sdk->MarkMessageRead((int) $messageid);
    
        echo 'OK';
    } catch (Exception $e) {
        // Display exception for debugging
        echo $e->getMessage();
    }
    

    Integration help

    Need help with integration? Write to us at [email protected].

    Hallo, unsere Website verwendet Cookies, damit alle Funktionen ordnungsgemäß funktionieren können.

    Zusätzlich zu diesen notwendigen Cookies verwenden wir auch Cookies von Dritten, damit wir Analyse-, Social-Media- oder Marketing-Tools von Dritten nutzen können. Das bedeutet, dass die damit erhobenen Daten auch von den Anbietern dieser Tools verarbeitet werden.

    Bist du mit der Verwendung von Cookies einverstanden, die nicht für den Betrieb der Website erforderlich sind, wie in unserer Datenschutzerklärung beschrieben wurde?

    Cookie-Einstellungen

    Hier kannst du die detaillierten Einstellungen für die auf unserer Website verwendeten Cookies ändern. Wenn du einer bestimmten Art von Cookies zustimmst, bedeutet dies, dass du damit einverstanden bist, dass die von ihnen gesammelten Daten vom Administrator dieser Website sowie vom Anbieter des von uns verwendeten spezifischen Tools verwendet werden - wie in unserer Datenschutzrichtlinie beschrieben wurde.

    Diese Art von Dateien ist für das ordnungsgemäße Funktionieren unserer Website erforderlich. Sie werden unter anderem dafür verwendet, dass der Browser das vom Nutzer gewählte Land, die Produkte im Einkaufswagen oder das Farbthema der Website speichert.

    Anhand dieser Dateien können wir nachvollziehen, wie die Nutzer auf unserer Website navigieren. Ein solches Tool ist Google Analytics, mit dem wir anonyme Informationen über die Anzahl der Besuche, die Nutzung bestimmter Funktionen oder die Art der Benutzergeräte sammeln können. Dank dieser Daten können wir die Website an die Bedürfnisse und Fähigkeiten der verschiedenen Nutzer anpassen.

    Tools von Google, Facebook und Seznam.cz, die Informationen über Nutzer sammeln, die wir für Marketingzwecke nutzen können.