EBS Energieberatungs-Protokoll:
Technische Spezifikation

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.

Upload

Der Upload erfolgt in 2 Schritten und ähnelt dem vom ZEUS Energieausweis:

1. HTTP-POST-Request zum Upload der Dateien
2. 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.