Schnittstelle Version 5.0 für Energieberatung
Allgemeines
Der EBS Manager ist eine Internet-Datenbank zur elektronischen Verwaltung von Energieberatungen und den zugehörigen Energiedaten.
Für Clientsoftware zur Erstellung von Energieberatungs-Protokollen (Energieberatungssoftware) bietet der EBS Manager eine HTTP-POST-Schnittstelle mit XML-Reply, um direkt aus der Clientsoftware die notwendigen Dateien in das EBS Manager-System einzuspielen.
Der Server erwartet eine ZIP-Datei, in der sich die Energieberatungs-Protokolle für Bestand, Planung und Gesamtkonzept als PDF-Dateien und als XML-Dateien befinden. Je nach Clientsoftware können weitere Dateien zur Archivierung mitgeschickt werden.
Für den Aufbau der XML–Datei für Energieberatungs-Protokolle existiert eine separate Spezifikation.
- EBS unterstützt keine PDFs, die Formularfelder enthalten. Formularfelder werden beim Upload ohne Hinweis aus dem PDF entfernt.
- EBS unterstützt keine verschlüsselten PDFs.
Upload
Der Upload erfolgt in 2 Schritten und ähnelt dem vom ZEUS Energieausweis:
- HTTP-POST-Request zum Upload der Dateien
- Aufruf der im XML-Reply angegebenen URL im Browser
Schritt 1: POST-Request
Direkt aus der Clientsoftware kann ein HTTP-Request (Methode: POST) abgesetzt werden.
Die aufzurufenden URLs für die jeweiligen EBS Manager-Systeme sind als XML über die URL https://www.energieausweise.net/service/upload.xml abrufbar. Im XML sind die Upload-URLs aller verfügbaren Systeme enthalten, wobei jeweils Produktiv- und Testsysteme angeführt werden. Zusätzlichen sind auch die URLs zu den XML-Schema-Dateien enthalten.
POST-Parameter
Folgende POST-Parameter werden von der Schnittstelle erwartet und sind verpflichtend:
Parameter | Beschreibung | Beispielwert |
---|---|---|
user | EBS Benutzername des Erstellers | hhuber |
password | EBS Passwort | xyz |
zip | upload.zip (siehe „Inhalt der ZIP-Datei“) | upload.zip |
client | Name der aufrufenden Clientsoftware | geq |
clientversion | Version der aufrufenden Clientsoftware | 2020,051401 |
Benutzername und Passwort aus dem EBS Manager können z. B. in der Clientsoftware direkt vor dem Upload abgefragt werden oder in deren Konfiguration verwaltet werden.
Inhalt der ZIP-Datei
Beschreibung | Dateiname |
---|---|
Energieberatungs-Protokoll | energieberatung.pdf |
XML für Bestand | bestand.xml |
XML für Planung | planung.xml |
XML für Empfehlungen Gesamtkonzept | gesamtkonzept.xml |
Source-Datei | energieberatung.zip |
Für den Aufbau der XML–Datei für Energieberatungs-Protokolle existiert eine separate Spezifikation, die am ZEUS XML v5 basiert.
Vor dem Upload muss die Client-Software die XML-Datei gegen die XSD-Datei (XML Schema Definition) validieren. Die URL für die XSD-Datei wird im upload.xml angeführt.
XML-Reply
Bei Erfolg
<?xml version="1.0" encoding="UTF-8"?>
<zeus>
<success>true</success>
<project>
<protocolnumber></protocolnumber>
<url></url>
</project>
</zeus>
Bei Fehler
<?xml version="1.0" encoding="UTF-8"?>
<zeus>
<success>false</success>
<error>
<code>2</code>
<message>Login fehlgeschlagen.</message>
<solution>Bitte überprüfen Sie den eingegeben Benutzernamen und Ihr Passwort.</solution>
</error>
</zeus>
Code | Fehler |
---|---|
1 | Fehlende Parameter. |
2 | Login fehlgeschlagen. |
3 | Keine Datei übergeben. |
4 | Die ZIP-Datei ist fehlerhaft und kann nicht entpackt werden. |
5 | In der ZIP-Datei sind nicht alle erwarteten Dateien vorhanden. |
7 | Ungültige PDF-Version (PDF Version 1.2 bis 1.7 erwartet). |
10 | Die hinaufgeladene Datei ist zu groß. |
11 | Ungültiges Dateiformat (keine ZIP-Datei) übergeben. |
12 | Die XML-Dateien haben unterschiedliche Versionsnummern. |
13 | Die Versionsnummer der XML-Datei ist ungültig. |
14 | Die XML-Datei ist ungültig. |
201 | Die Beratung konnte nicht gefunden werden. |
202 | Die Beratung ist bereits abgeschlossen, eine Aktualisierung ist nicht mehr möglich. |
203 | Sie haben keinen Zugriff auf diese Beratung. |
204 | Die Beratungsnummern in den XML-Dateien sind unterschiedlich. |
205 | Die Beratungsnummer fehlt in mindestens einer der XML-Dateien. |
500 | Derzeit werden Wartungsarbeiten durchgeführt, bitte um etwas Geduld. |
501 | Interner Fehler. |
Im Fehlerfall muss die Anzeige der Fehlermeldung (aus dem Element message
)
sowie der mögliche Vorschlag zur Behebung (aus dem Element solution
)
in der jeweiligen Clientsoftware erfolgen.
Schritt 2: Aufruf der URL im Browser
Im Erfolgsfall wird im XML-Reply eine URL zurückgeliefert, die aus der Clientsoftware im Browser aufgerufen werden muss, damit der Benutzer das Energieberatungs-Protokoll im EBS Manager fertigstellen kann.
Hinweis: Das XML-Format macht es beim Retournieren notwendig, die in der aufzurufenden URL vorkommenden Sonderzeichen zu codieren. Folgende URL wird z. B. retourniert:
https://www.energieberatung-salzburg.net/index.php?cmd=advice_detail&advice_id=123
Vor dem Aufruf der URL im Standardbrowser des Benutzers muss das kaufmännische &
,
das in der URL als &
zurückgeliefert wird, in ein reguläres &
umgewandelt werden.
Die aufzurufende EBS Manager-URL lautet also:
https://www.energieberatung-salzburg.net/index.php?cmd=advice_detail&advice_id=123