Integracja systemów kontroli dostępu, ogrzewania i inteligentnego domu z systemem Ellipse PMS

Hotel już wie, kto przyjedzie. Niech technologia też o tym wie.

Recepcja ma rezerwację w systemie PMS, ogrzewanie ma własny harmonogram, a zamki – osobne zarządzanie. Gdy pobyt się przedłuża lub gość zmienia pokój, tę samą informację trzeba przekazać do wielu miejsc. Właśnie te powtarzające się czynności może przejąć automatyzacja.

Ellipse PMS udostępnia poprzez API dane dotyczące pobytów, obłożenia oraz aktualnie obowiązujących kodów PIN. Usługa integracyjna regularnie je pobiera i przekształca w polecenia dla konkretnego systemu dostępu, regulacji ogrzewania lub systemu smart home.

Można podłączyć dowolny system, który umożliwia sterowanie zewnętrzne za pośrednictwem odpowiedniego interfejsu lub bramy. Po jednorazowej konfiguracji wymiana danych może przebiegać automatycznie. Kompatybilność i zakres sterowania należy sprawdzić dla konkretnego urządzenia; samo API Ellipse nie zastępuje sterownika producenta.

Dla hotelu oznacza to mniej ręcznego wprowadzania danych, jednolite źródło informacji oraz możliwość przygotowania pokoju zgodnie z charakterem pobytu. Rzeczywiste oszczędności energii lub czasu należy ocenić w trakcie eksploatacji. API dostarcza dane podstawowe, natomiast konkretne temperatury i zasady działania ustala integrator wspólnie z hotelem.

Cztery wywołania, jedno źródło danych

Integracja odczytuje dane z hotelowego adresu https://hotel.example.com/api/stays/. Domena ma charakter przykładowy; podczas wdrożenia zostanie zastąpiona adresem konkretnego hotelu. Wszystkie opisane wywołania wykorzystują metodę GET, uwierzytelnianie HTTP Basic oraz uprawnienie stays:read. Pomyślna odpowiedź ma status 200 i typ application/json.

Istniejąca integracja pobiera mapę popularności ( heatmap), mapę pinów (pinmap) oraz listę co minutę, a mapę pokoi ( roompairs) raz na godzinę. Jest to przykładowy sposób wykorzystania, a nie gwarancja natychmiastowego dostarczenia danych. Zmiana zostanie uwzględniona przy następnym pomyślnym pobraniu i przetworzeniu w systemie docelowym.

curl --fail --silent --show-error \
  --connect-timeout 5 --max-time 15 \
  --user "$ELLIPSE_USER:$ELLIPSE_PASSWORD" \
  "https://hotel.example.com/api/stays/?type=roompairs"

Zmienne środowiskowe w przykładzie reprezentują przypisane dane logowania. Wywołania kierowane są do serwera lub bramy integracyjnej za pośrednictwem protokołu HTTPS. Dane logowania nie powinny znajdować się w publicznym kodzie JavaScript ani w adresie URL.

Najważniejsze jest mapowanie pokoi. Klucz „12” w odpowiedzi to identyfikator konkretnego pokoju na planie hotelu. name: „202” to numer pokoju, a id_room: „2” oznacza kategorię pokoju. Kategoria nie jest identyfikatorem zamka. W integracji powstaje zatem powiązanie: jednostka 12 → pokój 202 → konkretny zamek i termostat.

Ogrzewanie: planujcie zgodnie z liczbą noclegów

Wywołanie funkcji heatmap zwraca wszystkie aktywne jednostki oraz plan na dzisiejszy dzień oraz sześć kolejnych dni. Wartość status: 1 oznacza noc zajęta, status: 0 – noc wolna. Dzień, w którym gość już tylko wyjeżdża, nie jest traktowany jako noc zajęta.

GET /api/stays/?type=heatmap

Przykładowa odpowiedź jest ograniczona do jednej jednostki; zawiera wszystkie siedem dat:

{
  "12": {
    "id": "12", "name": "202", "id_room": "2",
    "statuses": [
      { "date": "2026-10-08", "status": 1 },
      { "date": "2026-10-09", "status": 0 },
      { "date": "2026-10-10", "status": 1 },
      { "date": "2026-10-11", "status": 1 },
      { "date": "2026-10-12", "status": 1 },
      { "date": "2026-10-13", "status": 0 },
      { "date": "2026-10-14", "status": 0 }
    ]
  }
}

Praktyczny scenariusz: system regulacji, na podstawie przyszłego obłożenia, przygotowuje tryb komfortowy przed przyjazdem i tryb wyciszenia po wyjeździe. Wyprzedzenie i temperatury są regułami regulacji docelowej, a nie wartościami zwracanymi przez to API.

Uwaga na poranek w dniu wyjazdu: status: 0 nie oznacza, że gość już wyjechał. Do podejmowania decyzji czasowych należy również wykorzystywać dane dotyczące pobytu i godziny wyjazdu. Mapa cieplna nie jest czujnikiem obecności osoby w pokoju; dlatego nie należy wyłączać oświetlenia ani ogrzewania wyłącznie na podstawie jednej wartości obłożenia.

Dostęp: aktualny kod PIN

Wywołanie funkcji pinmap zwraca aktualny kod PIN dla każdej jednostki. Kod PIN aktywuje się w dniu przyjazdu dopiero od godziny przyjazdu podanej w rezerwacji; jeśli rezerwacja nie zawiera własnej godziny, stosowana jest domyślna godzina hotelu. W dniu wyjazdu kod PIN obowiązuje do godziny wyjazdu.

GET /api/stays/?type=pinmap

{
  "12": {
    "id": "12", "name": "202",
    "id_room": "2", "pin": "1234"
  },
  "13": {
    "id": "13", "name": "203",
    "id_room": "2", "pin": "5678"
  },
  "14": {
    "id": "14", "name": "204",
    "id_room": "2", "pin": "0"
  }
}

Kod PIN „0” oznacza wolny pokój bez ważnego dostępu dla gości. Integracja powinna cofnąć odpowiednie uprawnienia gościa; nie wolno ustawiać cyfry 0 jako kodu dostępu. Pozostałe kody PIN to czterocyfrowe ciągi znaków. Należy zachować je jako tekst, aby nie utracić ewentualnego zera na początku.

Zmiana gości w tym samym dniu: jeśli czas przyjazdu nowego gościa już minął, API zwróci kod PIN nowej rezerwacji. Usługa integracyjna musi odzwierciedlić zmianę w odpowiednim zamku i zweryfikować wynik zapisu. Pomyślne pobranie danych z API nie potwierdza jeszcze pomyślnej konfiguracji urządzenia.

To wywołanie dostarcza aktualny stan, a nie przyszły harmonogram ważności kodów. Dane nie uwzględniają warunku dokonania płatności ani zakończonego zameldowania online. Jeśli hotel wymaga spełnienia takich warunków, muszą one zostać oddzielnie zweryfikowane i rozwiązane w procesie przyznawania dostępu.

Pobyty i mapa pokoi: kontekst dla automatyzacji

Gdy integracja wymaga dat i godzin pobytu, wykorzystuje list. Parametr date jest obowiązkowy i ma format YYYY-MM-DD. Przy acmd=1 zwracane są wszystkie pobyty umieszczone na liście w danym dniu, nawet przed zameldowaniem. Bez niego, czyli przy acmd=0, pozostaną tylko pokoje, w których gość już się zakwaterował.

GET /api/stays/?type=list&date=2026-10-08&acmd=1

[
  {
    "room": "13", "roomname": "203",
    "reservation": "100001", "lang": "sk",
    "name": "Imię", "surname": "Nazwisko",
    "arrival": "2026-10-07",
    "departure": "2026-10-09",
    "a-time": "15:00:00", "d-time": "10:00:00",
    "pin": "5678", "phone": "+421900000000",
    "out_of_order": false
  }
]

room identyfikuje pokój. a-time i d-time to godziny przyjazdu i wyjazdu z danego pokoju. out_of_order: true oznacza zamknięcie techniczne, a nie temperaturę. Nie należy używać kodu PIN z listy pobytów jako dowodu aktualnej ważności; do tego służy pinmap.

W przypadku braku lub nieprawidłowej daty API zwróci status 400 i odpowiedź {"error":"Date"}. Przy regularnym odczytywaniu data musi ulegać zmianie; przykładowa data nie może pozostać na stałe w integracji produkcyjnej.

Mapa roompairs przypisuje identyfikator jednostki do numeru pokoju. Poniżej znajduje się fragment odpowiedzi:

GET /api/stays/?type=roompairs

{ "12": "202", "13": "203", "14": "204", "21": "303" }

Mapę należy załadować na początku, a następnie ją odświeżać. W przypadku przeniesienia gościa lub zmiany konfiguracji hotelu należy również zweryfikować powiązania z fizycznymi urządzeniami.

Jak z danych powstaje niezawodna automatyzacja

Po stronie Ellipse wystarczy odczytywać jednolite API. Usługa integracyjna porównuje następnie otrzymany stan z ostatnim pomyślnie zastosowanym stanem i za pośrednictwem interfejsu producenta wprowadza niezbędne zmiany. Wielokrotne odczytywanie tego samego stanu nie powinno powodować tworzenia zduplikowanych kodów dostępu ani niepotrzebnych poleceń.

Zalecana procedura dla integratora:

1. Uzyskać dostęp do hotelowego API z uprawnieniem stays:read i zweryfikować połączenie HTTPS.
2. Przyporządkować jednostki z roompairs do konkretnych zamków i regulatorów.
3. Pobierać żądane stany, sprawdzać odpowiedź HTTP oraz strukturę JSON.
4. Ocenić różnice i zastosować je za pośrednictwem interfejsu systemu docelowego.
5. Potwierdzić wykonanie, zapisać czas ostatniej udanej synchronizacji i zgłosić błąd.

Awaria API nie oznacza wolnego pokoju. Błędu, przekroczenia limitu czasu ani niekompletnej odpowiedzi nie należy przekształcać na pin: „0” ani na polecenie wyłączenia ogrzewania. Należy z wyprzedzeniem ustawić maksymalny czas ważności danych, zasady postępowania w przypadku awarii oraz ręczną interwencję. W przypadku dostępów operator musi również uwzględnić wygaśnięcie ważności w przypadku niedostępnej synchronizacji; aktualna mapa pinów sama w sobie nie zawiera czasu wygaśnięcia.

W przypadku ogrzewania należy przestrzegać lokalnych zabezpieczeń urządzeń oraz minimalnych wymagań eksploatacyjnych. W przypadku dostępów synchronizacja gości nie zmienia uprawnień serwisowych ani awaryjnych. Nie zapisuj haseł API ani kodów PIN w zwykłych logach. Z listy punktów końcowych przetwarzaj tylko te dane, które są potrzebne do integracji.

Przed uruchomieniem należy przetestować wcześniejsze przybycie, późniejsze wyjazdy, przedłużenie pobytu, zmianę pokoju, zmianę gości w ciągu jednego dnia, zamknięcie techniczne oraz awarię sieci. Należy uzgodnić z realizatorem API strefę czasową, graniczne momenty czasowe oraz sposób postępowania w przypadku anulowania pobytu; dostarczona dokumentacja nie określa ich szczegółowo.

Te same dane mogą stanowić podstawę dla innych scenariuszy inteligentnego domu, na przykład przygotowania trybu komfortowego w pokoju. Ich realizacja zależy od funkcji systemu docelowego. Opisane API odczytuje pobyty; polecenia dla urządzeń wykonuje warstwa integracyjna.

Chcesz połączyć swoje technologie z Ellipse? Prześlij nam nazwę i model systemu dostępu lub regulacji oraz dane kontaktowe swojego integratora. Wspólnie sprawdzimy interfejs, mapowanie pokoi i odpowiedni pilot. Umów się na konsultację lub zapoznaj się z systemem hotelowym Ellipse.