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