Energieausweis48 Logo

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.

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.

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

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:

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.

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.