Integracja po API

Oprócz innych dostępnych metod integracji, system Lock.me oferuje również integrację po API.

Do kogo skierowany jest ten artykuł?

Ten artykuł jest skierowany do osób technicznych, pragnących samemu zintegrować się z systemem Lockme. Jeśli nie wiesz, czym jest API, sprawdź artykuły na temat innych form integracji:

Zanim zaczniesz

Twoje konto musi posiadać uprawnienia partnera.
Dokumentacja dla nowego API Lockme oparta jest na protokole bezpieczeństwa OAuth2.
Dokumentacja API Lockme.
Możesz skorzystać z następującej biblioteki, aby ułatwić sobie pracę: Lockme PHP SDK.
UWAGA: Autoryzacja i wywołania OAuth nie są jeszcze funkcjonalne w tej dokumentacji.

Jakie operacje są możliwe w ramach API?

Operacje, które aktualnie udostępniamy za pośrednictwem naszego API to:

zarządzanie rezerwacjami (przeglądanie, dodawanie, edycja, usuwanie, przenoszenie) - ważne: z poziomu API nie można usuwać rezerwacji opłaconych za pośrednictwem lockme.
obsługa wiadomości webhook (pobieranie, oznaczanie jako obsłużona).
przeglądanie oddziałów i pokoi.
zarządzanie ustawieniami tygodniowymi pokoju (przeglądanie, edycja).
zarządzanie wyjątkami kalendarza pokoju (przeglądanie, dodawanie, edycja, usuwanie).

Jakie są wymagania naszej biblioteki i jak ją zainstalować?

Aktualne szczegóły naszego SDK możesz znaleźć tutaj > https://packagist.org/packages/lustmored/lockme-sdk

Do działania wymaga PHP w wersji minimum 7.2 (zalecamy przynajmniej 8.1 - wymagania mogą się zmienić w następnych wersjach!). Aby ją zainstalować należy skorzystać z Composera (https://getcomposer.org) i polecenia:

composer require lustmored/lockme-sdk

Czym jest identyfikator URI przekierowania?

Redirect URI jest to adres, na który zostanie przekierowany użytkownik przy łączeniu z aplikacją (po akceptacji przekazania danych). Parametr ten pełni również funkcję autoryzacyjną przy nawiązywaniu połączenia z API. Dlatego jego wartość musi być zgodna z tą zdefiniowaną w panelu. W przypadku braku mechanizmu autoryzacji opartego na użytkownikach, a korzystania wyłącznie z tokenów, wartość tego parametru powinna pozostać domyślna i zostać odpowiednio skonfigurowana również po stronie klienta.

Jak stworzyć aplikacje API?

Przejdź do Cockpitu Lock.me (Twoje konto musi posiadać uprawnienia partnera).
Wejdź w zakładkę "Rezerwacje" > "Aplikacje API".
W prawym górnym rogu kliknij "Dodaj".
Następnie wybierz partnera.
Wpisz nazwę wewnętrzną aplikacji (np. Moja aplikacja 1).
Podaj identyfikator URI przekierowania.
Kliknij "Dodaj".

Jak działają nasze webhooki?

Nasze webhooki wysyłają 3 rodzaje zdarzeń na zdefiniowane adresy. Jest to dodanie, edycja oraz usunięcie rezerwacji. Każda wiadomość na webhook zawiera nagłówek X-MessageId, który zawiera ID wiadomości.
W celu obsłużenia wiadomości należy ją pobrać (endpoint: GET /message/{messageid} w API), a po obsłużeniu oznaczyć, jako odczytaną (POST /message/{messageid}).
W przypadku, gdy wiadomość nie zostanie oznaczona jako odczytana, będzie parokrotnie wysyłana ponownie, w coraz większych odstępach czasu.
Każda wiadomość zawiera metadane wydarzenia (ID pokoju, rezerwacji oraz rodzaj akcji - add/edit/delete) oraz dane rezerwacji z momentu wygenerowania wiadomości.
Szczegółowe informacje dotyczące webhooków znajdziesz w artykule > https://lock.me/pl/docs/article/webhooks-configuration

Przykładowy kod połączenia z wykorzystaniem naszego SDK

Poniższy fragment kodu wymaga stworzonej aplikacji API oraz tokena, wygenerowanego z panelu. W celu obsłużenia pełnej autoryzacji użytkowników OAuth2 zachęcamy zapoznać się z dokumentacją tutaj > https://oauth2-client.thephpleague.com/ (nasze SDK działa w oparciu o bibliotekę league/oauth2-client).

W celu zachowania ciągłości połączenia do metody loadAccessToken należy przekazać callbacki odczytujące oraz zapisujące token (w tym przypadku do pliku token.json). WAŻNE: Pamiętaj, aby token nie był umieszczony na serwerze w publicznie dostępnym miejscu.

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

Przykład obsłużenia wiadomości za pomocą naszego SDK

W poniższym fragmencie kodu zakładamy, że zmienna $sdk została zainicjowana zgodnie z rozdziałem "przykładowy kod połączenia":

<?php

use Lockme\SDK\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();
}

Pomoc w integracji

Potrzebujesz pomocy w integracji? Napisz do nas na [email protected].