Heizreport Customer API v2

Base URL: https://heizreport.net/api/v2

Authentifizierung: Authorization: Bearer DEIN_API_TOKEN

Endpunkte

GET/health

GET/reports

POST/reports

POST/reports/with-data

PATCH/reports/{projectKey}

PUT/reports/{projectKey}/password

GET/reports/{projectKey}/pictures

GET/reports/{projectKey}/pdf?type=heizreport

GET/reports/{projectKey}/results

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

Feld	Bedeutung	Einheit
`spread`	Temperaturspreizung des FBH-Kreises	K
`heatingLoad`	Anteilige Heizlast der Heizfläche	W
`flowRate`	Volumenstrom des einzelnen Kreises	l/h
`flowLpm`	Volumenstrom für die Anzeige am Verteiler	l/min
`setting.value`	Einzustellender Wert am Heizkreisverteiler	siehe `setting.unit`
`flowRateSum`	Summe der Gruppe bei gleicher Spreizung	l/h
`projekt.abgleichFBH[].raeume[].durchfluss`	Kompatibler bisheriger Einstellwert	l/min

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

Projekt mit Daten anlegen

POST /api/v2/reports/with-data
Content-Type: application/json

{
  "projectData": {
    "projektName": "Max Mustermann",
    "projektPostleitzahl": "10115"
  }
}

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.

Fehlerformat

{
  "status": 422,
  "error": "Ergebnisse sind noch nicht verfügbar",
  "details": {
    "type": "calculation_unavailable"
  }
}