Häufig gestellte Fragen

Diese Seite organisiert die häufigsten Probleme während der Integration. Beginnen Sie mit dem Symptom, das dem, was Sie sehen, am nächsten kommt; Endpunktschemata, Parameter und vollständige Fehlerlisten bleiben in der Referenzdokumentation.

Nach Symptom suchen

Was Sie sehen	Beginnen Sie hier
Sie haben keinen API Key und wissen nicht, wo Sie einen erstellen können	Der API-Aufruf funktioniert noch nicht
Die Token-Ausstellung schlägt fehl, oder Anfragen geben 401 / 403 zurück	Der API-Aufruf funktioniert noch nicht
Ein Gerät fehlt, oder sein Zustand wirkt nicht aktuell	Gerätedaten wirken nicht korrekt
Sie möchten Peripherie, Trennungszustand oder Stromverlust kontinuierlich überwachen	Gerätedaten wirken nicht korrekt
Ein Befehl wurde akzeptiert, aber das Gerät hat nicht reagiert oder ist abgelaufen	Ein Gerätevorgang wurde nicht wie erwartet abgeschlossen
WebSocket kann keine Verbindung herstellen, trennt sich häufig oder hat Ereignislücken	Die Echtzeitverbindung ist instabil
Sie sind nicht sicher, ob Sie REST API oder WebSocket verwenden sollen	REST API oder WebSocket
Anfragen geben 429, 503 oder ein nicht verfügbares Gateway zurück	Anfragen sind begrenzt oder der Dienst ist vorübergehend nicht verfügbar
Das Problem besteht nach dem Durcharbeiten der Dokumentation weiter	Bereiten Sie Details zur Fehlerbehebung vor

Der API-Aufruf funktioniert noch nicht

Wie erstelle ich einen API Client und erhalte Zugangsdaten?

Erstellen Sie einen API Client in der WLTE Developer Console.

1. Melden Sie sich in der Developer Console an: https://developer.svnwi.com/wlte
2. Öffnen Sie eine Anwendung und gehen Sie zur API-Client-Verwaltung.
3. Erstellen Sie einen API Client und wählen Sie die für die Integration minimal erforderlichen Berechtigungen.
4. Speichern Sie die generierten clientId und clientSecret.

Die Erstellung eines API Client liefert eine clientId und ein clientSecret, die zusammen zum Erhalten eines Access Tokens verwendet werden.

clientSecret wird nur bei der Erstellung oder Rotation angezeigt. Speichern Sie es sofort in einem serverseitigen Secret-Speicher. Wenn es verloren geht, rotieren Sie das Secret, da der ursprüngliche Wert nicht erneut angezeigt werden kann. Siehe API Keys erhalten.

Die Ausstellung des Access Tokens schlägt fehl

Prüfen Sie diese Punkte der Reihe nach:

1. Der API Client existiert und ist aktiv.
2. clientId und clientSecret gehören zum selben Client.
3. Anwendung und Konto sind aktiv.
4. URL, Methode und Anfragetext entsprechen Access Token erstellen (auf Englisch).

Wiederholen Sie ungültige Zugangsdaten nicht endlos, da auch die Authentifizierung Ratenbegrenzungen unterliegen kann.

Der Antwortcode ist AUTH_INVALID

Die Zugangsdaten oder der aktuelle Status ihres Inhabers sind ungültig. Häufige Ursachen sind falsche Zugangsdaten, ein deaktivierter oder gelöschter API Client, eine deaktivierte Anwendung oder ein ungültiger Kontostatus.

Wenn Sie das Secret kürzlich rotiert haben, überprüfen Sie, ob Sie das neue verwenden. Bauen Sie Ihre Verzweigungslogik auf code, nicht auf message.

Der Antwortcode ist AUTH_SCOPE_DENIED

Der API Client hat nicht die vom Endpunkt geforderte Berechtigung. data.requiredScope gibt die fehlende Berechtigung an.

Fügen Sie diese Berechtigung in der Developer Console hinzu, speichern Sie die Änderung, erhalten Sie ein neues Token und versuchen Sie es erneut. Siehe Berechtigungen (auf Englisch).

Kann ein altes Token nach Deaktivierung oder Löschung eines API Client noch verwendet werden?

Nein. Geschützte Endpunkte prüfen den aktuellen Status von API Client, Anwendung und Konto, nicht nur den Ablauf des JWT.

Nach Deaktivierung oder Löschung des Clients können keine neuen Token ausgestellt werden, und vorhandene werden abgelehnt.

Kann clientSecret in einer Website oder mobilen App gespeichert werden?

Nein. clientSecret ist eine Server-Zugangsdaten. Weder Browser-Ressourcen noch Anwendungspakete noch Client-Logs können es zuverlässig schützen.

Bewahren Sie Zugangsdaten auf einem Server unter Ihrer Kontrolle auf. Schreiben Sie clientSecret, Access Token oder WebSocket-Tickets nicht in Frontend-Code, öffentliche Repositories oder Logs.

Gerätedaten wirken nicht korrekt

Ein Gerät fehlt in der Liste

Stellen Sie zunächst sicher, dass das Gerät zum aktuellen Konto gehört und der API Client darauf zugreifen darf.

Wenn das Gerät in der Developer Console, aber nicht in der API erscheint, prüfen Sie die Gerätezugriffsrechte und den device:read-Scope. Wenn die Ursache unklar bleibt, notieren Sie sich requestId, bevor Sie den Support kontaktieren.

Der Zustand aus der Liste stimmt gerade nicht mit dem physischen Gerät überein

Die Geräteliste gibt den von der Plattform bereits synchronisierten Zustand zurück. Sie aktualisiert nicht aktiv jedes physische Gerät bei jeder Listenanfrage und ist für Listenansichten, Dashboards und Massenlesevorgänge gedacht.

Verwenden Sie für eine explizite Aktualisierung durch den Benutzer oder vor/nach einem Vorgang Gerät abrufen (auf Englisch) oder eine Statusanfrage über WebSocket.

Kann ich häufig per HTTP abfragen, um Peripherie, Trennung oder Strom zu überwachen?

Nicht empfohlen. Peripheriezustand, Trennungszustand und Stromereignisse sind auf Echtzeit ausgerichtete Daten. Häufiges HTTP-Polling erhöht die Aktualisierungslast der Geräte erheblich und macht das Erreichen von Ratenbegrenzungen wahrscheinlicher.

Empfohlener Ansatz:

1. Verwenden Sie Geräte auflisten (auf Englisch) für Listen, Dashboards und Hintergrundsynchronisierung.
2. Verwenden Sie Gerät abrufen (auf Englisch) oder device.state.get über WebSocket, wenn ein Benutzer explizit die Detailseite eines Geräts aktualisiert.
3. Verwenden Sie WebSocket-Ereignisse zur kontinuierlichen Überwachung von Trennungs-, Strom- und Peripherieänderungen; bestätigen Sie nach einer Wiederverbindung den kritischen Zustand erneut über HTTP oder device.state.get.

Rufen Sie den Echtzeit-Aktualisierungsendpunkt nicht alle paar Sekunden für jedes Gerät auf. Er garantiert keine verlustfreie Ereigniszustellung und kann andere normale Anfragen desselben Kontos beeinträchtigen.

deviceType hat den Wert UNSUPPORTED

Die Plattform bietet für dieses Gerät noch keine nutzbare Typdefinition. Das Gerät kann weiterhin zum Konto gehören, aber der Client sollte nicht davon ausgehen, dass sein Zustandsschema oder seine Steuerungsfähigkeiten verfügbar sind.

Leiten Sie Fähigkeiten nicht aus dem Präfix der Geräte-ID ab.

Wie erkenne ich, ob ein Gerät einen Vorgang unterstützt?

Lesen Sie Gerätetypdefinitionen auflisten (auf Englisch) und untersuchen Sie capabilities.supportedOperations.

Nur dort aufgeführte Vorgänge sollten angezeigt oder aufgerufen werden. Zeigen Sie beispielsweise die RS485-Übertragung nicht an, es sei denn, device.rs485.transceive ist vorhanden.

Ein Gerätevorgang wurde nicht wie erwartet abgeschlossen

Die Antwort ist COMMAND_ACCEPTED, aber das Gerät hat sich nicht bewegt

COMMAND_ACCEPTED bedeutet, dass die Plattform die Anfrage akzeptiert hat. Es bedeutet nicht, dass das Gerät den Vorgang abgeschlossen hat.

Orientieren Sie sich am Befehlsstatus: SUCCESS bedeutet, dass das Gerät den Vorgang bestätigt hat; TIMEOUT bedeutet, dass keine endgültige Bestätigung rechtzeitig eingetroffen ist. Verwenden Sie Befehlsergebnis abrufen (auf Englisch), um den Status eines früheren Befehls wiederherzustellen.

Der Befehl hat den Status TIMEOUT. Ist sicher, dass das Gerät ihn nicht ausgeführt hat?

Nicht unbedingt. Möglicherweise hat das Gerät den Befehl nicht erhalten, oder es hat ihn ausgeführt, während die Bestätigung verzögert oder verloren wurde.

Wiederholen Sie den Befehl nicht blind. Lesen Sie zuerst den aktuellen Gerätezustand, insbesondere bei Vorgängen, die nicht sicher zu duplizieren sind.

Der Antwortcode ist COMMAND_REJECTED

Prüfen Sie zunächst zwei Dinge:

1. Die Gerätetypdefinition enthält den angeforderten Vorgang.
2. Die Parameter entsprechen den Fähigkeiten des Geräts, z. B. ein gültiger Relaisindex.

Wenn beides korrekt ist, prüfen Sie die Geräteverbindung und den zugrunde liegenden Gerätepfad.

Sollte ein Wiederholungsversuch einen neuen Idempotency-Key verwenden?

Verwenden Sie den ursprünglichen Schlüssel erneut, wenn Sie denselben Geschäftsvorgang nach einem Netzwerkfehler wiederholen. Unterschiedliche Geräte, Zielzustände oder Geschäftsvorgänge erfordern unterschiedliche Schlüssel.

Verwenden Sie keinen festen Schlüssel für alle Anfragen. Siehe HTTP-Verhalten (auf Englisch).

Die Echtzeitverbindung ist instabil

WebSocket kann keine Verbindung herstellen

Stellen Sie sicher, dass das Access Token gültig ist, und erstellen Sie dann ein neues wsTicket. Ein Ticket ist kurzlebig und einmalig verwendbar und sollte nicht zwischengespeichert oder wiederverwendet werden.

Siehe WebSocket Ticket erstellen und dann Verbindung herstellen (beide auf Englisch).

Wie sollte sich der Client nach einer Trennung erholen?

Verbinden Sie sich mit Backoff neu und erstellen Sie für jede neue Verbindung ein neues Ticket. Laden Sie nach der Wiederverbindung den benötigten Zustand neu, anstatt anzunehmen, dass Ereignisse aus dem getrennten Zeitraum vollständig wiedergegeben werden.

Siehe Heartbeat und Wiederverbindung (auf Englisch).

Es kommen doppelte Ereignisse an, oder es scheinen einige zu fehlen

Die Ereignisverarbeitung muss idempotent sein. WebSocket benachrichtigt den Client über Änderungen und sollte nicht die einzige dauerhafte Zustandsquelle sein.

Fragen Sie nach einem Seiten-Reload, einer Wiederverbindung oder einer erkannten Zustandslücke den Zustand über REST API oder eine Statusanfrage über WebSocket ab, um eine neue Basis herzustellen.

Anfragen sind begrenzt oder der Dienst ist vorübergehend nicht verfügbar

Die Antwort ist HTTP 429

Stoppen Sie sofortige Wiederholungsversuche. Lesen Sie Retry-After und versuchen Sie es nach der erlaubten Zeit erneut. Koordinieren Sie den Backoff zwischen den Instanzen Ihres Dienstes, um einen weiteren synchronisierten Ansturm zu vermeiden.

Echtzeit-Aktualisierung und Gerätesteuerung sind strenger begrenzt als Abfragen des synchronisierten Zustands. Siehe Ratenbegrenzungen und Wiederholungsversuche (auf Englisch).

Die Antwort ist 503 oder GATEWAY_UNAVAILABLE

Der Echtzeitpfad zum Gerät ist vorübergehend nicht verfügbar. Notieren Sie sich requestId und versuchen Sie es mit Backoff eine begrenzte Anzahl von Malen erneut.

Wenn der Zustand anhält, stoppen Sie Wiederholungsversuche und bereiten Sie Details zur Fehlerbehebung für den Support vor.

Bereiten Sie Details zur Fehlerbehebung vor

Wenn das Problem weiterhin besteht, sammeln Sie:

Information	Beispiel oder Hinweis
requestId	Die eindeutige Trace-ID aus der API-Antwort
API-Client-ID	Fügen Sie niemals clientSecret bei
Anfragemethode und -pfad	GET /wlte/v1/devices
UTC-Zeitstempel	Genauer Zeitpunkt des Auftretens des Problems
HTTP-Status und Geschäfts-code	Zum Beispiel 403 / AUTH_SCOPE_DENIED
Bereinigte Parameter	Entfernen Sie Passwörter, Token und persönliche Daten

Reichen Sie das Anliegen dann über Support kontaktieren ein.