Zamki TTLock w aparthotelu: API, PMS i automatyzacja dostępu

1. Jak działa TTLock w aparthotelu?

TTLock to ekosystem zamków elektronicznych, aplikacji i platformy integracyjnej. Sama nazwa nie oznacza jednego identycznego zamka: rozwiązania różnych producentów mogą używać technologii TTLock, ale różnią się mechaniką, elektroniką, firmware’em, wersją obsługiwanych kodów i akcesoriami. Do wdrożenia liczy się dokładny model i jego dokumentacja, nie tylko logo aplikacji.

Typowy zamek komunikuje się lokalnie z telefonem przez Bluetooth Low Energy (BLE). Gość może dostać kod PIN ważny wyłącznie w czasie rezerwacji, e‑key w aplikacji albo — jeśli dany model to obsługuje — kartę, odcisk palca czy inny identyfikator. W wynajmie krótkoterminowym kod PIN zwykle zmniejsza tarcie: gość nie musi instalować aplikacji, zakładać konta ani mieć kompatybilnego telefonu.

Jeśli operator ma zdalnie sprawdzać stan zamka, wysłać polecenie albo synchronizować uprawnienia bez podchodzenia do drzwi, potrzebna jest ścieżka komunikacji online: najczęściej zgodna bramka BLE–Wi‑Fi/LAN w zasięgu zamka albo zamek z łącznością komórkową. Bramka nie sprawia, że sam mechanizm drzwi staje się niezależny od chmury. Jej zasilanie, Internet, zasięg BLE, konto TTLock i usługa API stają się elementami łańcucha.

2. Trzy modele obsługi gości — od aplikacji po automat

Praktyczny przepływ nie powinien opierać się na samym „utwórz kod”. Ważne są też zmiana terminu, anulowanie, przedłużenie pobytu, zmiana pokoju, nieudane płatności, wcześniejsze wymeldowanie, awaria API i ponowienie żądania. W każdym z tych zdarzeń integracja musi wiedzieć, które uprawnienie należy utworzyć, zmienić lub odebrać.

3. API TTLock — co można zintegrować i napisać samodzielnie?

Tak — TTLock udostępnia Open Platform API, a producent publikuje także SDK dla aplikacji. To umożliwia integrację z PMS, systemem rezerwacji, panelem recepcji lub własnym portalem gościa; można też zlecić napisanie pośredniczącego oprogramowania dopasowanego do konkretnego obiektu. API nie jest jednak magicznym przełącznikiem: dostęp wymaga aplikacji i poświadczeń platformy, a możliwości zależą od modelu zamka, wersji kodów, gatewaya i konkretnego endpointu.

W oficjalnej dokumentacji Cloud API V3 opisano między innymi operacje na zamkach, e‑key, czasowych kodach PIN, gatewayach i rejestrze otwarć. Przykładowo endpoint dodawania kodu przyjmuje identyfikator zamka i początek/koniec ważności jako znaczniki czasu w milisekundach. Dokumentacja zaznacza, że własny kod dodawany przez API wymaga zamków z wersją kodów V4; tryb dodania przez gateway jest odrębny od scenariusza Bluetooth wymagającego operacji SDK przy telefonie. Zgodność trzeba sprawdzić na konkretnym egzemplarzu i firmware’ze, zanim zbuduje się logikę produkcyjną.

Dzięki API można, w zależności od sprzętu i przyznanych uprawnień:

• generować kod dla konkretnego zamka z ograniczeniem daty i godziny;
• automatycznie wysłać gościowi dostęp po potwierdzeniu rezerwacji, a po jej anulowaniu usunąć lub unieważnić;
• przedłużyć pobyt albo utworzyć dostęp dla serwisu z krótszym oknem czasowym;
• sprawdzać listę zamków i gatewayów oraz dostępność gatewaya;
• odczytywać rejestr zdarzeń lub stan baterii — o ile wspiera to model i konfiguracja;
• zbudować panel administracyjny, pulpit recepcji, integrację z CRM/PMS lub przepływ automatyzacji.

Ważny niuans: „jest API” nie oznacza, że każdy zamek da się otworzyć z dowolnej aplikacji w dowolnym momencie. Polecenie z chmury zależy od dostępności połączenia przez bramkę lub odpowiedni wariant sprzętu. Funkcje i nazwy endpointów różnią się między API, SDK i generacjami. Najpierw należy zarejestrować aplikację w Open Platform, uzyskać i przetestować tokeny, sprawdzić wymagania konta oraz potwierdzić warunki dostępu i ewentualne opłaty z TTLock lub dystrybutorem — nie zakładać, że dostęp produkcyjny jest bezwarunkowy lub bezpłatny.

API używamy wyłącznie po stronie serwera. Client secret, access token, kody gości i pełne odpowiedzi API nie powinny trafić do kodu JavaScript w przeglądarce, logów WordPressa ani repozytorium publicznego. Dokumentacja endpointu odczytu historii wskazuje, że rekord może zawierać użyty kod/identyfikator dostępu. To szczególnie wrażliwe dane operacyjne: ogranicz dostęp, retencję i zakres eksportu do tego, co rzeczywiście jest potrzebne.

4. Przykładowa architektura: rezerwacja → kod → wiadomość

Bezpieczna integracja zwykle składa się z trzech warstw: PMS lub system rezerwacji, własny backend pośredniczący i TTLock Open Platform. Frontend nie łączy się bezpośrednio z API zamków.

1. PMS emituje zmianę rezerwacji. Backend pobiera identyfikator lokalu, status, datę/godzinę check-in i check-out oraz niezbędny kanał dostarczenia instrukcji. Nie kopiujemy do zamka ani do logów całego profilu gościa.
2. Backend waliduje reguły. Sprawdza płatność i status, mapuje lokal na prawidłowy lock ID, uwzględnia strefę Europe/Warsaw, zmianę czasu i bufor wejścia/wyjścia.
3. Backend wywołuje TTLock. Używa tokenu przechowywanego po stronie serwera i tworzy dostęp ważny w dokładnym oknie pobytu. Dla nowego wdrożenia warto preferować losowe, unikatowe kody zamiast numeru rezerwacji lub danych osobowych.
4. Zapisuje rezultat i wysyła komunikat. Dopiero po potwierdzeniu powodzenia wysyła gościowi kod oraz prostą instrukcję wejścia. W razie błędu alarmuje obsługę i uruchamia procedurę ręczną.
5. Obsługuje zmiany idempotentnie. Powtórny webhook lub retry nie może tworzyć wielu aktywnych kodów. Każda operacja powinna mieć identyfikator rezerwacji, status i bezpieczną ścieżkę ponowienia.

Jeżeli PMS nie ma gotowego konektora, można napisać własny mostek REST albo użyć narzędzia automatyzacyjnego — ale po sprawdzeniu, czy PMS udostępnia stabilne API/webhooki i czy pozwala na pracę na danych produkcyjnych. Samo posiadanie API po stronie TTLock nie rozwiązuje braku API po stronie systemu rezerwacji. Trzeba również ustalić, kto utrzymuje integrację, aktualizuje ją po zmianach endpointów i odpowiada za komunikację z gościem.

5. Bramka, Bluetooth i co się stanie bez Internetu

Bluetooth jest dobry do lokalnej obsługi przez operatora znajdującego się przy drzwiach oraz do scenariuszy, w których telefon gościa jest kluczem. Zasięg jest ograniczony, a integracja przez SDK oznacza rozwijanie i utrzymanie aplikacji mobilnej oraz obsługę uprawnień systemu telefonu. Dla gościa, który chce po prostu wejść kodem, aplikacja może być zbędnym utrudnieniem.

Gateway pośredniczy między chmurą a zamkiem po BLE. Zgodna bramka umożliwia zdalną administrację i wybrane operacje online, ale wymaga stabilnego zasilania, Internetu i zasięgu radiowego od gatewaya do zamka. Nie należy przyjmować katalogowej odległości jako gwarancji dla grubych ścian, metalowych drzwi, korytarzy czy wielu kondygnacji. Rozmieszczenie trzeba zweryfikować na miejscu; czasem sensowniejszy jest dodatkowy gateway w strefie niż jeden „mocny router”. Przykład gatewaya TTLock G2/G3 można sprawdzić w [polskim cenniku ESC](https://www.escsa.pl/sklep/product-locstar-g2-g3-ttlock-wi-fi-smart-gateway.html).

Awaria Internetu lub chmury: zdalne komendy, synchronizacja i odczyt bieżących danych mogą nie działać, choć wcześniej poprawnie zapisany PIN może nadal działać lokalnie w zamku — zależnie od modelu, sposobu wygenerowania, synchronizacji, zegara i firmware’u. Nie obiecuj gościom działania offline bez testu. Odbiór musi obejmować odcięcie Internetu, restart gatewaya, rozładowaną baterię, błędny czas i sprawdzenie, czy kod wygasa zgodnie z oczekiwaniem.

6. Dobór zamka: drzwi, ewakuacja i codzienna eksploatacja

Dobór zaczyna się od pomiarów i oględzin: grubość skrzydła, rozstawy, kierunek otwierania, rodzaj zamka wpuszczanego, wkładka, szyld, sposób ryglowania i możliwość awaryjnego otwarcia. Klamka elektroniczna lub retrofit nie pasuje automatycznie do każdych drzwi. Przy drzwiach przeciwpożarowych, drogach ewakuacyjnych i wejściach wspólnych potwierdź zgodność z projektem, wymaganiami obiektu i instrukcją producenta drzwi — nie montuj elektroniki, która może utrudnić bezpieczne wyjście.

W aparthotelu trzeba też rozdzielić poziomy dostępu: wejście zewnętrzne, piętro, lokal, zaplecze techniczne i pomieszczenia personelu. Kod do pokoju nie powinien otwierać serwerowni, magazynu ani wszystkich drzwi w budynku. Karty lub e‑key dla housekeeping powinny mieć osobny zakres i grafik. Tam, gdzie to możliwe, zachowaj mechaniczny sposób awaryjnego otwarcia i określ, kto oraz jak może z niego skorzystać.

7. Koszty: zamek to tylko jedna pozycja

Ceny zależą od mechaniki drzwi, wykończenia, czytnika, dystrybutora i zakresu integracji. Jako orientacyjny punkt odniesienia: w chwili sprawdzenia polska oferta modeli TTLock vG/HT wyświetlała przykładowe ceny ok. 1 132–1 513 zł brutto za wybrane klamki/okucia; gateway G2/G3 był prezentowany za ok. 384 zł brutto. Są to ceny konkretnego sprzedawcy i konkretnych modeli, a nie gwarantowany cennik całego rynku; mogą się zmieniać. Zobacz [bieżącą listę TTLock w Altum Polska](https://altumpolska.pl/c/ttlock-smartlock) oraz [przykład gatewaya w ESC](https://www.escsa.pl/sklep/product-locstar-g2-g3-ttlock-wi-fi-smart-gateway.html).

Przy kilku lokalach ręczne klikanie może być najtańsze na starcie. Gdy rezerwacji jest dużo, koszt pracy recepcji, błędne kody i nocne interwencje szybko zmieniają rachunek. Policz koszt całkowity: sprzęt + instalacja + gatewaye + licencje/API + wiadomości do gości + administracja + utrzymanie integracji + awaryjna obsługa. Dostępność i cena usługi Open API nie są tu zgadywane — należy je potwierdzić przed wyceną projektu.

8. Bezpieczeństwo, prywatność i procedury awaryjne

• Oddziel konto właściciela od konta recepcji i serwisu; nadaj każdej roli tylko niezbędne uprawnienia.
• Trzymaj Client Secret i access token w menedżerze sekretów lub chronionej konfiguracji backendu; zaplanuj odnowienie tokenu i jego unieważnienie po incydencie.
• Nie umieszczaj PIN-u, pełnego API request/response ani tokenu w logach aplikacji. Ogranicz historię otwarć do osób, które jej potrzebują, i ustal retencję oraz zasady dostępu.
• Po wymeldowaniu sprawdź, że dostęp wygasł; po anulowaniu pobytu unieważnij go od razu, a nie dopiero przy ręcznym przeglądzie rezerwacji.
• Przygotuj plan, gdy PMS, Internet, cloud API, gateway lub zasilanie nie działa: numer dyżurny, weryfikacja tożsamości gościa, mechaniczny klucz awaryjny, kontakt do osoby na miejscu oraz rejestr interwencji.
• Przed uruchomieniem ustal, kto administruje zamkami po odejściu pracownika lub zmianie operatora. Przekazanie kont, tokenów i kluczy awaryjnych powinno być udokumentowane.

Historia wejść i identyfikatory przypisane do rezerwacji mogą ujawniać informacje o konkretnych osobach. Zbieraj tylko dane niezbędne do obsługi i bezpieczeństwa, ogranicz dostęp oraz uzgodnij role administratora i podmiotu przetwarzającego z dostawcą PMS/IT. Sama obecność historii w aplikacji nie oznacza, że wolno ją przechowywać bezterminowo lub udostępniać każdemu pracownikowi.

9. Plan wdrożenia i testy odbiorowe

1. Inwentaryzacja drzwi: sprawdź mechanikę, kierunek ewakuacji, wariant awaryjny i listę lokalizacji.
2. Pilot: zamontuj 1–2 reprezentatywne modele, sprawdź telefon, PIN, gateway, baterie i codzienny check-in.
3. Integracja: potwierdź konto Open Platform, endpointy, zakres danych, dostępność PMS API, obsługę anulowania i retry.
4. Test awarii: odłącz Internet, wyłącz gateway, zasymuluj opóźnioną/anulowaną rezerwację i sprawdź wejście ręczne.
5. Odbiór i szkolenie: przekaż mapę lock ID, konta i role, instrukcję dla gościa, procedurę serwisową i odpowiedzialność za baterie.

Jeśli dopiero planujesz sieć dla obiektu, zobacz też nasz poradnik o Wi‑Fi dla hoteli. Przy wdrożeniu warto potraktować zamki jako część całej infrastruktury, a nie odizolowany gadżet: sieci gości i urządzeń, zasilanie, dostęp administratorów, PMS oraz procedury recepcji muszą działać razem.

Ceny sprzętu przytoczono jako przykłady z publicznych ofert handlowych sprawdzonych 26 września 2026 r.; przed zakupem zweryfikuj model, cenę i dostępność u sprzedawcy. Zakres API, model zamka i warunki Open Platform należy potwierdzić dla konkretnego konta i urządzenia. Poradnik nie zastępuje audytu drzwi, projektu ewakuacji ani analizy ochrony danych dla konkretnego obiektu.