Gerätedaten in Ihr SaaS integrieren

Anwendungsfall

Verwenden Sie dieses Muster, wenn WLTE-Gerätefähigkeiten Teil Ihres eigenen Produkts sind (Multi-Tenant-SaaS, internes Betriebssystem oder Ähnliches). Ihre Endnutzer interagieren mit Ihrem Produkt und Ihrem eigenen Kontosystem — sie kommen niemals direkt mit WLTE-Zugangsdaten in Berührung.

• Ein einziges WLTE-Konto und ein einziger API Client bedienen Ihre gesamte Bereitstellung, nicht separate Zugangsdaten pro Endkunde.
• Geräte innerhalb eines WLTE-Kontos sind flach; es gibt kein Mandantenkonzept (Tenant). Welche Geräte zu welchem Kunden gehören, ist eine Zuordnung, die Sie selbst erstellen und pflegen.
• Live-Ereignisse sollten kontinuierlich in Ihre eigene Datenpipeline fließen (Datenbank, Message Queue, eigener WebSocket oder Webhook), statt dass jede Seite jedes Endkunden eine eigene Verbindung zu WLTE hält.

Geben Sie niemals clientId, clientSecret oder Access Token an den Endkunden weiter. Nehmen Sie nicht an, dass Geräte innerhalb eines Kontos mandantenisoliert sind — das sind sie nicht.

Empfohlene Architektur

Nur Ihr Backend speichert WLTE-Zugangsdaten. Führen Sie die Zuordnung deviceId → tenantId, bedienen Sie alle Mandanten über eine einzige WebSocket-Verbindung und verteilen Sie Daten über den Rest Ihres Systems.

Schrittweise Umsetzung

1. Entwerfen und pflegen Sie die Zuordnung deviceId → tenantId (oder Ihre eigene Kunden-/Objekt-ID). WLTE-Konten unterscheiden nicht zwischen Mandanten — diese Tabelle ist die zentrale Datenstruktur der gesamten Integration.
2. Erhalten Sie ein Access Token von Ihrem einzigen, serverseitig gespeicherten API Client: device:read für reine Lesenutzung, plus device:control oder device:config, wenn Sie Befehle senden.
3. Rufen Sie Geräte auflisten (auf Englisch) und Gerätetypdefinitionen auflisten (auf Englisch) auf, um den anfänglichen Basiszustand aufzubauen, und teilen Sie ihn dann anhand Ihrer Zuordnungstabelle in Ansichten pro Mandant auf.
4. Erstellen Sie ein einmaliges WebSocket-Ticket (auf Englisch) und stellen Sie eine einzige Verbindung her — nicht eine pro Mandant —, um Verbindungsereignisse, Zustandsänderungsereignisse und Stromereignisse (alle auf Englisch) zu empfangen.
5. Suchen Sie bei jedem Ereignis zuerst den Mandanten anhand der deviceId, schreiben Sie dann in Ihren eigenen Speicher oder Ihre Warteschlange, damit Ihre API/WebSocket/Webhook dies an die Kunden dieses Mandanten liefern kann.
6. Wenn ein Endkunde eine Steueranfrage sendet, autorisieren Sie sie zuerst in Ihrem eigenen Berechtigungssystem (Ihre produktspezifischen Rechte pro Mandant, nicht der WLTE-Scope), und lassen Sie dann Ihr Backend die Anfrage mit einem Idempotenzschlüssel an WLTE weiterleiten.
7. Speichern Sie Befehlsergebnisse und Ereignisse selbst dauerhaft, wo Sie eine langfristige Speicherung oder eine Aufzeichnung für die Abrechnung benötigen — WLTE gibt keine Ereignishistorie erneut wieder, und Befehlsdatensätze werden nur kurzzeitig aufbewahrt.

Wichtige Schnittstellen und Ereignisse

Zweck	Referenz
Basiszustand aufbauen	Geräte auflisten (auf Englisch)
Fähigkeitsbasierte Multi-Tenant-Ansichten	Gerätetypdefinitionen auflisten (auf Englisch)
Gerät zum Konto hinzufügen	Gerät zum Konto hinzufügen (auf Englisch)
WebSocket-Authentifizierung	WebSocket Ticket erstellen (auf Englisch)
Verbindungsänderungen	Geräteverbindungsereignisse (auf Englisch)
Peripheriezustandsänderungen	Ereignis für Gerätezustandsänderung (auf Englisch)
Benachrichtigungen über Stromverlust und -wiederherstellung	Gerätestromereignisse (auf Englisch)
Steuerbefehl weiterleiten	Relaisbefehl erstellen (auf Englisch)
Befehlsergebnis abfragen	Befehlsergebnis abrufen (auf Englisch)

Fehler und Wiederherstellung

• Ratenbegrenzungen werden auf Ebene des API Client gezählt. Mehrere Mandanten, die ein Konto teilen, teilen sich ein Ratenbegrenzungsbudget — ein hohes Anfragevolumen eines Mandanten kann das Kontingent des gesamten Kontos erschöpfen. Drosseln und stellen Sie daher auf Ihrer eigenen Ebene in die Warteschlange, statt die Anfragerate der Endkunden direkt an WLTE weiterzugeben.
• Verbinden Sie bei Verlust der WebSocket-Upstream-Verbindung nur diese eine serverseitige Verbindung neu, statt pro Mandant neu zu verbinden; markieren Sie nachgelagerte Daten während der Wiederverbindung als möglicherweise veraltet.
• Während der Trennung verpasste Ereignisse werden nicht erneut zugestellt. Stellen Sie den Basiszustand nach der Wiederverbindung über REST wieder her und setzen Sie dann die ereignisgesteuerten Aktualisierungen fort.
• Befehlsdatensätze und Idempotenzschlüssel werden auf WLTE-Seite etwa 48 Stunden lang aufbewahrt. Speichern Sie Befehlsergebnisse und Endstatus selbst dauerhaft, wenn Sie ein längeres Audit- oder Abrechnungsfenster benötigen.
• Warten Sie bei 429 RATE_LIMITED auf Retry-After. Implementieren Sie in Ihrem Dienst keine separate, unabhängige Wiederholungsschleife pro Mandant.

Überlegungen für die Produktion

• Endkunden dürfen unter keinen Umständen clientId, clientSecret oder Access Token von WLTE sehen oder erhalten — jeder WLTE-Aufruf muss über Ihr Backend laufen.
• Die vier WLTE-Berechtigungen (device:read/device:control/device:config/device:manage) sind grobe Rechte auf Kontoebene. Sie ersetzen nicht Ihr eigenes granulares Berechtigungsmodell pro Kunde — das sind zwei getrennte Autorisierungsebenen.
• Behandeln Sie die Zuordnung deviceId → tenantId als die wichtigste Tabelle in Ihrem System; halten Sie sie synchron, wann immer Geräte zum Konto hinzugefügt oder daraus entfernt werden oder wenn Kunden Objekte hinzufügen oder entfernen, um zu vermeiden, dass Daten beim falschen Mandanten landen.
• Planen Sie das Ratenbegrenzungsbudget im Voraus: Die Anzahl der Mandanten erhöht Ihr Anfragevolumen linear, aber die Ratenbegrenzung des Kontos wächst nicht mit.
• Siehe Berechtigungen (auf Englisch) für verfügbare Scope-Kombinationen und Ratenbegrenzungen und Wiederholungsversuche (auf Englisch) für Ratenbegrenzungsmessungen.

Nächste Schritte

• Geräteüberwachungs-Dashboard
• REST API oder WebSocket
• Berechtigungen (auf Englisch)
• Ratenbegrenzungen und Wiederholungsversuche (auf Englisch)