API und Integrationen mit Software von Drittanbietern

Das technische Schema ist einfach und robust: Sie können Ihre Software an die API-Schicht Ihrer Installation anbinden und diese eigenständig verwalten.

Die API-Struktur ermöglicht es Ihnen, Vorgänge durchzuführen, die nahezu alle Funktionen des Manage-Panels simulieren, das im Lieferumfang des KITs enthalten ist. Alle Aufrufe müssen aktiviert sein und von einer autorisierten IP-Adresse stammen.

Im Folgenden finden Sie die vollständige Anleitung zu allen verfügbaren Aufrufen, gegliedert nach Funktionsbereich. Dieselbe Dokumentation ist auch in interaktiver Form auf Postman verfügbar: hier klicken!.

Hinweis: Es ist auch eine erweiterte Version des API-Dienstes verfügbar (API PRO), mit der Sie die Logs der API-Aufrufe einsehen und den Öffnungsaufruf aus der Ferne durchführen können — siehe den Abschnitt API Pro oder kontaktieren Sie uns, um mehr zu erfahren.

Praktische Beispiele für die Integration mit Buchungssystemen, PMS, Zahlungs- und Reservierungsplattformen finden Sie unter Häufigste Integrationen: So geht’s.

Authentifizierung

Alle Aufrufe (mit Ausnahme der Statusprüfung) erfordern ein Bearer-Token, das über den Aufruf authorize erhalten und als Header in den nachfolgenden Anfragen übergeben wird.

• Das Token ist 1 Stunde gültig: Es muss regelmäßig durch Wiederholung des Aufrufs authorize erneuert werden.
• Es gibt keine Begrenzung der Anzahl der Aufrufe, die Sie durchführen können.
• Mögliche Fehler beim Aufruf authorize: nicht autorisierte IP-Adresse oder falscher secret_key (invalid_access), falsche Anmeldedaten (invalid_credentials), allgemeiner Fehler (could not create token).
• Mögliche Fehler bei den übrigen Aufrufen: Token abgelaufen, ungültig oder nicht vorhanden (invalid_token). Etwaige spezifische Fehler werden im Feld messages der JSON-Antwort angegeben.

POST /api/v2/authorize — Token abrufen

Gibt das Bearer-Token zurück, das für alle nachfolgenden Aufrufe verwendet werden soll.

• Erforderliche Parameter: email (E-Mail-Adresse des Bedieners), password (Passwort des Bedieners), secret_key (der autorisierten IP-Adresse zugeordnet, zu finden im Panel im Bereich API / Setup)
• Antwort 200: token
• Antwort 401: invalid_credentials (falsche E-Mail-Adresse oder Passwort), invalid_credentials2 (nicht autorisierte IP-Adresse oder falscher secret_key), invalid_access1 (secret_key fehlt)

GET /api/v2/ — Statustest

Prüft, ob das Panel aktiv und funktionsfähig ist (gibt Test aus). Erfordert keine Authentifizierung und keine Parameter.

Benutzer

PUT /api/v2/adduser — Neuen Benutzer anlegen

Legt einen neuen Benutzer im Panel an.

• Erforderliche Parameter: name (Vorname), surname (Nachname)
• Optionale Parameter: email, phone, prefix (URL-codierte Landesvorwahl, z. B. +39 → %2b39), tags (Array; jedes Komma wird durch einen Unterstrich ersetzt), status (1 = aktiviert, 0 = deaktiviert), fields (Array benutzerdefinierter Zusatzfelder im Format fields[id_campo]=valore)

PUT /api/v2/updateuser — Benutzer bearbeiten

Aktualisiert die Daten eines bestehenden Benutzers.

• Erforderliche Parameter: user_id, name, surname
• Optionale Parameter: email, phone, prefix, tags, status (1 = aktiviert, 0 = deaktiviert), fields (Array von Zusatzfeldern, gleiches Format wie bei AddUser)

DELETE /api/v2/deleteuser — Benutzer löschen

Löscht einen Benutzer aus dem Panel.

• Erforderliche Parameter: user_id
• Antwort 200: Benutzer erfolgreich gelöscht
• Antwort 400: Benutzer nicht gefunden

GET /api/v2/getusers — Benutzerliste

Gibt die Daten aller im Panel vorhandenen Benutzer zurück, oder eines bestimmten, wenn der optionale Parameter übergeben wird.

• Optionale Parameter: user_id, tags (filtert Benutzer nach Tag), getGrantInfo (wenn 1, werden auch die Details der zugehörigen Zugänge einbezogen)
• Antwort 404: kein Benutzer gefunden

GET /api/v2/users/getStatus — Benutzerstatus

Gibt zurück, ob ein Benutzer aktiviert oder deaktiviert ist.

• Parameter: user_id

POST /api/v2/users/changeStatus — Benutzerstatus ändern (noch nicht verfügbar)

Bei status = 1 wird der Benutzer für Zugänge aktiviert, bei status = 0 deaktiviert.

• Parameter: user_id, status (1 = aktiviert, 0 = deaktiviert)

Gruppen

GET /api/v2/getGroup — Gruppenliste

Gibt die Daten aller im Panel vorhandenen Gruppen zurück, oder einer oder mehrerer bestimmter, wenn der optionale Parameter übergeben wird.

• Optionale Parameter: group_id (kann ein Array sein)
• Antwort 404: keine Gruppe gefunden

POST /api/v2/grantAccessGroup — Zugang zu einer Gruppe aktivieren

Aktiviert den Zugang eines oder mehrerer Benutzer zu einer oder mehreren angegebenen Gruppen und erstellt die Benutzer-Gruppen-Zuordnung.

• Erforderliche Parameter: user_id (kann ein Array sein), group_id (kann ein Array sein)
• Antwort 200: Zuordnungen erfolgreich erstellt
• Antwort 400: Benutzer nicht gefunden, Gruppe nicht gefunden, Zuordnung bereits vorhanden

POST /api/v2/dropAccessGroup — Zugang zu einer Gruppe entziehen

Entzieht die Zugangsberechtigungen eines Benutzers, der einer Gruppe zugehört, und entfernt die Benutzer-Gruppen-Zuordnung.

• Erforderliche Parameter: user_id (kann ein Array sein), group_id (kann ein Array sein)
• Antwort 200: Zuordnungen erfolgreich entfernt
• Antwort 400: Zuordnung nicht vorhanden, Gruppe nicht gefunden, Benutzer nicht gefunden

Guthaben

GET /api/v2/getcredits — Guthabenstand

Gibt das verfügbare Guthaben zurück.

GET /api/v2/getprices — Preisliste

Gibt die Preisliste für das Aufladen des Guthabens zurück.

POST /api/v2/recharge — Guthaben aufladen

Führt eine Guthabenaufladung durch.

• Parameter: user_id, amount (z. B. 10.50)

Schlüssel

GET /api/v2/getunusednfc — Freie NFC-Schlüssel

Gibt die Liste der NFC-Schlüssel zurück, die keinem Benutzer zugeordnet sind. Kein Parameter erforderlich.

• Antwort 404: kein freier NFC-Schlüssel gefunden

GET /api/v2/getallnfc — Liste der NFC-Schlüssel

Gibt die Daten zu allen im Panel vorhandenen NFC-Schlüsseln zurück, unabhängig davon, ob sie zugeordnet sind oder nicht.

• Optionale Parameter (Paginierung): limit, offset
• Antwort 400: kein Schlüssel gefunden, oder offset ohne limit verwendet

PUT /api/v2/addkey — NFC-Schlüssel hinzufügen

Fügt einen neuen NFC-Schlüssel hinzu.

• Erforderliche Parameter: nfc_key_code (RFID-Code, gelesen mit einem Standardlesegerät: wird gemäß dem LabKey-Standard umgewandelt — verwenden Sie keinen Code aus einem Zugangslog), nfc_key_name (dem Schlüssel zuzuordnender Name)
• Optionale Parameter: force_hex (erzwingt die Umwandlung des Codes aus einer Hexadezimalzeichenkette; wenn nicht angegeben, erfolgt die Umwandlung automatisch nur, wenn der Code mindestens einen Buchstaben enthält)

PUT /api/v2/addkey2user — NFC-Schlüssel einem Benutzer zuordnen

Ordnet einen NFC-Schlüssel einem bestimmten Benutzer zu.

• Erforderliche Parameter: user_id, nfc_key_id
• Antwort 400: Schlüssel bereits zugewiesen
• Antwort 404: Schlüssel nicht gefunden, Benutzer nicht gefunden

DELETE /api/v2/deletekey — NFC-Schlüssel löschen

Löscht einen NFC-Schlüssel.

• Erforderliche Parameter: nfc_key_code (gemäß LabKey-Standard umgewandelter RFID-Code, z. B. 1234567890 → 210215073)
• Antwort 404: Schlüssel nicht vorhanden
• Antwort 400: nfc_key_code fehlt

GET /api/v2/getnfcdetails — Details eines NFC-Schlüssels

Gibt die Details zu einem NFC-Schlüssel zurück.

• Erforderliche Parameter: nfc_key_code (gemäß LabKey-Standard umgewandelter Code)
• Antwort 404: kein Benutzer mit dem Schlüssel verbunden, NFC-Schlüssel nicht gefunden
• Antwort 400: Parameter fehlen

POST /api/v2/editnfc — NFC-Schlüssel bearbeiten

Bearbeitet die Details eines NFC-Schlüssels.

• Erforderliche Parameter: nfc_key_code, name
• Antwort 404: nfc_key_code nicht gefunden oder fehlt, name fehlt

POST /api/v2/edittastierino — Tastenfeld-Code ändern

Ändert den Code eines Tastenfelds (Pinpad).

• Erforderliche Parameter: old_pinpad_key_code (alter, zu ersetzender Code), new_pinpad_key_code (neuer Code)
• Antwort 200: Code korrekt aktualisiert
• Antwort 404: der alte Code existiert nicht
• Antwort 400: der Code muss numerisch sein

POST /api/v2/updatepinpad — Tastenfeld-Code für Benutzer aktualisieren

Aktualisiert den Tastenfeld-Code über die Auswahl des Benutzers.

• Erforderliche Parameter: user_id, new_pinpad_key_code
• Antwort 404: Benutzer nicht vorhanden
• Antwort 400: der Code muss numerisch sein, Schlüssel bereits vorhanden

POST /api/v2/getqrcode — QR-Code erzeugen

Erzeugt einen QR-Code für den ausgewählten Benutzer, verwendbar ausgehend von der „message string".

• Erforderliche Parameter: user_id
• Optionale Parameter: image (wenn 1, wird das QR-Code-Bild base64-codiert zurückgegeben), with_background (erfordert image=1; wenn 1, wird dem Bild ein dekorativer Hintergrund hinzugefügt)
• Antwort 404: Benutzer nicht gefunden

POST /api/v2/getfasturl — Fast URL erzeugen

Erzeugt die Fast URL für den ausgewählten Benutzer, verwendbar ausgehend vom Feld „fast_url".

• Erforderliche Parameter: user_id
• Antwort 404: Benutzer nicht gefunden

GET /api/v2/getallpinpad — Liste der Tastenfeld-Codes

Gibt alle Tastenfeld-Codes und die zugehörigen Details zurück.

• Optionale Parameter (Paginierung): limit, offset
• Antwort 400: entweder sowohl limit als auch offset setzen oder beide leer lassen; limit/offset müssen Ganzzahlen sein

Zugänge und Berechtigungen

POST /api/v2/getGrantInfo — Details eines Zugangs

Gibt die Daten zum angegebenen Zugang zurück.

• Erforderliche Parameter: involved_associations (eine oder mehrere vom Aufruf grantaccess zurückgegebene IDs)
• Antwort 200: Informationen zum Benutzer und, für jede zugeordnete LabKey, die Details des Zugangs
• Antwort 400: es muss mindestens eine gültige involved_associations gesendet werden
• Antwort 404: Zeile mit dieser involved_associations nicht gefunden

POST /api/v2/automategetGrantInfo — Vereinfachte Zugangsdetails

Komfortaufruf zur Vereinfachung der Nutzung von getGrantInfo.

• Optionale Parameter: user_id (kann ein Array sein), unique_name (kann ein Array sein — Name der ausgewählten LabKey)

GET /api/v2/getuservarcodetails — Details der Zugangspunkte eines Benutzers

Gibt alle Details zu den Zugangspunkten zurück, die dem ausgewählten Benutzer zugeordnet sind.

• Erforderliche Parameter: user_id

POST /api/v2/grantaccess — Zugang aktivieren

Aktiviert den Zugang eines Benutzers. Um eine Kombination mehrerer Technologien (NFC, Tastenfeld, Barcode) zu konfigurieren, kann diese API mehrmals mit unterschiedlicher key_id aufgerufen werden.

• Erforderliche Parameter: user_id, key_id (ID des dem Benutzer zugeordneten Zugangsschlüssels: nfc_key_id für NFC/Pocket, pinpad_key_id für Tastenfeld/Barcode verwenden), data (JSON-Zeichenkette mit den Parametern jedes Zugangspunkts: Datumsbereich datei/datef, Uhrzeiten houri/hourf, Wochentage mo,tu,we,th,fr,sa,su, Feiertage tv, command_device_id, id_rele, technology)
• Optionale Parameter: check_overalapping, force_same_idrele_commanddeviceid

POST /api/v2/editaccess — Zugang bearbeiten

Komfortaufruf, der nacheinander dropaccess und grantaccess ausführt und eine neue involved_associations für den Benutzer zurückgibt. Kein atomarer Vorgang: Wenn dropaccess erfolgreich abgeschlossen wird, grantaccess jedoch fehlschlägt, bleiben die Zuordnungen trotzdem gelöscht.

• Erforderliche Parameter: involved_associations (kann ein Array sein), user_id, key_id, data (JSON-Zeichenkette, gleiches Format wie bei GrantAccess)

DELETE /api/v2/dropaccess — Zugang entziehen

Entzieht die Zugangsberechtigungen.

• Erforderliche Parameter: involved_associations (aus der Antwort von grantaccess erhaltener Code)

POST /api/v2/isAccessible — Zugänglichkeit eines Zugangspunkts prüfen

Prüft, ob ein Zugangspunkt in einem bestimmten Zeitraum zugänglich ist.

• Erforderliche Parameter: unique_name, from_date (Zeitstempel), to_date (Zeitstempel), id_rele

Zählerverwaltung (Anti-Passback)

GET /api/v2/antipassback/ — Zählerdetails

Gibt die Details zur Zählerverwaltung für den angegebenen Benutzer und Zugangspunkt zurück. Die Antwort ist ein Array mit den Details für jedes Relais.

• Parameter: user_id, unique_name
• Felder der Antwort: is_active (1/0, Zähler aktiv oder nicht), has_total/number_total (Gesamtzugangslimit), has_day/number_day (Tageslimit), has_week/number_week (Wochenlimit), has_month/number_month (Monatslimit)

POST /api/v2/antipassback/update_or_create — Zähler einstellen

Erstellt oder aktualisiert die Zählerkonfiguration für ein oder mehrere Relais.

• Parameter: user_id, data (JSON-Zeichenkette mit den Feldern is_active, has_total/number_total, has_day/number_day, has_week/number_week, has_month/number_month für jede LabKey und jedes Relais)
• Hinweis: Wenn is_active gesetzt ist, kann nur eines von has_total, has_day, has_week oder has_month aktiviert werden — eine gleichzeitige Aktivierung ist nicht möglich.

Allgemein

GET /api/v2/getlabkeys — Liste der LabKeys

Gibt die Details der Steuergeräte/LabKeys zurück.

• Optionale Parameter: unique_name, labkey_id, key_tipe
• Antwort 400: keine LabKey gefunden

GET /api/v2/getbuildings — Liste der Standorte

Gibt die Informationen zu den dem Panel zugeordneten Standorten zurück.

• Optionale Parameter: structure_id, structure_name, referent

GET /api/v2/getlogs — Zugangsprotokolle

Gibt die Zugangsprotokolle zurück.

• Optionale Parameter: from (Startdatum), to (Enddatum), unique_name (Name der LabKey), labkey_id, user_id, limit (Paginierung), offset (Paginierung)

POST /api/v2/sendemail — E-Mail senden

Sendet eine E-Mail an einen Kunden, zum Beispiel mit den Zugangsdetails.

• Erforderliche Parameter: user_id (Empfänger), operator_email (Absender)
• Optionale Parameter: message (individuelle Nachricht; wenn nicht angegeben, wird eine Standardnachricht gesendet), cc_emails (Array von Adressen in Kopie), show_sender_name, send_permissions_list, send_fast_url, send_qr_code

WebHooks

Alerts — Echtzeit-Benachrichtigungen

Ermöglicht den Empfang automatischer Benachrichtigungen an einen eigenen Endpunkt, sobald ein Ereignis eintritt (z. B. ein Zugang). Der Webhook wird im Manage-Panel im Bereich Alert → Alert Standard konfiguriert.

• An den eigenen Endpunkt in der Query-String gesendete Parameter: user_id, full_name, id_log, key_code, result_boolean (Zugang erlaubt oder nicht), timestamp, is_log_offline, unique_name, labkey_id, tags, event_type

Zusatzfelder

Verwaltung der benutzerdefinierten Felder, die dem Benutzerstammdatensatz zugeordnet werden können (siehe auch Neuen Benutzer anlegen).

GET /api/v2/customfields — Feldliste

Gibt die Liste der Zusatzfelder mit den zugehörigen Attributen zurück.

• Optionale Parameter (Paginierung): limit, offset

GET /api/v2/customfields/{id_field} — Felddetail

Gibt die Details eines bestimmten Zusatzfelds zurück.

GET /api/v2/customfields/count — Feldanzahl

Gibt die Anzahl der gespeicherten Zusatzfelder zurück.

POST /api/v2/customfields/create — Feld erstellen

Erstellt ein neues Zusatzfeld.

• Erforderliche Parameter: type_field (text oder date), name_field (max. 255 Zeichen)
• Optionale Parameter: order (numerisch), is_required (1 = bei der Benutzererfassung erforderlich), can_disable_user (1 = ja; nur mit type_field=date verwendbar — das System deaktiviert den Benutzer automatisch um Mitternacht, wenn das eingegebene Datum in der Vergangenheit liegt)

POST /api/v2/customfields/{id_field}/update — Feld bearbeiten

Aktualisiert ein bestehendes Zusatzfeld. Gleiche Parameter wie bei create.

Zusatzfelder des Benutzers

GET /api/v2/customfieldsuser/{id_user}/ — Feldliste für Benutzer

Gibt alle für einen Benutzer ausgefüllten Zusatzfelder zurück.

• Optionale Parameter (Paginierung): limit, offset

GET /api/v2/customfieldsuser/{id_user}/{id_field} — Feldwert für Benutzer

Gibt den Wert eines bestimmten Zusatzfelds für den angegebenen Benutzer zurück.

POST /api/v2/customfieldsuser/{id_user}/{id_field}/create — Feldwert festlegen

Erstellt den Wert eines Zusatzfelds für den Benutzer.

• Erforderliche Parameter: value (max. 255 Zeichen)
• Optionale Parameter: can_disable_user (0 = nein, 1 = ja)

POST /api/v2/customfieldsuser/{id_user}/{id_field}/update — Feldwert aktualisieren

Aktualisiert den Wert eines Zusatzfelds für den Benutzer. Gleiche Parameter wie bei create.

Vorlagen

Verwaltung vordefinierter Vorlagen für wiederkehrende Zugänge (siehe auch Vorlagen).

GET /api/v2/templates/count — Vorlagenanzahl

Gibt die Anzahl der gespeicherten Vorlagen zurück.

GET /api/v2/templates/ — Vorlagenliste

Gibt die Liste der Vorlagen zurück.

• Optionale Parameter (Paginierung): limit, offset

GET /api/v2/templates/detail — Vorlagendetail

Gibt das Detail einer bestimmten Vorlage zurück.

• Parameter: template_id

POST /api/v2/templates/addAccessUser — Vorlage auf Benutzer anwenden

Wendet eine Zugangsvorlage auf einen Benutzer an. Es gibt zwei Möglichkeiten: Angabe von sowohl timestamp_start als auch timestamp_end (das System legt Beginn und Ende des Zugangs auf diese Werte fest), oder Angabe nur von timestamp_start, wobei das System das Ende automatisch anhand der Vorlageneinstellungen berechnet.

• Erforderliche Parameter: user_id, template_id
• Optionale Parameter: timestamp_start (Standard: jetzt), timestamp_end

Feiertage

Verwaltung der Feiertage (siehe auch Feiertage): Während der konfigurierten Zeiträume öffnen die ausgewählten Zugangspunkte nur für zugelassene Benutzer.

GET /api/v2/festivita — Feiertagsliste

Gibt alle Feiertage zurück, oder einen bestimmten, wenn die ID übergeben wird.

• Optionale Parameter: id
• Antwort 404: Feiertag nicht gefunden

GET /api/v2/festivita/count — Feiertagsanzahl

Gibt die Anzahl der konfigurierten Feiertage zurück.

• Optionale Parameter: id
• Antwort 400: ungültige oder fehlende Parameter

GET /api/v2/festivita/is_holiday — Feiertag prüfen

Prüft, ob ein bestimmtes Datum/eine bestimmte Uhrzeit in einen Feiertagszeitraum fällt.

• Erforderliche Parameter: datetime (Format YYYY-MM-DD HH:MM:SS)
• Optionale Parameter: unique_name, labkey_id, rele (Array), user_id
• Antwort 200: is_holiday (boolescher Wert)
• Antwort 400: ungültige oder fehlende Parameter

POST /api/v2/festivita/create — Feiertag erstellen

Erstellt einen neuen Feiertag.

• Erforderliche Parameter: title, start_datetime (Format YYYY-MM-DD HH:MM:SS), end_datetime (Format YYYY-MM-DD HH:MM:SS)
• Optionale Parameter: description, recurring (1 = jährlich wiederkehrend), notification_email, monday…sunday (1 = an diesem Tag aktiv), varcos (JSON-Array der betroffenen labkey_id/rele), user_ids (Array der betroffenen Benutzer)

POST /api/v2/festivita/update — Feiertag bearbeiten

Aktualisiert einen bestehenden Feiertag. Gleiche optionale Parameter wie bei create.

• Erforderliche Parameter: id
• Optionale Parameter: title, start_datetime, end_datetime, recurring, active (1 = aktiviert, 0 = deaktiviert), notification_email, monday…sunday, varcos, user_ids

DELETE /api/v2/festivita/delete — Feiertag löschen

Löscht einen Feiertag.

• Erforderliche Parameter: id
• Antwort 200: Feiertag erfolgreich gelöscht
• Antwort 400: ungültige oder fehlende Parameter
• Antwort 404: Feiertag nicht gefunden