Die REST API v1 bietet die Möglichkeit den kompletten Prozess der Energieausweiserstellung zu starten und zu verfolgen.
Alle Anfragen werden über
HTTPS
an den Host
api
in der Domain
energieausweis48.de
gesendet.
Der Endpoint für die REST API v1 lautet
/v1
.
Hierhin werden alle Anfragen gesendet.
Sofern eine Anfrage oder eine Antwort über einen Body verfügen, ist dieser in JSON formatiert.
Alle Anfragen mit Bodys
müssen
mit dem Header
Content-Type: application/json
übersendet werden.
curl -X POST -H 'Content-Type: application/json' -d '{"example":"example"}' https://api.energieausweis48.de/v1/example
HTTP/1.1 200 OK Content-Type: application/json { "example": "example" }
Sollte unsere API nicht erreichbar sein, weil ein Fehler vorliegt,
werden Sie eine Antwort mit dem HTTP Status Code
500
erhalten.
Bei Wartungsarbeiten lautet der HTTP Status Code der Antwortet
503
.
Wenn Sie einen Endpoint anfordern, der nicht existiert
oder Informationen zu einem Auftrag benötigen, welcher nicht existiert,
erhalten Sie eine Antwort mit dem HTTP Status Code
404
.
Um sich an der API zu authentifizieren zu können benötigen Sie Ihren individuellen Token.
Ihren Token finden Sie (nach der Registrierung) innerhalb Ihres Profils unter dem Punkt Zugangsdaten.
Sie übergeben den Token als Parameter mit dem Namen
token
bei
jeder
Anfrage an den Server.
Sollten Sie auf Ressourcen zugreifen
ohne sich zunächst zu authentifizieren erhalten Sie eine Antwort
mit dem HTTP Status Code
401
.
Bei Zugriffen auf nicht berechtigte Ressourcen erhalten Sie
eine Antwort mit dem HTTP Status Code
403
.
curl -X POST https://api.energieausweis48.de/v1/protected?token=MeinIndividuellerToken
Wenn sie einen Auftrag erteilen möchten, müssen Sie uns die initial notwendigen Daten übermitteln.
Aufgrund der Komplexität der Eingabedaten bieten wir aktuell nur den Bedarfsausweis Full Service über die API an.
Der Energieausweis kann jeweils für 1 - 5 Wohnungen und 6 - 12 Wohnungen beauftragt werden.
Bitte ermitteln Sie zunächst Ihr Zielprodukt und senden Sie uns dann die ID des Produkts bei der Beauftragung zu.
Die ID wird als
product_id
übertragen.
1
-
Bedarfsausweis Full Service für 1 - 5 Wohnungen
2
-
Bedarfsausweis Full Service für 6 - 12 Wohnungen
Ebenfalls ermittelt werden muss vorher der Gebäudetyp Ihres Gebäudes.
Jeder Gebäudetyp besitzt ebenfalls eine ID die bei der Beauftragung übertragen werden muss.
Die ID wird als
type
in der Eigenschaft
property
übertragen.
Wichtig: Bitte beachten Sie, dass ein Einfamilienhaus immer nur eine Wohnung, ein Zweifamilienhaus zwei Wohnungen und ein Mehrfamilienhaus immer mehr als zwei Wohnungen haben muss.
1
-
Freistehendes Einfamilienhaus
2
-
Einseitig angebautes Einfamilienhaus
3
-
Zweiseitig angebautes Einfamilienhaus
4
-
Freistehendes Zweifamilienhaus
5
-
Einseitig angebautes Zweifamilienhaus
6
-
Zweiseitig angebautes Zweifamilienhaus
7
-
Mehrfamilienhaus
8
-
Wohnteil gemischt genutztes Gebäude
9
-
Sonstiges Wohngebäude
Um das Gebäude zu besichtigen, muss ein Termin mit einer Person vereinbart werden, die es unseren Objektbesichtigern ermöglicht das Gebäude zu betreten und ggf. Fragen zum Gebäude zu beantworten.
Die Kontaktinformationen dieser Person übergeben Sie uns im Feld
tenant
.
Hierbei kann aktuell eine Anrede
(salutation
)
nur aus
Frau
(female
)
oder
Herr
(male
)
bestehen.
Der Vorname
(prename
),
sowie der Nachname
(surname
)
muss mindestens aus 2 Buchstaben bestehen.
Innerhalb des
contact
Felds können Sie
optional
eine Mobilfunknummer
(mobile
)
angeben.
Sofern wir Ihren Account für eine Rechnungserstellung
pro Auftrag
konfiguriert haben, können Sie uns mit dem Feld
billing
eine Anschrift mitteilen, an welche die Rechnung versendet werden soll.
Abschließend benötigen Sie noch das
Baujahr
(property.year_built
)
des Gebäudes, welches zwischen 1600 und
2019
liegen muss, sowie die
Adresse
(address
)
des Gebäudes. Mit Hilfe dieser Informationen können Sie nun eine
POST
Anfrage an den Endpoint
/orders/new
senden, um den Auftrag zu erteilen.
Die Hausnummer
(house
)
in der Adresse darf maximal
10
Zeichen lang sein.
Die Postleitzahl
(zip
)
besteht wie gewohnt aus 5 Ziffern.
Zusätzlich können Sie im Feld
external_identifier
noch
optional
Ihre interne Auftragsnummer oder sonstige Identifier zur Auftragsführung mitliefern,
optional, maximal 480 Zeichen
im Feld
property.comment
eine Mitteilung zur Hilfe in der Auftragsbearbeitung, sowie im optionalen Feld
finalize_at
ein Datum, wann der Auftrag idealerweise bearbeitet werden soll.
curl -X POST -H 'Content-Type: application/json' -d '{ "product_id": 1, "property": { "type": 1, "year_built": 1993, "comment": "Der Eingang befindet sich im Hinterhof" }, "tenant": { "salutation": "male", "prename": "Max", "surname": "Mustermann", "contact": { "phone": "0123456789", "email": "max.mustermann@example.com", "mobile": "9876543210" } }, "billing": { "prename": "Max", "surname": "Mustermann", "contact": { "email": "max.mustermann@example.com" }, "address": { "street": "Rechnungsstraße", "house": "109", "zip": "41242", "city": "Rechnungsort" } }, "address": { "street": "Gebäudestraße", "house": "13a", "zip": "03142", "city": "Gebäudestadt" }, "external_identifier": "nummer10", "finalize_at": "2019-03-10" }' https://api.energieausweis48.de/v1/orders/new?token=MeinIndividuellerToken
Sie erhalten eine Antwort mit dem HTTP Status Code
201
.
Im Feld
data
finden Sie die Auftragsnummer
(id
),
den Status des Auftrags im Feld
status
jeweils mit der ID des Status
(id
),
dem Namen des Status
(name
),
sowie dem Erstellungszeitpunkt
(created-at
)
und dem letzten Zeitpunkt der Aktualisierung des Auftrags
(updated-at
).
Ein Auftrag steht initial immer im Status
Besichtigung
mit der ID
4
in dem zunächst ein Termin zur Besichtigung
mit der auskunftsfähigen Person vereinbart wird.
HTTP/1.1 201 Created Content-Type: application/json { "data": { "id": 1031921, "status": { "id": 4, "name": "Besichtigung" }, "created-at": "2017-09-28 11:27:31", "updated-at": "2017-09-28 11:27:31" } }
Sollten Ihre übermittelten Daten nicht unseren Anforderungen entsprechen,
erhalten Sie eine Antwort mit dem HTTP Status Code
422
.
Mit einer
POST
Anfrage an den Endpoint
/files/$AUFTRAGSNUMMER
können Sie Dokumente zum Auftrag hinzufügen,
die uns bei der Erstellung des Energieausweises helfen.
Der Name des Feldes lautet hier
file
.
Zulässing sind alle gängigen Dokumente wie z.B. PDFs, Office Dokumente, Bilder, CSVs und Textdateien.
curl -X POST -H 'Content-Type: multipart/form-data' -F 'file=@/test-file.pdf' https://api.energieausweis48.de/v1/files/1031921?token=MeinIndividuellerToken
Sie erhalten eine leere Antwort bei Erfolg oder ein JSON Fehler Objekt bei einem Fehler.
{"code":"","http_code":422,"message":"'file' is empty"}
Sie können sich jederzeit über eine
GET
Anfrage an den Endpoint
/orders/$AUFTRAGSNUMMER
den
aktuellen
Status zu einem Auftrag anzeigen lassen.
Ebenso wie Produkte und Gebäudetypen haben auch die Status eine eindeutige ID.
4
-
Besichtigung:
Der Besichtigungstermin wird vereinbart und durchgeführt.
5
-
Besichtigung durchgeführt
6
-
QS:
Die Daten werden in die Berechnung übertragen und auf Validtät geprüft.
7
-
Zur Prüfung beim Energieberater:
Der Energieberater prüft die eingegebenen Daten und deren Auswirkungen.
8
-
Rückfrage vom Energieberater:
Der Energieberater kann den Energieausweis nicht ausstellen
und klärt den involvierten Personen die fehlenden Details.
9
-
Fertiggestellt:
Der Energieberater hat den Energieausweis ausgestellt.
Sie können den Energieausweis jetzt herunterladen.
2
-
Storniert
10
-
Ungültig:
Es wurden nach der Ausstellung des Energieausweises Fehler festgestellt.
Die beiden Status
Fertiggestellt
und
Storniert
markieren jeweils Punkte nach deren Erreichen ein Auftrag als
beendet
gilt.
Der Status
Ungültig
tritt nur in Ausnahmefällen auf.
Das kann auch Jahre nach dem eigentlichen Ausstellen des Ausweises geschehen.
Hierfür muss ein
neuer
Auftrag erteilt werden.
Zusätzlich zum eigentlichen, aktuellen Auftragsstatus liefern wir
die gesamte Historie des Auftrags im Feld
events
aus. Events sind bei uns Ereignisse die passiert sind und
möglicherweise
den Status des Auftrags verändert haben.
events
ist ein Array welches jeweils Objekte mit den Feldern
name
(Name des Events),
comment
(Zusatzinformationen; Ist
null
wenn keine Zusatzinformationen vorhanden sind) und
created-at
(Zeitpunkt an dem das Ereignis statt fand) enthält.
Mögliche Events sind folgende:
1
-
Entwurf angelegt
23
-
Auftrag in Klärung
Der Ansprechpartner kann den Termin erst nach ein paar Tagen/Wochen wahrnehmen
24
-
Auftrag wird weiter bearbeitet
2
-
Termin zur Besichtigung wird vereinbart
4
-
Termin konnte nicht vereinbart werden
3
-
Termin zur Besichtigung ist geplant
6
-
Termin zur Besichtigung durchgeführt
8
-
Datenerfassung durch Besichtiger abgeschlossen
9
-
Qualitätssicherung durchgeführt
10
-
Qualitätssicherung zurückgewiesen
Die Qualitätssicherung muss erst noch Rücksprache mit dem Objektbesichtiger halten
11
-
Zur Prüfung beim Energieberater
12
-
Rückfrage vom Energieberater
16
-
Modernisierungsmaßnahmen
13
-
Energieausweis wurde fertiggestellt
21
-
Ausweis ungültig
17
-
Storniert
curl https://api.energieausweis48.de/v1/orders/1031921?token=MeinIndividuellerToken
Sie erhalten eine ähnliche Antwort wie die nach der Beauftragung mit dem HTTP Status Code
200
.
HTTP/1.1 200 OK Content-Type: application/json { "data": { "id": 1031921, "created-at": "2017-09-28 11:27:31", "updated-at": "2017-10-03 16:01:58", "status": { "id": 7, "name": "Zur Prüfung beim Energieberater" }, "events": [ { "id": 11, "name": "Zur Prüfung beim Energieberater", "comment": null, "created-at": "2017-10-03 16:01:58" }, { "id": 9, "name": "Qualitätssicherung durchgeführt", "comment": null, "created-at": "2017-10-03 12:05:18" }, { "id": 8, "name": "Datenerfassung durch Besichtiger abgeschlossen", "comment": null, "created-at": "2017-10-03 11:30:17" }, { "id": 6, "name": "Termin zur Besichtigung durchgeführt", "comment": null, "created-at": "2017-10-03 10:20:47" }, { "id": 3, "name": "Termin zur Besichtigung ist geplant", "comment": "Termin soll am 3.10 um 10:00 Uhr statt finden", "created-at": "2017-09-29 14:00:43", "appointment": "2017-10-03 10:00" }, { "id": 1, "name": "Entwurf angelegt", "comment": null, "created-at": "2017-09-28 11:27:31" } ] } }
Da es vorkommt, dass ein Auftrag nicht sofort storniert werden kann, weil zum Beispiel gerade die Vor-Ort-Besichtigung statt findet, können wir nur Stornierungsanfragen entgegen nehmen.
Diese werden dann von unserem Service Team bearbeitet und zum nächst möglichen Zeitpunkt akzeptiert oder (wenn es bereits zu spät ist) abgelehnt.
Nach einer Akzeptierung befindet sich der Auftrag im Status
Storniert
.
Sollte die Stornierungsanfrage abgelehnt werden, ändert sich nichts am Status des Auftrags und dieser wird wie gewöhnlich fertiggestellt.
Sie können eine Stornierungsanfrage über eine
POST
Anfrage an den Endpoint
/orders/$AUFTRAGSNUMMER/cancellation
stellen.
Wir benötigen für die Erstellung der Stornierungsanfrage einen Stornierungsgrund.
Auch hier geben wir diverse Gründe an Hand einer ID vor.
Sie können die ID des Stornogrunds im Feld
reason
übergeben.
1
-
Ich habe das falsche Produkt gewählt
3
-
Ich habe schon einen Energieausweis
6
-
Ich möchte den Auftrag nicht weiter verfolgen
curl -X POST -H 'Content-Type: application/json' -d '{ "reason": 6 }' https://api.energieausweis48.de/v1/orders/1031921/cancellation?token=MeinIndividuellerToken
HTTP/1.1 200 OK Content-Type: application/json { "success": "Die Stornierungsanfrage wurde erstellt." }
Sollte der Auftrag nicht mehr stornierbar sein,
weil er zum Beispiel bereits fertiggestellt wurde oder bereits eine Stornierungsanfrage erstellt wurde,
dann erhalten Sie eine Antwort mit dem HTTP Status Code
422
.
Sobald sich der Auftrag im Status
Fertiggestellt
befindet, kann die URL zum PDF des fertigen Energieausweises über eine
GET
Anfrage an den Endpoint
/orders/$AUFTRAGSNUMMER/download
heraus gefunden werden.
curl https://api.energieausweis48.de/v1/orders/1031921/download?token=MeinIndividuellerToken
HTTP/1.1 200 OK Content-Type: application/json { "download": "https://api.energieausweis48.de/govalue/ea48download.php?order_id=1031921&event_hash=asdf" }
Sollte sich der Auftrag nicht im Status
Fertiggestellt
befinden, erhalten Sie eine Antwort mit dem HTTP Status Code
202
.
Wenn ein Energieausweis auf Basis von fehlerhaften Daten erstellt wird, sind wir dazu verpflichtet diesem beim deutschen Institut für Bautechnik (DIBt) für ungültig zu erklären.
Sie haben die Möglichkeit für einen Auftrag im Status
Ungültig
mit einer
GET
Anfrage an den Endpoint
/orders/$AUFTRAGSNUMMER/correct
eine Korrektur anzufordern.
Beim Anfordern einer Korrektur wird ein neuer Auftrag angelegt. Die ID des neuen Auftrags erhalten Sie in der Antwort der Anfrage.
curl https://api.energieausweis48.de/v1/orders/1031921/correct?token=MeinIndividuellerToken
HTTP/1.1 200 OK Content-Type: application/json { "new": 1031922 }
Sollte sich der Auftrag nicht im Status
Ungültig
befinden, erhalten Sie eine Antwort mit dem HTTP Status Code
403
.