smartLocks.batterien
Open Nuki device tasks (battery `aufgaben`, faulty door `stoerungen`) AND the logs of the most recent runs. Does NOT call Nuki live, so the handover and smart locks pages stay fast. Any staff member. Read-only query.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
mitLauf | boolean | no | |
mitWaechter | boolean | no | |
mitProtokoll | boolean | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
aufgaben | array of object | yes | |
aufgaben.taskId | string | yes | |
aufgaben.title | string | yes | |
aufgaben.priority | string | yes | |
aufgaben.status | string | yes | |
aufgaben.createdAt | string | yes | |
aufgaben.tuerId | string | yes | |
aufgaben.komponente | enum | yes | One of: geraet, keypad, tuersensor |
letzterLauf | object · nullable | yes | |
letzterLauf.at | string | yes | |
letzterLauf.geprueft | array of string | yes | |
letzterLauf.fehlend | array of string | yes | |
letzterLauf.ohneSignal | array of string | yes | |
letzterLauf.kritisch | array of string · nullable | no | |
letzterLauf.fehler | string · nullable | yes | |
stoerungen | array of object | yes | |
stoerungen.taskId | string | yes | |
stoerungen.title | string | yes | |
stoerungen.priority | string | yes | |
stoerungen.status | string | yes | |
stoerungen.createdAt | string | yes | |
stoerungen.seit | string · nullable | yes | |
stoerungen.tuerId | string | yes | |
stoerungen.grund | string | yes | |
tuerLauf | object · nullable | yes | |
tuerLauf.at | string · nullable | yes | |
tuerLauf.tueren | object | yes | |
tuerLauf.fehler | string · nullable | yes | |
tuerLauf.fehlerSeit | string · nullable | yes | |
aufgabenSichtbar | boolean | yes | |
protokoll | object · nullable | yes | |
protokoll.klingeln | array of object | yes | |
protokoll.falschCode | array of object | yes | |
protokoll.daueroeffnung | array of object | yes | |
protokoll.logScopeFehlt | boolean | yes | |
waechterAusfall | object · nullable | yes | |
waechterAusfall.art | enum | yes | One of: nuki, gestoppt |
waechterAusfall.seit | string | yes | |
waechterAusfall.fehler | string | yes |
smartLocks.batterienPruefen
Batterie-Abgleich jetzt statt erst um 06:15 ausfuehren. Owner-only (schreibt Aufgaben). Mutation — changes data.
Input parameters
Returns object.
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
angelegt | integer | yes | |
geschlossen | integer | yes | |
abgebrochen | integer | yes | |
fehlend | integer | yes |
smartLocks.doors.create
Add a door. Provider account must exist. Owner-only. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | |
provider | enum | yes | One of: nuki, ttlock, tedee |
lockRef | string | yes | |
lockName | string | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes |
smartLocks.doors.delete
Delete a door mapping from the smart-lock registry. Refused (`gaeste_codes_aktiv`) while the door still carries live personal guest codes — delete or let them expire first; `takt_laeuft` (CONFLICT) while Foyer's guest-code run is working — retry in a moment.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
smartLocks.doors.list
All doors, default-door order (position, createdAt). Any staff. Read-only query.
Input parameters
Returns object.
Output fields
Returns array of object. Fields of each element:
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
name | string | yes | |
provider | enum | yes | One of: nuki, ttlock, tedee |
lockName | string · nullable | yes | |
enabled | boolean | yes | |
position | integer | yes |
smartLocks.doors.listProviderLocks
List the provider account's locks (setup "Schlösser laden" (load locks)). Owner-only. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
provider | enum | yes | One of: nuki, ttlock, tedee |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
locks | array of object | yes | |
locks.lockRef | string | yes | |
locks.name | string | yes |
smartLocks.doors.update
Rename / enable / reorder a door. Owner-only. Mutation — changes data.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
name | string | no | |
enabled | boolean | no | |
position | integer | no |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ok | literal | yes | One of: true |
smartLocks.haustuerCodeAnzeigen
Reveal the code value of ONE keypad-code entry (Nuki type 13) at the front door, read live from Nuki. The code is a house key: it is never stored in Foyer, but every call is audit-logged (door.code_shown: who, when, door, authId). Only entries whose `erlaubt.anzeigen` is true. Owner only. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
doorId | string | yes | |
authId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
code | string | yes |
smartLocks.haustuerCodeVorschau
Preview of a front-door code rotation: which Nuki entry is the current guest code, until when the old code stays valid, how many stays may already have it. Changes nothing. Owner only.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
doorId | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
alteAuth | object | yes | |
gueltigBis | string | yes | |
betroffeneAufenthalte | integer | yes | |
mitVorgabeAltCode | integer | yes | |
woertlichInTexten | integer | yes |
smartLocks.haustuerCodeWechseln
Rotate the guests' front-door keypad code: creates a new random code at Nuki, waits for Nuki to confirm (up to ~3 min), THEN switches guest messages and the arrival guide to it; the old code stays valid until the affected guests have left. Returns the new code in plaintext once. On `rueckleseprobe_zeitueberschreitung` (Nuki did not confirm in time) the result is `fehlgeschlagen` with `authName`: the shared code stays the OLD one, but an unconfirmed entry with that name may remain at Nuki — tell the owner to check the Nuki app (Authorizations) for an entry named exactly `authName` and delete it if present. Never relay or guess a code. Physical security: a wrong rotation can lock guests out. Owner only, audit-logged. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
doorId | string | yes | |
alteAuthId | string · nullable | no |
Output fields
One of 2 shapes, depending on the outcome:
Shape 1
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | literal | yes | One of: gewechselt |
neuerCode | string | yes | |
neueAuthName | string | yes | |
gueltigBis | string | yes |
Shape 2
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | literal | yes | One of: fehlgeschlagen |
grund | string | yes | |
authName | string | no |
smartLocks.haustuerZugang
Who has access to the front door: every Nuki authorization of each active Nuki door, read LIVE from Nuki (≤ 60 s cache). Contains the names of Nuki app users (personal data, live only — Foyer does not store them) but never a code value. Each entry carries `erlaubt` — which actions the protection rules allow (show code, edit name/code/active, delete), `grund` when something is locked (gaestecode_geschuetzt, foyer_gaeste_code = a personal per-booking guest code managed by Foyer: show only, manage it via the booking; schonfrist_laeuft, nuki_beschaeftigt, geraet; zeitfenster_eintrag = the entry carries a time window set in the Nuki app: edit name/code/active is not allowed, only viewing and deleting). An existing time window (`vonTag`/`bisTag`) is shown read-only: Foyer does not write time windows and does not write to entries that have one. Owner only.
Input parameters
Returns object.
Output fields
Returns array of object. Fields of each element:
| Field | Type | Required | Notes |
|---|---|---|---|
doorId | string | yes | |
doorName | string | yes | |
stand | enum | yes | One of: ok, fehler |
fehler | string · nullable | yes | |
abgerufenAm | string | yes | |
codesBekannt | boolean | yes | |
traegtGaesteCode | boolean | yes | |
eintraege | array of object | yes | |
eintraege.id | string | yes | |
eintraege.name | string | yes | |
eintraege.typ | string | yes | |
eintraege.enabled | boolean | yes | |
eintraege.allowedFromDate | string · nullable | yes | |
eintraege.allowedUntilDate | string · nullable | yes | |
eintraege.allowedWeekDays | integer · nullable | yes | |
eintraege.allowedFromTime | integer · nullable | yes | |
eintraege.allowedUntilTime | integer · nullable | yes | |
eintraege.lastActiveDate | string · nullable | yes | |
eintraege.fehler | boolean | yes | |
eintraege.istGaesteCode | boolean | yes | |
eintraege.vonTag | string · nullable | yes | |
eintraege.bisTag | string · nullable | yes | |
eintraege.deaktivierungNach | string · nullable | yes | |
eintraege.erlaubt | object | yes |
smartLocks.haustuerZugangBearbeiten
Edit a Nuki authorization at the front door. An entry that carries a time window (set in the Nuki app) is NOT editable here — name, code and active are rejected with `zeitfenster_eintrag` (Foyer would have to write the window back, which Nuki drops or hides); change it in the Nuki app, deleting works. Foyer does NOT write time windows (decision 2026-10-05, Nuki drops them): a `zeitfenster` that differs from the entry's current window is rejected with `zeitfenster_nicht_verfuegbar` — do not send it; windows can only be set in the Nuki app. Fields: name (1–32 chars), code (keypad codes only: 6 digits 1–9, not starting with 12, not trivial, not used by another entry) and active/inactive. Send only the fields to change; code-change names (“Foyer Gäste <digit>…”, older “Foyer Gäste ab …”) are reserved. The current guest code and old codes in their grace period are protected (rename only). Waits for Nuki to confirm EVERY field (up to ~3 min); `gespeichert` only after the read-back. If Nuki drops the time window (entry would be unlimited) Foyer deactivates the entry and creates an urgent task (`zeitfenster_verworfen_deaktiviert`). If Nuki does not confirm in time, Foyer re-checks after ~10 min (`unbestaetigt_nachpruefung_geplant`). `gespeichert` may carry `hinweis: zeitfenster_verworfen_inaktiv` — the entry is inactive but Nuki dropped its existing time window; tell the owner. ACTIVATING an entry without a time window requires `unbegrenztBestaetigt: true` — the code then applies WITHOUT time limit; ask the owner explicitly before setting it (otherwise `aktivierung_ohne_zeitfenster`). An entry whose window has expired (`zeitfenster_abgelaufen`) can only be deactivated or deleted here. Owner only, audit-logged. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
doorId | string | yes | |
authId | string | yes | |
aenderung | object | yes | |
aenderung.name | string | no | |
aenderung.code | string | no | |
aenderung.zeitfenster | object | no | |
aenderung.aktiv | boolean | no | |
aenderung.unbegrenztBestaetigt | boolean | no |
Output fields
One of 2 shapes, depending on the outcome:
Shape 1
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | literal | yes | One of: gespeichert |
hinweis | string | no |
Shape 2
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | literal | yes | One of: fehlgeschlagen |
grund | string | yes |
smartLocks.haustuerZugangLoeschen
Delete a Nuki authorization at the front door. Not possible for the current guest code, old codes in their grace period, or the bridge/keypad devices. Deleting an APP entry (typ `app`) means that person can no longer open the door with the Nuki app — say so when asking for confirmation. Waits for Nuki to confirm the entry is gone (up to ~3 min). Owner only, audit-logged. Requires confirmation.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
doorId | string | yes | |
authId | string | yes |
Output fields
One of 2 shapes, depending on the outcome:
Shape 1
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | literal | yes | One of: geloescht |
Shape 2
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | literal | yes | One of: fehlgeschlagen |
grund | string | yes |
smartLocks.listActiveCodes
Lists a stay's (stayId) active (not revoked) door codes with lock ID, code in plain text, and validity period. Operations roles only (owner, staff, reception). Read-only.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
stayId | string | yes |
Output fields
Returns array of object. Fields of each element:
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | |
lockId | string | yes | |
code | string | yes | |
validFrom | string | yes | |
validTo | string | yes |
smartLocks.nukiGetConfig
Owner config view (never returns the token — only its hint). Read-only query.
Input parameters
Returns object.
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | yes | |
tokenHint | string · nullable | yes | |
smartlockId | string · nullable | yes | |
smartlockName | string · nullable | yes |
smartLocks.tedeeGetConfig
Owner config view (never returns the PAK — only its hint). Read-only query.
Input parameters
Returns object.
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
credentialsHint | string · nullable | yes |
smartLocks.ttlockGetConfig
Owner config view (never returns credentials — only the hint). Read-only query.
Input parameters
Returns object.
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
enabled | boolean | yes | |
credentialsHint | string · nullable | yes | |
lockId | string · nullable | yes | |
lockName | string · nullable | yes |
smartLocks.unlockErgebnis
Did Nuki confirm the opening triggered by this click? (B2) `offen` = no result yet (the job runs ~10 s after the click). Like `unlock`: requires the smart_locks module and an operator role (owner/staff/reception); reads via `withSystem`. Read-only query.
Input parameters
| Field | Type | Required | Notes |
|---|---|---|---|
doorId | string | yes | |
geklicktAm | string | yes |
Output fields
| Field | Type | Required | Notes |
|---|---|---|---|
ergebnis | enum | yes | One of: offen, bestaetigt, unbestaetigt |