Versionen

REST API v1

Die REST API v1 bietet die Möglichkeit den kompletten Prozess der Energieausweiserstellung zu starten und zu verfolgen.

Grundsätzliches

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.

Anfrage

curl
  -X POST
  -H 'Content-Type: application/json'
  -d '{"example":"example"}'
  https://api.energieausweis48.de/v1/example

Antwort

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.

Authentifizierung

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.

Token Übergabe

curl
  -X POST
  https://api.energieausweis48.de/v1/protected?token=MeinIndividuellerToken

Auftrag erteilen

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.

Produkt

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

Gebäudetyp

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

Auskunftsfähige Person

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.

Abweichende Rechnungsanschrift

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

Anfrage für Beauftragung

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.

Antwort einer Beauftragung

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.

Dokumente zum Auftrag hinzufügen

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.

Hochladen eines Dokuments

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.

Beispiel für Fehler beim Hochladen

{"code":"","http_code":422,"message":"'file' is empty"}

Auftragsstatus anzeigen

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

Anfrage zum Anzeigen des Auftragsstatus

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.

Antwort für das Anzeigen des Auftragsstatus

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"
      }
    ]
  }
}

Stornierung anfragen

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.

Stornierungsgrund

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

Anfrage für eine Stornierungsanfrage

curl
  -X POST
  -H 'Content-Type: application/json'
  -d '{
    "reason": 6
  }'
  https://api.energieausweis48.de/v1/orders/1031921/cancellation?token=MeinIndividuellerToken

Antwort bei einer erfolgreichen Stornierungsanfrage

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.

Energieausweis herunterladen

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.

Anfrage zum Erhalt der PDF URL des Energieausweises

curl https://api.energieausweis48.de/v1/orders/1031921/download?token=MeinIndividuellerToken

Antwort zum Erhalt der PDF URL des Energieausweises

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.

Korrektur für einen ungültigen Energieausweis anfordern

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.

Korrektur für einen ungültigen Auftrag anfordern

curl https://api.energieausweis48.de/v1/orders/1031921/correct?token=MeinIndividuellerToken

Die Antwort erhält die ID des neuen Auftrags

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.