Schnittstelle Version 5.0 für Energieausweise Neu
Allgemeines
ZEUS ist eine Online-Datenbank, die zur Verwaltung von Energieausweisen dient.
Für Clientsoftware, die Energieausweise berechnet, bietet ZEUS eine HTTP-POST-Schnittstelle mit XML-Reply, um direkt aus der Clientsoftware die notwendigen Dateien in das ZEUS-System einzuspielen.
Der ZEUS-Server erwartet eine ZIP-Datei (upload.zip), in der sich der Energieausweis als PDF und als XML-Datei befinden. Je nach Client-Software können weitere Dateien zur Archivierung mitgeschickt werden.
Für den Aufbau der XML–Datei für Energieausweise existiert eine separate Spezifikation.
- ZEUS unterstützt keine PDFs, die Formularfelder enthalten. Formularfelder werden beim Upload ohne Hinweis aus dem PDF entfernt.
- ZEUS unterstützt keine verschlüsselten PDFs.
Registrierte Clients mit den erwarteten Dateien
Über folgende Software-Programme werden derzeit in Österreich Energieausweise berechnet. Für diese sind folgende Schnittstellen-Dateien vorgesehen, die generiert werden müssen und als ZIP-Datei gepackt übertragen werden können:
XML v4 End of life
| Software | XML | Source-Dateien | |
|---|---|---|---|
| ArchiPHYSIK (A-NULL Development) | energieausweis.pdf | energieausweis.xml | *.aph |
| AX3000 (Nemetschek) | energieausweis.pdf | energieausweis.xml | *.zip |
| Ecotech Gebäuderechner (Builddesk) | energieausweis.pdf | energieausweis.xml | *.zip |
| Gebäudeprofi (ETU) | energieausweis.pdf | energieausweis.xml | *.zip |
| GEQ (Zehentmayer Software) | ausdruck_geq.pdf | statistik.xml | *.geq, *.geqz |
Für den Aufbau der XML–Datei Version 4.0 existiert eine separate Spezifikation.
XML v5 Neu
| Software | XML | Source-Dateien | |
|---|---|---|---|
| ArchiPHYSIK (A-NULL Development) | energieausweis.pdf | energieausweis.xml | energieausweis.aph |
| AX3000 (Nemetschek) | energieausweis.pdf | energieausweis.xml | energieausweis.zip |
| Ecotech Gebäuderechner (Builddesk) | energieausweis.pdf | energieausweis.xml | energieausweis.zip |
| Gebäudeprofi (ETU) | energieausweis.pdf | energieausweis.xml | energieausweis.zip |
| GEQ (Zehentmayer Software) | energieausweis.pdf | energieausweis.xml | energieausweis.geqx oder energieausweis.geqz |
Für den Aufbau der XML–Datei Version 5.0 existiert eine separate Spezifikation.
Upload
Der Upload erfolgt in 2 Schritten:
- 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 ZEUS-Systeme sind als XML über die URL https://www.energieausweise.net/service/serviceurls.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.
Alle Requests sollten bevorzugt über HTTPS abgesetzt werden. Für ZEUS Burgenland sowie Uploads von XML v4 und später ist ein Upload über HTTPS verpflichtend.
POST-Parameter
Folgende POST-Parameter werden von der Schnittstelle erwartet und sind verpflichtend:
| Parameter | Beschreibung | Beispielwert |
|---|---|---|
| user | ZEUS Benutzername des Erstellers | hhuber |
| password | ZEUS Passwort | xyz |
| zip | upload.zip (siehe „Inhalt der ZIP-Datei“) | upload.zip |
| client | Name der aufrufenden Clientsoftware (mögliche Werte: anull, ax3000, ecotech, etu oder geq) |
geq |
| clientversion (optional) | Version der aufrufenden Clientsoftware | 2020,051401 |
Benutzername und Passwort aus ZEUS können z. B. in der Clientsoftware direkt vor dem Upload abgefragt werden oder in deren Konfiguration verwaltet werden.
XML-Reply
Bei Erfolg
<?xml version="1.0" encoding="UTF-8"?>
<zeus>
<success>true</success>
<project>
<id>1234</id>
<name>ZEUS Testprojekt</name>
<url>https://beispiel.energieausweise.test/tu/abc123</url>
</project>
</zeus>Bei Fehler
<?xml version="1.0" encoding="UTF-8"?>
<zeus>
<success>false</success>
<error code="4">Datei fehlerhaft</error>
</zeus>| Code | Fehler |
|---|---|
| 1 | Fehlende Parameter ([Auflistung der fehlenden Parameter]) |
| 2 | Login fehlgeschlagen |
| 3 | ZIP nicht angekommen (max. Uploadgröße [Größe] MB) |
| 4 | Datei fehlerhaft (ZIP konnte nicht entpackt werden) |
| 5 | Erwartete Datei(en) laut Client [Client] nicht vorhanden |
| 6 | XML fehlerhaft ([Fehlerbeschreibung]) |
| 7 | Ungültige PDF-Version (PDF Version [ab] bis Version [bis] erwartet) |
| 8 | Die Version [Version] des Berechnungsprogramms ist für den ZEUS-Upload gesperrt. |
| 9 | Für die XML-Version [Version] ist eine sichere Verbindung erforderlich. |
| 500 | Derzeit werden Wartungsarbeiten durchgefuehrt, bitte um etwas Geduld. |
Im Fehlerfall muss die Anzeige der Fehlermeldung (aus dem Element error)
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 den Uploades des Energieausweises in ZEUS fertigstellen kann.