Fernauslese.de bietet Softwareherstellern die Möglichkeit, Daten über eine Schnittstelle – die Fernauslese.de API zu zfa.io – abzufragen und Veränderungen vorzunehmen ohne unser Zentralsystem zfa.io selbst aufrufen zu müssen.
Die Fernauslese.de API ist in verschiedenen Varianten verfügbar. Die nachfolgende Dokumentation zeigt die Implementation in Form einer HTTP GET Schnittstelle. Über die API können alle Daten und Funktionen aus zfa.io angesteuert werden.
Bei Fragen oder Problemen stehen wir gerne mit unserem technischen Support zur Verfügung.
Kommunikationsparameter der API
Über den Pfad /api/VERWALTUNGSSOFTWARE/ können verschiedene Parameter übergeben werden. Die Authentifizierung erfolgt mittels Standardauthentifizierung (Benutzername und Passwort). Für den Zugriff mittels API erhält der Kunde spezielle Zugangsdaten, die von den Zugangsdaten für das Web-Frontend abweichen.
Der Benutzername für die API besteht aus dem in der Regel dreistelligen Kürzel für den Betrieb (z.B. bcm für Beispiel-Campingplatz in Musterstadt) mit dem Präfix api_ (hier: api_bcm).
| channel | int | channel bezeichnet den Kanal, der abgefragt oder geschaltet werden soll. Die Angabe des Parameters channel ist zwingend erforderlich. Zwischen der Beschreibung des Kanals im Web-Frontend und dem channel besteht kein direkter Zusammenhang. Hierfür erhalten Sie eine Zuordnungstabelle. |
| newstate | int | Mit newstate wird die gewünschte Betriebsart übergeben (Soll-Zustand). Dieser Befehl kann optional ausgeführt werden.
|
Die Zuordnungstabelle beschreibt die Zuordnung zwischen der Beschreibung eines Kanals im Web-Frontend und einem channel als Kommunikationsparameter der API. Beispiel:
| Beschreibung https://kürzel.zfa.io | channel https://kürzel.zfa.io/ api/VERWALTUNGSSOFTWARE/ |
|---|---|
| Steckdose1 | 1 |
| Steckdose 2 | 2 |
| Steckdose 3 | 3 |
| Steckdose 4 | 4 |
Rückgabeparameter
Die API liefert nach erfolgreicher Parameterübergabe folgende Rückgabewerte, die Rückgabewerte werden mit ; getrennt ausgegeben:
| value | float | Der aktuelle Zählerstand in Kilowattstunden (kWh). |
| state | int | Der aktuelle Schaltzustand im Schrank, wie er vom Fernauslesesystem zurückgemeldet wird (Ist-Zustand).
Die Bedeutung der verschiedenen Schaltzustände wird hier erklärt. |
| error | int | Gibt an, ob auf diesem channel ein Stromversorgungsfehler (ausgelöster Fehlerstrom-Schutzschalter, Vorsicherung defekt, fehlende Phase) vorliegt. Kommunikationsfehler innerhalb des Fernauslesesystems werden hier NICHT ausgegeben, diese sind nur über das Web-Frontend ersichtlich!
|
| power | int | Die momentan bezogene Leistung in Watt (W). |
| usage | float | Der Verbrauch seit dem letzten Einschalten in Kilowattstunden (kWh). Dies ist ein Zwischenzähler, der immer dann zurückgesetzt wird, wenn ein Kanal vom ausgeschalteten in den eingeschalteten Zustand umgeschaltet wird. Beim Ausschalten bleibt der Verbrauchswert noch bis zum nächsten Einschalten erhalten. |
| qc | str | 6-stelliger alphanummerischer Zugangscode für den Quick Check unter https://qc.zfa.io |
Fehlermeldungen
Bei internen Fehlern in der API werden folgende Fehlermeldungen zurückgegeben:
| database connection refused | Fehler des Datenbankservers |
| database not found | Datenbank für diesen Mandant nicht vorhanden |
| update error | Setzen des neuen Schaltzustandes nicht möglich |
| query error | Abfragen des Zählerstandes nicht möglich |
Testszenario
Um die volle Funktionalität der API sicherzustellen, können Sie bei der Implementierung auf folgende Beispiele zurückgreifen.
Beispiel 1: Zählerstand abfragen
URL:
https://kürzel.zfa.io/api/VERWALTUNGSSOFTWARE/?channel=1Aktion: Der aktuelle Zählerstand des channel mit der ID 1 wird abgefragt.
Rückgabewert:
value=0.010;state=0;error=0;power=0;usage=0.000;qc=1A2B3CBedeutung: Der aktuelle Zählerstand beträgt 0,010 kWh. Der aktuelle Schaltzustand (Ist-Zustand) ist Aus. Es liegen keine Fehlermeldungen vor. Momentan wird keine Leistung bezogen (0 W). Seit dem letzten Einschalten wurde kein Strom bezogen. Der Quick Check unter https://qc.zfa.io kann mit dem Link https://qc.zfa.io/1A2B3C erreicht werden.
Beispiel 2: Kanal einschalten
URL:
https://kürzel.zfa.io/api/VERWALTUNGSSOFTWARE/?channel=1&newstate=1Aktion: Der channel mit der ID 1 wird eingeschaltet.
Rückgabewert:
value=0.010;state=0;error=0;power=0;usage=0.000;qc=1A2B3CBedeutung: Der aktuelle Zählerstand beträgt 0,010 kWh. Der aktuelle Schaltzustand (Ist-Zustand) ist Aus. Es liegen keine Fehlermeldungen vor. Momentan wird keine Leistung bezogen (0 W). Seit dem letzten Einschalten wurde kein Strom bezogen. Der Quick Check unter https://qc.zfa.io kann mit dem Link https://qc.zfa.io/1A2B3C erreicht werden.
Schnittstelle zwischen der Verwaltungssoftware und Fernauslese.de
Der Benutzer erhält einen Konfigurationsstring im Format api-benutzername:passwort für die Nutzung des Fernauslesesystems mit der Verwaltungssoftware. Idealerweise kann er diesen genauso in den dortigen Einstellungen hinterlegen. Wir empfehlen eine Funktion einzubauen, in der der Kunde für den jeweiligen Zähler den entsprechenden channel hinterlegen kann.