Node-RED

Daten lesen und schreiben, auf Änderungen reagieren, Buchungszeitplan, Check-in am Leser und eigene Schlösser mit node-red-contrib-inwendo-erp.

Das Paket node-red-contrib-inwendo-erp verbindet Node-RED mit vynst (inwendo ERP). Es eignet sich besonders für Technik vor Ort: Relais, Türöffner, Shelly, GPIO, Kartenleser, Thermostate. Node-RED kann hinter einem normalen Router laufen; Befehle von vynst kommen über den MQTT-Broker von vynst an.

Installation

cd ~/.node-red
npm install node-red-contrib-inwendo-erp

Oder im Editor über Palette verwalten → Installieren. Nötig ist Node.js 18 oder neuer.

Nodes

Fehler von vynst werfen die Nodes mit Fehlercode und Text (X-IW-ERROR-CODE, X-IW-ERROR-JSON); fangt sie mit einem catch-Node.

API-Token

Legt einen langlebigen Token unter Einstellungen → API-Zugänge an. Je nach Nodes braucht er:

Beschränkt den Token am besten auf den Pfad /api/nodered/.* plus die Bereiche, die eure Flows lesen.

Auf Änderungen reagieren

Der Trigger meldet beim Deploy einen Webhook an (POST /api/nodered/webhook) und bekommt Ereignisse auf zwei Wegen:

Änderungen, die Node-RED selbst macht, schickt vynst nicht zurück: die Nodes senden X-IW-Trigger-Source: nodered.

Buchungszeitplan

Für Heizung, Licht und Türen zur richtigen Zeit:

{
  "type": "booking_start",
  "due_at": "2026-10-11T18:00:00+02:00",
  "booking_id": 123,
  "booking_title": "Training U12",
  "bookable_id": 7,
  "bookable_name": "Halle 1",
  "participants": 14,
  "pre_start_minutes": 30,
  "post_end_minutes": 15
}

Typen sind booking_pre_start, booking_start, booking_end und booking_post_end. Am zuverlässigsten schickt vynst die Ereignisse selbst (Einstellung integration_booking_timed_events_enabled). vynst prüft jede Minute, schickt nie doppelt und überspringt abgesagte Buchungen. Vorlauf und Nachlauf kommen aus den Feldern automation_pre_start_minutes und automation_post_end_minutes des Raums, sonst aus den Einstellungen (30 und 15 Minuten). Ohne die Einstellung liest Node-RED die Buchungen selbst.

Check-in am Eingang

Der Leser liefert eine Kartennummer, Mitgliedsnummer oder den QR-Code der digitalen Mitgliedskarte:

Abgelehnte Scans kommen am zweiten Ausgang mit Grund an, etwa unknown_person, scanned_too_often oder no_employment_contract.

Eigene Schlösser

1. Einen inwendo erp lock-Node anlegen und eine lock bridge dafür. Instanz-ID und Schlüssel entstehen automatisch.
2. Jedem Schloss eine eindeutige Lock ID und den Namen in vynst geben. In der App erscheint ein Öffnen-Knopf oder ein QR-Code, den ein Scanner an der Tür prüft.
3. Deployen. Die Bridge meldet ihre Schlösser bei vynst an (/api/nodered/smart_lock/register). In vynst erscheint eine Smartlock-Verbindung vom Anbieter Node-RED. Dort einmal Geräte synchronisieren und Rechte vergeben.
4. Den Ausgang des Lock-Nodes an euer Relais hängen. Den Zustand (locked, unlocked, open, jammed) meldet ihr über den Eingang zurück.

Jeder Befehl ist mit HMAC-SHA256 signiert (X-IW-Signature), trägt Zeitstempel und Nonce und wird höchstens 30 Sekunden nach dem Tippen in der App ausgeführt. Haltet die Uhr des Node-RED-Rechners per NTP synchron.

Zutritt am Leser prüfen

Was der Leser liest, geht in inwendo erp access check (POST /api/nodered/smart_lock/check_access). vynst prüft mit denselben Regeln wie die App und schreibt ins Schloss-Protokoll:

Die reine Mitgliedsnummer wird nicht angenommen, weil sie zu erraten ist. Die Antwort:

{
  "granted": true,
  "reason": "granted",
  "credential_type": "card",
  "smart_lock": { "id": 12, "name": "Haupteingang" },
  "person": { "id": 345, "name": "Erika Mustermann" },
  "opened": null
}

Mit „vynst öffnet das Schloss“ öffnet vynst bei Erfolg selbst, zum Beispiel eine Nuki-Tür mit Kartenleser an Node-RED.

Beispiel-Flows

Unter Importieren → Beispiele → node-red-contrib-inwendo-erp: Tür mit Leser, Halle vor der Buchung heizen, Flutlicht während Buchungen, RFID-Leser mit Relais, Check-in am Eingang, virtuelle Schlösser.

Virtuelle Schlösser ausprobieren

Ohne Hardware testen, wie Schlösser aus Node-RED in vynst funktionieren: Der Flow vynst-virtuelle-schloesser.json bringt zwei virtuelle Schlösser hinter einer MQTT-Bridge mit, eine Tür mit Öffnen-Knopf in der App und einen Fitnessraum mit QR-Scanner. Genau dieser Flow läuft in den automatischen Tests von vynst in einem echten Node-RED.

1. In Node-RED Importieren wählen und die Datei hochladen (oder ihren Inhalt einfügen).
2. Den Node inwendo ERP öffnen: Adresse eurer Instanz und einen API-Token mit dem Recht Veranstaltungen (event) schreiben eintragen.
3. Die Bridge Vereinsheim (virtuell) einmal öffnen und mit Fertig schließen. Dabei entstehen Instanz-ID und Schlüssel.
4. Deployen. In der Verwaltung von vynst unter SmartLock-Verbindungen die neue Node-RED-Verbindung öffnen, Geräte synchronisieren und Rechte vergeben.
5. In der App Öffnen tippen. Der Befehl kommt über den MQTT-Broker von vynst an, das virtuelle Schloss öffnet, bestätigt und schließt nach 5 Sekunden wieder ab. Den neuen Zustand meldet es an vynst zurück.

Die Function-Nodes „virtual lock …“ ersetzt ihr später durch euer Relais (GPIO, Shelly, Modbus …), den Inject-Node durch euren Leser.

Funktionen hinter Schaltern

Ist eine Funktion in vynst aus, antwortet die API mit HTTP 400, X-IW-ERROR-CODE: 404 und ["feature disabled: <einstellung>"]. Der Node zeigt dann „Funktion im ERP deaktiviert“. Die Schalter stehen unter Einstellungen → Smart Home & Automationen.

API

Die Endpunkte unter /api/nodered/ stehen im Bereich Smart Home und Automationen. Quellcode: github.com/inwendo/node-red-contrib-inwendo-erp.