gaesteCodes.codeAnzeigen
Reveal the personal keypad code of one booking (only when confirmed or locked). Every call is audit-logged with channel; the value never appears in logs. Operator roles. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
code | string | yes |
gaesteCodes.codeNachZimmer
Reveal the personal keypad code by room and date instead of booking id. Picks the booking whose night covers the date — on a changeover day the arriving guest, not the departing one. Returns code, stayId, room, arrival and departure. `stay_nicht_gefunden` (NOT_FOUND): no booking that night; `zimmer_mehrdeutig` (PRECONDITION_FAILED): more than one — use the full room name or `codeAnzeigen`. Same rules and audit log as `codeAnzeigen`. Operator roles. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
zimmer | string | yes | |
datum | string | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
code | string | yes | |
stayId | string | yes | |
zimmer | string | yes | |
anreise | string | yes | |
abreise | string | yes |
gaesteCodes.einstellungen
Settings of personal guest codes for the single active Nuki front door: on/off, active from (date), daily window (arrival from, departure until), live keypad occupancy, and whether personal codes are possible at all (`grund`: keine_nuki_tuer, mehrere_tueren, or abo_noetig when Nuki recently refused with 402/426). Owner only.
Input parameters
Returns object.
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
doorId | string · nullable | yes | |
doorName | string · nullable | yes | |
aktiv | boolean | yes | |
aktivAb | string · nullable | yes | |
anreiseAb | string | yes | |
abreiseBis | string | yes | |
belegung | number · nullable | yes | |
moeglich | boolean | yes | |
grund | string · nullable | yes |
gaesteCodes.einstellungenSetzen
Switch personal guest codes on/off for the single active Nuki front door and set the daily window (arrival from HH:MM ≤ 12:00, departure until HH:MM). Switching on applies to arrivals from TOMORROW; switching off lets existing codes run out. Owner only. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
doorId | string | yes | |
aktiv | boolean | yes | |
anreiseAb | string | yes | |
abreiseBis | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
doorId | string · nullable | yes | |
doorName | string · nullable | yes | |
aktiv | boolean | yes | |
aktivAb | string · nullable | yes | |
anreiseAb | string | yes | |
abreiseBis | string | yes | |
belegung | number · nullable | yes | |
moeglich | boolean | yes | |
grund | string · nullable | yes |
gaesteCodes.freigeben
Re-enable a locked personal keypad code (only before its end). Confirmed by read-back (up to ~3 min); without a confirmed code (locked before it existed, or its entry was deleted) the booking returns to planned (`hinweis: neu_geplant`) and Foyer's next run decides again — on arrival day after 14:30 that means the shared code only. Owner only. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes |
Output fields
One of 2 shapes, depending on the outcome:
Shape 1
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | literal | yes | One of: freigegeben |
hinweis | literal | no | One of: neu_geplant |
Shape 2
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | literal | yes | One of: fehlgeschlagen |
grund | string | yes |
gaesteCodes.sperren
Lock a guest out — in any state, also before the code exists (then no code is ever created for this booking). Later messages carry no door code for this booking. An existing Nuki entry is disabled (or, if not yet confirmed, deleted) and checked by read-back (up to ~3 min); entries of fallback/failed bookings are deleted, never just disabled. If Nuki does not confirm, the booking is STILL locked, the result carries `hinweis: nuki_unbestaetigt`, and an urgent task asks to check the entry in the Nuki app; calling `sperren` again retries Nuki. On one room of a multi-room booking it locks the whole booking's code. `takt_laeuft` (CONFLICT): Foyer's own run is working on this booking — retry in a moment. Owner only. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes |
Output fields
One of 2 shapes, depending on the outcome:
Shape 1
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | literal | yes | One of: gesperrt |
hinweis | literal | no | One of: nuki_unbestaetigt |
Shape 2
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | literal | yes | One of: fehlgeschlagen |
grund | string | yes |
gaesteCodes.status
Personal front-door keypad code of one booking: state (geplant/angelegt/bestaetigt/gesperrt/deaktiviert/fehlgeschlagen/rueckfall/geloescht, null = no code yet), valid from/until (Foyer enforces the end itself — Nuki carries no time window), end offset in days, last error category, explicit timestamps (confirmed/locked/deactivated/deleted), and keypad openings of this booking. `aktiv` = personal codes are switched on for the house. Called with one room of a multi-room booking, it reports the booking's shared code (`traegerStayId`). Never returns the code value. Operator roles.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes | |
traegerStayId | string | yes | |
zustand | string · nullable | yes | |
gueltigAb | string · nullable | yes | |
gueltigBis | string · nullable | yes | |
endeVersatzTage | number | yes | |
letzterFehler | string · nullable | yes | |
bestaetigtAm | string · nullable | yes | |
gesperrtAm | string · nullable | yes | |
deaktiviertAm | string · nullable | yes | |
geloeschtAm | string · nullable | yes | |
oeffnungen | array of string | yes | |
aktiv | boolean | yes |
gaesteCodes.uebersicht
Count of confirmed personal guest codes and live keypad occupancy of the front door, with a hint at ≥ 80 (fast_voll) and ≥ 95 (voll — no new personal codes). Owner only.
Input parameters
Returns object.
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
aktiv | number | yes | |
belegung | number · nullable | yes | |
hinweis | enum · nullable | yes | One of: fast_voll, voll |
gaesteCodes.zeitraumAendern
Extend (+) or shorten (−) the validity END of the booking's personal code by whole days (−60…60, not 0); the offset survives later booking date changes. Rejected if the new end is in the past or before the start, or if the code is already deleted. Changes Foyer only (no Nuki call): Foyer switches the code off at the end and deletes it the day after; a code already switched off becomes active again on Foyer's next run if the new end lies in the future. Owner only. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes | |
tage | integer | yes |
Output fields
One of 2 shapes, depending on the outcome:
Shape 1
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | literal | yes | One of: geaendert |
gueltigBis | string · nullable | yes |
Shape 2
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | literal | yes | One of: fehlgeschlagen |
grund | string | yes |