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>
<name></name>
<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 Lösung |
---|---|
1 | Fehlende Parameter. Bitte wenden Sie sich an den Hersteller Ihres Programms. |
2 | Login fehlgeschlagen. Bitte überprüfen Sie den eingegeben Benutzernamen und Ihr Passwort. |
3 | Keine Datei übergeben. Falls Sie Ihrem Projekt zusätzliche Dokumente hinzugefügt haben, entfernen Sie diese bitte und versuchen Sie es bitte erneut. Andernfalls wenden Sie sich bitte an den Hersteller Ihres Programms. |
4 | Die ZIP-Datei ist fehlerhaft und kann nicht entpackt werden. Bitte wenden Sie sich an den Hersteller Ihres Programms. |
5 | In der ZIP-Datei sind nicht alle erwarteten Dateien vorhanden. Falls Sie Ihrem Projekt zusätzliche Dokumente hinzugefügt haben, entfernen Sie diese bitte und versuchen Sie es bitte erneut. Andernfalls wenden Sie sich bitte an den Hersteller Ihres Programms. |
7 | Ungültige PDF-Version (PDF Version 1.2 bis 1.7 erwartet). Bitte wenden Sie sich an den Hersteller Ihres Programms. |
10 | Die hinaufgeladene Datei ist zu groß. Entfernen Sie zusätzliche Dokumente, die Sie Ihrem Projekt hinzugefügt haben, und versuchen Sie es bitte erneut. |
11 | Ungültiges Dateiformat (keine ZIP-Datei) übergeben. Bitte wenden Sie sich an den Hersteller Ihres Programms. |
12 | Die XML-Dateien haben unterschiedliche Versionsnummern. Bitte wenden Sie sich an den Hersteller Ihres Programms. |
13 | Die Versionsnummer der XML-Datei ist ungültig. Bitte wenden Sie sich an den Hersteller Ihres Programms. |
14 | Die XML-Datei ist ungültig. Bitte wenden Sie sich an den Hersteller Ihres Programms. |
201 | Die Beratung konnte nicht gefunden werden. Bitte wenden Sie sich an den Hersteller Ihres Programms. |
202 | Die Beratung ist bereits abgeschlossen, eine Aktualisierung ist nicht mehr möglich. Legen Sie eine neue Beratung im EBS Manager an und versuchen Sie es erneut. |
203 | Sie haben keinen Zugriff auf diese Beratung. Diese Beratung ist einem anderen Berater zugeordnet. Bitte wenden Sie sich an Ihren Administrator im EBS Manager. |
204 | Die Beratungsnummern in den XML-Dateien sind unterschiedlich. Bitte wenden Sie sich an den Hersteller Ihres Programms. |
205 | Die Beratungsnummer fehlt in mindestens einer der XML-Dateien. Bitte wenden Sie sich an den Hersteller Ihres Programms. |
500 | Derzeit werden Wartungsarbeiten durchgeführt, bitte um etwas Geduld. Bitte versuchen Sie den Upload später noch einmal. |
501 | Interner Fehler. Bitte wenden Sie sich an den Support vom EBS Manager. |
502 | Der Upload ist für dieses Bundesland nicht freigeschaltet. Bitte wenden Sie sich an den Support vom EBS Manager. |
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