MENU Online-Datenbank zur Verwaltung von Energieausweisen gizmocraft, design and technology GmbH

EBS Energieberatungs-Protokoll:
Technische Spezifikation

Schnittstelle Version 5.0 für Energieberatung

Die Schnittstelle Version 5.0 wird ab September 2020 für den EBS Manager Salzburg in der Testumgebung (Spielwiese) zur Verfügung stehen.

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.

Bitte beachten:
  • 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:

  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>
CodeFehler
1Fehlende Parameter.
2Login fehlgeschlagen.
3Keine Datei übergeben.
4Die ZIP-Datei ist fehlerhaft und kann nicht entpackt werden.
5In der ZIP-Datei sind nicht alle erwarteten Dateien vorhanden.
7Ungültige PDF-Version (PDF Version 1.2 bis 1.7 erwartet).
10Die hinaufgeladene Datei ist zu groß.
11Ungültiges Dateiformat (keine ZIP-Datei) übergeben.
12Die XML-Dateien haben unterschiedliche Versionsnummern.
13Die Versionsnummer der XML-Datei ist ungültig.
14Die XML-Datei ist ungültig.
201Die Beratung konnte nicht gefunden werden.
202Die Beratung ist bereits abgeschlossen, eine Aktualisierung ist nicht mehr möglich.
203Sie haben keinen Zugriff auf diese Beratung.
204Die Beratungsnummern in den XML-Dateien sind unterschiedlich.
205Die Beratungsnummer fehlt in mindestens einer der XML-Dateien.
500Derzeit werden Wartungsarbeiten durchgeführt, bitte um etwas Geduld.
501Interner 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&amp;advice_id=123

Vor dem Aufruf der URL im Standardbrowser des Benutzers muss das kaufmännische &, das in der URL als &amp; 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