API: Sonexa (Sontex)

Mit diesem Importer ruft ERAS2 Ablesewerte direkt aus dem Sontex-Portal Sonexa ab. Eine Datei ist dafür nicht nötig.

Für die Nutzung dieser Schnittstelle ist eine gesonderte Lizenz erforderlich.

Voraussetzungen bei Sontex

ERAS2 nutzt zwei Sonexa-Schnittstellen:

Project API: liest die Liste Ihrer Projekte.
Measurement API: holt je Projekt die Messwerte.

Die Device API wird von ERAS2 nicht verwendet.

Die Project API ist bei Sontex ein eigenes, kostenpflichtiges Produkt und muss bei Sontex Deutschland bestellt werden. Erst nach der Freischaltung erscheint sie in der Sonexa in der Token-Maske zur Auswahl. Ohne sie bricht der Import mit dem Fehler 403 ab.

Token in der Sonexa anlegen

In der Sonexa den Reiter REST Api öffnen und auf + NEUEN API TOKEN ERSTELLEN klicken (oder einen vorhandenen Token über den Stift bearbeiten).
Eine Bezeichnung vergeben, z. B. ERAS.
Unter Aktivierte APIs Measurement API und Project API auswählen. Für die Mehrfachauswahl die Taste Strg gedrückt halten. Die Device API wird nicht benötigt.
Den Haken bei Aktiv? setzen und Speichern.
Den Token vollständig kopieren und in ERAS2 im Feld Token: eintragen (siehe Einrichtung).

ERAS2 arbeitet mit genau einem Token für alle Abrufe. Zwei getrennte Tokens (einer je API) funktionieren nicht. Laut Sonexa kann es bis zu 30 Minuten dauern, bis Änderungen am Token wirksam sind.

Einrichtung

In der Liste der für Sie zur Verfügung stehenden Importer finden Sie den Eintrag API Sonexa Abruf. Nach der Auswahl tragen Sie unter Optionen ein:

Feld	Bedeutung
`Token:`	Der API-Token aus der Sonexa.
`Ablesewerte ab`	Werte mit einem früheren Datum werden nicht übernommen. Vorbelegt ist heute vor zwei Monaten.
`Estate Filter:`	Optional. Es werden nur Sonexa-Projekte abgerufen, deren Name diesen Text enthält. Groß- und Kleinschreibung spielen keine Rolle. Leer bedeutet: alle Projekte.
`Probedurchlauf`	Ruft alle Daten ab und schreibt das Protokoll, übernimmt aber nichts in ERAS2. Gut geeignet für den ersten Test.
`Ablesungen vor dem Einbaudatum übernehmen`	Ohne Haken werden Werte verworfen, die vor dem Einbaudatum des Geräts liegen.

Was übernommen wird

Je Gerät ein Wert pro Abruf: der letzte gespeicherte Monatswert, sonst der aktuelle Zählerstand. Ältere Monatswerte werden nicht nachgeholt.
Heizkostenverteiler, Wasserzähler und Wärmezähler. Alle Werte werden mit der Ableseart MO übernommen.
Bei Wärmezählern zählt die Wärmeenergie. Liefert ein Wärmezähler Energie, wird sein Volumen nicht übernommen. Kältewerte von Kombizählern werden ebenfalls nicht übernommen.
Einige Geräte liefern ihre Monatswerte ohne genaues Datum. ERAS2 übernimmt diese Werte mit dem Monatsende.
Rauchwarnmelder erhalten den Status in Ordnung oder Fehler aus ihrer letzten Auslesung in der Sonexa, mit dem Datum dieser Auslesung. Wie oft ein Rauchwarnmelder ausgelesen wird (z. B. jährlich), legen Sie in der Sonexa fest. In ERAS2-Versionen vor 1.24 wurden Rauchwarnmelder ohne Daten seit mehr als sechs Monaten mit „Kein Funkempfang seit …“ als Fehler markiert.

Zuordnung zu Ihren Objekten

Jedes Sonexa-Projekt wird einem ERAS2-Objekt zugeordnet. ERAS2 sucht dazu Geräte des Projekts über die Gerätenummer in Ihrem Bestand und nimmt das Objekt, zu dem die meisten gefundenen Geräte gehören. Projektname und Objektnummer aus der Sonexa spielen dabei keine Rolle.

Als Gerätenummer prüft ERAS2 zuerst die Funkadresse, danach die Zählernummer. Es gilt die Nummer, die ERAS2 im Objekt kennt.
Ist kein Gerät eines Projekts in ERAS2 bekannt, wird das Projekt übersprungen und im Protokoll mit „Kein Objekt gefunden …“ vermerkt. Die übrigen Projekte werden trotzdem importiert.
Geräte, die im zugeordneten Objekt fehlen, erscheinen im Bericht mit „Gerät mit der Nummer … wurde nicht gefunden.“

Fehlermeldungen

Meldung enthält	Ursache	Abhilfe
`403` oder „Project API ist für diesen Zugang nicht freigeschaltet“	Die Project API ist bei Sontex nicht gebucht.	Bei Sontex Deutschland bestellen, danach am Token zusätzlich `Project API` auswählen (siehe oben).
`401` oder „Token ist ungültig oder abgelaufen“	Der Token ist falsch, widerrufen oder unvollständig kopiert.	In der Sonexa einen neuen Token erzeugen und vollständig einfügen.
„jwt is required“	Es ist kein Token eingetragen.	Token unter `Optionen` eintragen.

In älteren ERAS2-Versionen enthält die Meldung bei fehlender Project API nur die Zahl 403.