Node-RED

Read and write data, react to changes, use the booking schedule, check in at the reader and offer your own locks with node-red-contrib-inwendo-erp.

The package node-red-contrib-inwendo-erp connects Node-RED with vynst (inwendo ERP). It is especially suited to on-site hardware: relays, door openers, Shelly, GPIO, card readers and thermostats. Node-RED can run behind a normal router. Commands from vynst arrive via vynst’s MQTT broker.

Installation

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

Or in the editor, via Manage palette → Install (Palette verwalten → Installieren). Node.js 18 or later is required.

Nodes

When vynst returns an error, the nodes throw it with an error code and text (X-IW-ERROR-CODE, X-IW-ERROR-JSON). Catch them with a catch node.

API token

Create a long-lived token under Settings → API access (Einstellungen → API-Zugänge). Depending on the nodes you use, it needs:

It is best to restrict the token to the path /api/nodered/.* plus the areas your flows read.

Reacting to changes

When deployed, the trigger registers a webhook (POST /api/nodered/webhook) and receives events in one of two ways:

vynst does not send back changes that Node-RED makes itself: the nodes send X-IW-Trigger-Source: nodered.

Booking schedule

For heating, lights and doors at the right time:

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

The types are booking_pre_start, booking_start, booking_end and booking_post_end. Most reliably, vynst sends the events itself (setting integration_booking_timed_events_enabled). vynst checks every minute, never sends an event twice and skips cancelled bookings. Lead and follow-up times come from the fields automation_pre_start_minutes and automation_post_end_minutes of the room, otherwise from the settings (30 and 15 minutes). Without that setting, Node-RED reads the bookings itself.

Check-in at the entrance

The reader supplies a card number, a member number or the QR code of the digital member card:

Rejected scans arrive at the second output with a reason, such as unknown_person, scanned_too_often or no_employment_contract.

Your own locks

1. Create an inwendo erp lock node and a lock bridge for it. The instance ID and key are created automatically.
2. Give each lock a unique Lock ID and a name in vynst. The app shows an Open button or a QR code that a scanner at the door checks.
3. Deploy. The bridge registers its locks with vynst (/api/nodered/smart_lock/register). A smart lock connection from the provider Node-RED then appears in vynst. There, sync the devices once with Sync devices and grant rights.
4. Connect the lock node’s output to your relay. Report the state (locked, unlocked, open, jammed) back via the input.

Every command is signed with HMAC-SHA256 (X-IW-Signature), carries a timestamp and a nonce, and is executed at most 30 seconds after the tap in the app. Keep the clock on the Node-RED machine synchronised via NTP.

Checking access at the reader

What the reader reads goes into inwendo erp access check (POST /api/nodered/smart_lock/check_access). vynst applies the same rules as the app and writes to the lock log:

A plain member number is not accepted, because it can be guessed. The response looks like this:

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

With the option “vynst opens the lock” enabled, vynst opens the lock itself on success, for example a Nuki door with a card reader connected to Node-RED.

Example flows

Under Import → Examples → node-red-contrib-inwendo-erp (Importieren → Beispiele → node-red-contrib-inwendo-erp) you will find: door with reader, heating the hall before a booking, floodlights during bookings, RFID reader with relay, check-in at the entrance, and virtual locks.

Try virtual locks

Try how locks from Node-RED work in vynst without any hardware: the flow vynst-virtuelle-schloesser.json brings two virtual locks behind an MQTT bridge, a door with an Open button in the app and a gym with a QR scanner. vynst’s automated tests run exactly this flow in a real Node-RED.

1. In Node-RED choose Import and upload the file (or paste its content).
2. Open the inwendo ERP node: enter the address of your installation and an API token with the right events (event) write.
3. Open the bridge Vereinsheim (virtuell) once and close it with Done. This creates the instance ID and the secret.
4. Deploy. In the vynst administration open the new Node-RED connection under SmartLock-Verbindungen (smart lock connections), press Sync devices and grant rights.
5. Tap Open in the app. The command arrives over the vynst MQTT broker, the virtual lock opens, confirms and locks itself again after 5 seconds. It reports the new state back to vynst.

Later, replace the function nodes “virtual lock …” with your relay (GPIO, Shelly, Modbus …) and the inject node with your reader.

Features behind switches

If a feature is off in vynst, the API responds with HTTP 400, X-IW-ERROR-CODE: 404 and ["feature disabled: <setting>"]. The node then shows the status “Funktion im ERP deaktiviert” (function disabled in the ERP). The switches are under Settings → Smart home & automation (Einstellungen → Smart Home & Automationen).

API

The endpoints under /api/nodered/ are listed under Smart home and automation. Source code: github.com/inwendo/node-red-contrib-inwendo-erp.