EBS Energieberatungs-Protokoll:
Technische Spezifikation

Schnittstelle Version 5.0 für Energieberatung Entwurf

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 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>
		<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.