Einführung

Diese Seite legt das Grundmodell fest, bevor Sie mit der Integration beginnen. Sie listet nicht jeden Parameter jedes Endpunkts auf, sondern erklärt die wichtigsten Objekte, Anfragemuster, das Gerätezustandsmodell und den Befehlslebenszyklus, die WLTE OpenAPI verwendet.

Wenn Sie nur sofort die erste Anfrage ausführen möchten, gehen Sie zu Schnellstart.

Was ist WLTE OpenAPI?

WLTE OpenAPI ist für serverseitige Systeme konzipiert. Es ermöglicht Ihrer Plattform, WLTE-Geräte zu lesen, zu steuern und zu überwachen.

Typische Fähigkeiten umfassen:

• Auflisten der einem Konto zugänglichen Geräte
• Lesen des Zustands eines Geräts und seiner Peripheriedaten
• Laden von Gerätetypdefinitionen und unterstützten Vorgängen
• Senden von Relais-, RS485- und Konfigurationsbefehlen
• Abfragen von Befehlsergebnissen
• Empfangen von Echtzeit-Geräteereignissen über WebSocket

Grundlegende Konzepte

Konzept	Beschreibung
API Client	Die aufrufende Identität, erstellt in der Developer Console für eine Anwendung
clientId / clientSecret	Serverseitige Zugangsdaten zum Abrufen eines Access Tokens
Access Token	Kurzlebiges Token für den Aufruf geschützter Endpunkte
Gerät (Device)	Ein dem Konto zugängliches WLTE-Gerät
Gerätetyp (Device Type)	Definition, die unterstützte Peripherie und Vorgänge beschreibt
Peripheriezustand (Peripheral State)	Zustand von Relais, Digitaleingängen, Sensoren, Analogeingängen und anderer Peripherie
Befehl (Command)	Eine Anfrage zur Ausführung eines Gerätevorgangs, z. B. Relaissteuerung, RS485-Übertragung oder Konfigurationsaktualisierung
WebSocket-Ereignis	Echtzeitbenachrichtigung über Zustandsänderungen, Verbindungsänderungen, Stromereignisse und Ähnliches

Integrationsmodell

Ihr Server sollte clientSecret speichern und Access Token abrufen. Browser, mobile Apps und andere Clients sollten clientSecret nicht direkt speichern.

REST API und WebSocket

REST API und WebSocket ersetzen sich nicht gegenseitig. Sie erfüllen unterschiedliche Aufgaben.

Szenario	Empfohlene Methode
Access Token erhalten	REST API
Geräte auflisten	REST API
Gerätetypdefinitionen laden	REST API
Befehle an ein Gerät senden	REST API oder WebSocket, je nach Ihrem Verbindungsmodell
Befehlsergebnisse abfragen	REST API
Ein Gerät explizit aktualisieren	REST API GET /devices/{deviceId} oder WebSocket device.state.get
Verbindung, Trennung, Strom oder Zustandsänderungen überwachen	WebSocket

Verwenden Sie für die erste Integration REST API, um Authentifizierung, Geräteauflistung und eine Gerätezustandsabfrage zu überprüfen. Fügen Sie WebSocket hinzu, wenn Ihr Produkt Echtzeitereignisse benötigt.

Siehe REST API oder WebSocket für einen detaillierteren Vergleich.

Gerätezustandsmodell

Der Gerätezustand sollte je nach Anwendungsfall interpretiert werden.

Daten	Anwendungsfall	Beschreibung
Zustand aus der Geräteliste	Listenansichten, Dashboards, Hintergrundsynchronisierung	Bereits von der Plattform synchronisierte Daten, geeignet für Massenanzeigen
Echtzeitzustand eines einzelnen Geräts	Aktualisierung der Detailseite, Prüfung vor/nach einem Vorgang	Der Server versucht aktiv, dieses Gerät zu aktualisieren
WebSocket-Ereignisse	Kontinuierliche Zustandsüberwachung	Echtzeitbenachrichtigungen über Verbindungsänderungen, Stromereignisse, Peripherieänderungen und Ähnliches

Verwenden Sie kein häufiges HTTP-Polling über alle Geräte hinweg, um Peripherie, Trennungszustand oder Stromänderungen zu überwachen. Kontinuierliche Überwachung sollte WebSocket-Ereignisse verwenden. Verwenden Sie nach einer Wiederverbindung die Geräteliste oder den Endpunkt für den Einzelgerätestatus, um kritischen Zustand wiederherzustellen.

Befehlsmodell

Gerätebefehle durchlaufen üblicherweise zwei Phasen:

1. Die Plattform akzeptiert die Anfrage.
2. Das Gerät bestätigt das Endergebnis, oder das Wartefenster läuft ab.

Häufige Status:

Status	Bedeutung
SUCCESS	Das Gerät hat das Ergebnis bestätigt
TIMEOUT	Innerhalb des Wartefensters ist keine endgültige Bestätigung eingetroffen
FAILED	Der Befehl ist fehlgeschlagen oder wurde explizit abgelehnt
SENT	Der Befehl wurde gesendet, hat aber noch keinen endgültigen Status; tritt normalerweise bei der Abfrage eines bereits vorhandenen Befehls auf

TIMEOUT beweist nicht, dass das Gerät den Befehl nicht ausgeführt hat. Es könnte ihn ausgeführt haben, während die Bestätigung verzögert oder verloren wurde. Wiederholen Sie bei Befehlen mit Nebenwirkungen die Anfrage nach einem Timeout nicht blind. Lesen Sie zuerst den aktuellen Gerätezustand, bevor Sie entscheiden.

Berechtigungs- und Sicherheitsmodell

API Client verwenden Scopes zur Zugriffskontrolle. Allgemeine Regeln:

• Nur-Lese-Abfragen erfordern normalerweise device:read
• Gerätesteuerung erfordert normalerweise device:control
• Gerätekonfiguration erfordert normalerweise device:config
• Geräteverwaltung erfordert normalerweise device:manage

Wenn eine Anfrage AUTH_SCOPE_DENIED zurückgibt, identifiziert die Antwort die fehlende Berechtigung. Aktualisieren Sie die API-Client-Berechtigungen in der Developer Console und erhalten Sie ein neues Access Token.

Sicherheitsgrenzen:

• Speichern Sie clientSecret nur auf Ihrem Server
• Schreiben Sie clientSecret, Access Token oder WebSocket-Tickets nicht in Frontend-Code, öffentliche Repositories oder Logs
• Nach Deaktivierung oder Löschung eines API Client werden vorhandene Token abgelehnt
• Aktualisieren Sie nach der Rotation eines Secrets Ihre serverseitige Secret-Konfiguration und erhalten Sie ein neues Token

Empfohlener Integrationspfad

1. Erstellen Sie einen API Client in der Developer Console.
2. Verwenden Sie Bruno, um Authentifizierung, Geräteauflistung und eine Gerätezustandsabfrage zu überprüfen.
3. Laden Sie Gerätetypdefinitionen, um unterstützte Peripherie und Vorgänge zu bestätigen.
4. Wählen Sie REST API, WebSocket oder beides, je nach Workflow Ihres Produkts.
5. Integrieren Sie von Ihrem Server aus mit einem SDK oder direkten HTTP-/WebSocket-Aufrufen.
6. Überprüfen Sie vor dem Produktivbetrieb Berechtigungen, Ratenbegrenzungen, Wiederholungsversuche, Idempotenz und Log-Bereinigung.

Nächster Schritt: gehen Sie zu Schnellstart.