API Integration

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:

• Google Calendar integration
• Integration with Wordpress

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."

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].