Was Sie mit der API machen können

Verbinden Sie Ihre eigene Software mit Heizreport: eigene Projekte anlegen, Projektdaten vorbelegen und ändern, Räume lesen und erfassen, Förderanträge lesen, Berechnungsergebnisse abrufen sowie PDFs erzeugen und vorhandene Bilder auflisten.

Für geschützte Aufrufe benötigen Sie Ihren API-Token aus dem Pro-Bereich. Projektanlage, Berechnungen und PDFs setzen die jeweils passenden Lizenzrechte voraus. U-Werte schreiben, Heizkörper erfassen und Bilder hochladen sind noch nicht öffentlich verfügbar.

So starten Sie

1. Lesen Sie die einfache Übersicht mit Schnellstart und Beispielen.
2. Prüfen Sie Felder und Antworten in der Swagger-Referenz.
3. Laden Sie unter Downloads die Postman-Collection oder die Anleitungen für Ihre Entwicklungswerkzeuge herunter.

Die produktive API erreichen Sie ausschließlich unter https://heizreport.net/api/v2. Zum Ausprobieren ein eigenes Testprojekt verwenden und zwischen einzelnen Tests mindestens eine Sekunde warten.

Zugriffsschutz

Ein Token pro Kunde mit allen freigegebenen API-Rechten für eigene Projekte. Fest maximal 2 Zugriffe in jedem gleitenden Zeitraum von einer Sekunde, gemeinsam über alle geschützten Endpunkte. Das Limit gilt auch nach Tokenwechsel und kann nicht individuell erhöht werden.

Bei Überschreitung: HTTP 429 und Retry-After: 1. Bitte eine Sekunde warten und den Aufruf anschließend erneut versuchen. Fachlich abgelehnte authentifizierte Aufrufe zählen ebenfalls.

Neue Tokens werden nur bei Erstellung oder Erneuerung angezeigt. Bestehende Tokens bleiben gültig; gespeicherte Tokens können nicht erneut angezeigt werden.

JSON-Bodies: maximal 64 KiB und Content-Type: application/json. Unbekannte Felder, falsche Typen und ungültige Werte liefern 422. projectData und projektData dürfen nicht gemeinsam übermittelt werden. Fremde oder nicht vorhandene Projekte liefern 404.

Projektanlage benötigt eine aktive Jahres- oder Bildungslizenz. Berechnungen und PDFs prüfen die Projekt- und Lizenzrechte wie in Pro. Die Datenerfassung bleibt auch bei abgelaufener Lizenz für entsperrte Kunden verfügbar.

Förderanträge lesen ab v2.5.0

Eigene Förderanträge lassen sich ausschließlich lesend mit ihren Kernfeldern abrufen: BzA-ID, BnD-ID, Bearbeitungsstatus, zuständiger Energieberater und Bearbeitungszeitpunkte.

Listen liefern applications[], total, page und limit; Einzelantworten enthalten application. Die Hülle enthält außerdem status: 200 und action. Paginierung: ?page=1&limit=50, maximal 100 Anträge pro Seite, maximaler Seitenwert 1000000. Sortierung nach Antrags-ID absteigend; Seiten hinter dem Ende sind leer. Bei parallelen Änderungen können sich Seiten verschieben. Unbekannte oder ungültige Listenparameter liefern 422.

Der Token gilt nur für eigene Anträge. Fremde und fehlende Anträge liefern beide 404. Der Projektabruf prüft zusätzlich den Projektbesitz; eigene Projekte ohne Anträge liefern eine leere Liste. Projektvarianten werden nicht automatisch zusammengefasst. Das Lesen ist für entsperrte Kunden auch bei abgelaufener Jahreslizenz verfügbar. Das gemeinsame Limit von zwei Zugriffen pro Sekunde bleibt bestehen.

IDs des Antrags und Beraters sowie BzA/BnD sind Zeichenketten. projectId ist eine Zahl oder null. Fehlende Werte sind null; Zeitpunkte verwenden ISO 8601 in UTC. Historische 0/1-Flags ergeben kein Datum. proofs_waiting, proofs_review und proofs_corrections unterscheiden fehlende Nachweise, Prüfung und Korrektur. done bedeutet BnD fertig; completed bedeutet Auszahlung abgeschlossen. Verwenden Sie status zur Automatisierung. statusStep ist keine Prozentangabe.

Ein vollständiges Antwortbeispiel und alle Statuswerte stehen in der API-Referenz sowie den aktualisierten OpenAPI-, Postman- und KI-Anleitungsdownloads. Diese Endpunkte enthalten keine zusätzlichen Kunden-, Nachweis- oder Dokumentdaten und bieten keine Schreiboperationen.

Projektdetails und Räume ab v2.4.0

Die API kann jetzt Projektdetails und Raumbasisdaten lesen sowie Räume anlegen und ändern. Alle Aufrufe benötigen den Kundentoken und zählen zum gemeinsamen Limit von zwei Zugriffen pro Sekunde. Die Datenerfassung bleibt für entsperrte Kunden auch bei abgelaufener Jahreslizenz möglich.

Raum anlegen

POST mit Content-Type: application/json. Der Raumname ist Pflicht. Den neuen Schlüssel aus room.id übernehmen und für spätere Aufrufe verwenden.

{
  "roomData": {
    "raumBezeichnung": "Wohnzimmer",
    "raumEtage": 1,
    "raumFlaeche": 25.5,
    "raumHoehe": 2.5,
    "raumTemperatur": 20,
    "raumNotiz": "Erfasst über die Kunden-API"
  }
}

Erlaubte Raumfelder

Geschoss-ID und Bezeichnungen

raumEtage wird als ID gesendet und in Antworten als Zeichenkette ausgegeben. Standard bei Anlage ist 1 (Erdgeschoss).

Jeder Raum enthält in roomData zusätzlich raumEtageBezeichnung und raumEtageKuerzel: bei Einzelabruf, in Raumlisten und nach Anlage oder Änderung. Diese beiden Felder werden aus der ID abgeleitet und dürfen nicht als Eingaben gesendet werden. Bei fehlender oder unbekannter gespeicherter ID sind beide leer.

Beispiel-Ausschnitt aus roomData:

{"raumEtage":"1","raumEtageBezeichnung":"Erdgeschoss","raumEtageKuerzel":"EG"}

raumTemperatur wird in °C gesendet und als JSON-Zahl zurückgegeben. Für 20 °C bitte 20 senden. Erlaubt sind 7 und die ganzen Temperaturen 16–26; andere Werte liefern 422. Die Umrechnung in interne Datenbank-IDs übernimmt die API. Bei fehlender oder unbekannter gespeicherter ID enthält die Antwort null.

Zahlen können als JSON-Zahl oder numerische Zeichenkette gesendet werden. Fläche/Höhe unterstützen auch Dezimalkomma; maximal 32 Zeichen. Geschoss und Temperatur sind ganzzahlig. Unbekannte Felder, boolesche Zahlenwerte, Arrays und Objekte als Feldwerte liefern 422.

Raum ändern und Antworten lesen

PATCH verwendet ebenfalls die Hülle roomData. Nicht übermittelte Felder bleiben erhalten:

{"roomData":{"raumNotiz":"Neue Notiz","raumTemperatur":22}}

Einzelantworten enthalten room, die Liste enthält rooms[]. Jeder Eintrag hat id, projectKey und roomData. Feldwerte in roomData werden als Zeichenketten zurückgegeben; raumTemperatur ist eine JSON-Zahl in °C (oder null bei unbekanntem gespeichertem Wert). raumBaujahr ist zusätzlich lesbar und wird bei Anlage aus dem Projekt übernommen; spätere Projektänderungen führen es nicht automatisch nach.

Eine Raum-ID muss zum angegebenen eigenen Projekt gehören. Ein Raum eines anderen Projekts liefert 404, auch wenn beide Projekte demselben Kunden gehören. Raum-ID, Projektzuordnung, Baujahr, U-Werte und Heizflächen können hier nicht geschrieben werden.

Raum-Anlage und Projektaktivität werden gemeinsam gespeichert. Bei Anlage wird der Projektstatus auf „in Bearbeitung“ (2) gesetzt; abgeschlossene/archivierte Projekte (4/5) behalten ihren Status. PATCH aktualisiert die Aktivität und behält den Projektstatus bei.

Raumbasisdaten allein reichen noch nicht für eine vollständige Heizlastberechnung. Bauteile und U-Werte werden nicht automatisch ergänzt. Nach einem Verbindungsabbruch vor Wiederholung einer Anlage zuerst die Raumliste prüfen, damit kein doppelter Raum entsteht.

Ergebnisdaten und Fußbodenheizung

Der Ergebnisendpunkt nutzt die aktuelle Berechnungsstruktur. Fußbodenheizkreise stehen unter results.floorHeatingBalance.groups[].rooms[].

Bestehende Kundenintegrationen können weiterhin unverändert projekt.abgleichFBH[].raeume[].durchfluss verwenden. Beide Strukturen werden aus denselben Berechnungswerten erzeugt; durchfluss entspricht dem Einstellwert in l/min.

GET /api/v2/reports/abcdefghi/results
Authorization: Bearer DEIN_API_TOKEN
Accept: application/json

Antwortbeispiel

{
  "status": 200,
  "action": "getResults",
  "project": {
    "key": "abcdefghi"
  },
  "results": {
    "available": true,
    "status": "calculated",
    "source": "api-v2-core",
    "summary": {},
    "roomHeatLoads": [],
    "radiators": [],
    "hydraulicBalance": {},
    "floorHeatingBalance": {
      "groups": [
        {
          "spread": 10,
          "flowRateSum": 73,
          "flowRateUnit": "l/h",
          "rooms": [
            {
              "surfaceId": "123-floorHeatingRaw-0",
              "roomName": "Wohnzimmer",
              "floorLabel": "Erdgeschoss",
              "heatingLoad": 850,
              "spread": 10,
              "flowRate": 73,
              "flowLpm": 1.22,
              "setting": {
                "value": 1.22,
                "unit": "l/min"
              }
            }
          ]
        }
      ]
    },
    "heatpump": {},
    "exchange": {}
  },
  "projekt": {
    "abgleichFBH": [
      {
        "raeume": [
          {
            "raumBezeichnung": "Wohnzimmer",
            "heizlast": 850,
            "durchfluss": 1.22
          }
        ],
        "spreizung": 10,
        "summeVolumenstrom": 73
      }
    ]
  }
}

Kompatibilitätsstruktur

Die Namen und Verschachtelung von projekt.abgleichFBH bleiben gegenüber der bisherigen API unverändert:

projekt.abgleichFBH[]
├── spreizung
├── summeVolumenstrom
└── raeume[]
    ├── raumBezeichnung
    ├── heizlast
    └── durchfluss

Optionale Systemtemperatur

Vorlauftemperatur und Spreizung können gemeinsam vorgegeben werden. Die Werte beeinflussen Heizkörper- und Hydraulikberechnung; die FBH-Gruppen werden weiterhin für 10, 7 und 5 K ausgegeben.

GET /api/v2/reports/abcdefghi/results?flowTemperature=55&spread=10

Die bisherigen Parameternamen vorlaufT und spreizung werden ebenfalls unterstützt.

Webhook bei der ersten PDF-Erstellung

Ist im Pro-Bereich unter Integrationen → API eine Webhook-Adresse hinterlegt, sendet Heizreport genau einmal pro Projekt einen JSON-POST. Auslöser ist die erste erfolgreiche PDF-Erstellung – sowohl über den PDF-Endpunkt der API als auch über die zentrale Dokumenterstellung im Kundenportal. Fehlgeschlagene PDF-Erstellungen lösen keinen Webhook aus.

Als erfolgreiche Zustellung gilt jede Antwort mit HTTP-Status 2xx. Die PDF bleibt auch dann verfügbar, wenn das Webhook-Ziel nicht erreichbar ist oder einen Fehlerstatus liefert. Das Ziel muss öffentlich erreichbar sein; Weiterleitungen und private beziehungsweise reservierte IP-Adressen werden nicht zugelassen.

POST https://example.org/heizreport-webhook
Content-Type: application/json
X-Heizreport-Event: pdf.generated
X-Heizreport-Delivery: 28f67e0a29cc4f98a89e9cff1bd9acaf

{
  "event": "webhookheizreport",
  "eventType": "pdf.generated",
  "eventId": "28f67e0a29cc4f98a89e9cff1bd9acaf",
  "authenticate": "DEIN_WEBHOOK_AUTH_WERT",
  "projektKey": "abcdefghi",
  "projectKey": "abcdefghi",
  "generatedAt": "2026-09-02T12:00:00+00:00",
  "document": {
    "id": 12345,
    "type": "heizreport",
    "name": "heizreport_komplett.pdf",
    "size": 482193,
    "url": "https://heizreport.net/files.php?...",
    "viewerUrl": "https://heizreport.net/files.php?...",
    "temporary": false
  }
}

event behält mit webhookheizreport beziehungsweise webhookcheck das bisher vorgesehene Format bei; eventType bezeichnet das neue stabile Ereignis. eventId ist die eindeutige Zustell-ID. authenticate enthält unverändert den in den API-Einstellungen hinterlegten Wert. Bei temporären Download-Dokumenten ist document.id gleich 0 und document.temporary gleich true.