BzA-API – Anleitung

Diese Schnittstelle nimmt eine Bestätigung zum Antrag (BzA) der KfW-Heizungsförderung für elektrisch angetriebene Wärmepumpen entgegen. Der Ablauf ist asynchron: Anfrage absenden → Energieberatung Schneider startet den Durchlauf → Status abfragen, bis das PDF bereitsteht.

Authentifizierung

Jede Anfrage benötigt den Header X-API-Key mit dem Ihnen zugeteilten Schlüssel. Ein fehlender oder ungültiger Schlüssel wird mit 404 beantwortet (nicht 401/403) – ein 404 auf dem Endpunkt bedeutet also nicht „offline".

Schritt 1 – Anfrage absenden

curl -X POST https://api.energieberater-schneider.com/v1/request-document \
  -H "X-API-Key: IHR_API_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "objekt": {
        "strasse": "Hagenburger Str.",
        "hausnummer": "1",
        "plz": "31515",
        "ort": "Wunstorf"
      },
      "wohneinheiten": 1,
      "wohnflaeche_m2": 100,
      "waermepumpe": { "typ_label": "Luft-Wasser-Wärmepumpe", "kw": 14 },
      "foerderfaehige_kosten": 28000,
      "klimageschwindigkeitsbonus": { "alte_heizung": "gas" }
    }
  }'

Antwort (202):

{ "jobId": "9f8e7d6c5b4a39281706f1e2d3c4b5a6", "status": "queued" }

Schritt 2 – Status abfragen

Die jobId aus Schritt 1 wiederholt abfragen, bis status = done (oder error):

curl https://api.energieberater-schneider.com/v1/request-document/JOB_ID \
  -H "X-API-Key: IHR_API_SCHLUESSEL"

Solange der Durchlauf noch nicht gestartet wurde oder wartet: { "status": "queued" }. Während der Verarbeitung: { "status": "running" }. Wenn fertig:

{
  "jobId": "9f8e...",
  "status": "done",
  "finishedAt": "2026-06-25T18:42:10+00:00",
  "pdfUrl": "https://storage.googleapis.com/.../bza.pdf?..."
}

Das PDF unter pdfUrl herunterladen – der Link ist 1 Stunde gültig (bei Ablauf einfach erneut abfragen).

Felder

Feld	Typ	Pflicht	Hinweis
objekt.strasse / hausnummer / plz / ort	Text	ja	Adresse des Objekts
wohneinheiten	Ganzzahl ≥ 1	ja	Anzahl Wohneinheiten (WE)
wohnflaeche_m2	Zahl	ja	Wohnfläche in m²
waermepumpe.typ_label	Text	ja	z. B. "Luft-Wasser-Wärmepumpe"
waermepumpe.kw	Zahl	ja	Nennleistung (kW)
foerderfaehige_kosten	Zahl (€)	ja	wird auf die Höchstgrenze gedeckelt: 28.000 € für die erste WE, +15.000 € je WE 2–6, danach +8.000 € je WE
klimageschwindigkeitsbonus	Objekt	optional	{ "alte_heizung": "gas" | "biomasse" | "oel_kohle" } – weglassen, wenn kein Bonus

Optional: BzA per E-Mail

Auf oberster Ebene (neben data) kann email_kopie gesetzt werden. Bei true wird die fertige BzA zusätzlich als PDF-Anhang an Ihre bei uns hinterlegte E-Mail-Adresse gesendet. Standard ist false – dann erfolgt die Zustellung nur über die pdfUrl (Schritt 2).

{
  "email_kopie": true,
  "data": { ... wie oben ... }
}

Hinweise

• Bonusauswahl: Der Effizienzbonus ist nicht mehr Bestandteil dieses BzA-Ablaufs und wird nicht im KfW-Portal ausgewählt. Optional kann ausschließlich der Klimageschwindigkeitsbonus übermittelt werden.
• Asynchron mit Admin-Start: der POST liefert sofort eine jobId; danach den GET abfragen, bis status = done. Ein 202 bedeutet: Auftrag angenommen. Der echte KfW-Durchlauf startet erst nach Freigabe durch Energieberatung Schneider.
• Validierung: fehlende/ungültige Felder ergeben 400 mit {"error": "..."} – bevor ein Auftrag angelegt wird. Ein 202 heißt also: Eingabe akzeptiert.
• Kostendeckelung: liegt foerderfaehige_kosten über der Höchstgrenze, wird gedeckelt und die 202-Antwort enthält "foerderfaehigeKostenCappedTo": <Betrag>.
• Idempotenz (empfohlen bei Wiederholungen): Header Idempotency-Key: <eindeutige-id> beim POST mitsenden. Eine Wiederholung mit gleichem Schlüssel liefert denselben Auftrag zurück, statt eine zweite BzA zu erzeugen.

Komplettes Beispiel-Skript

Anfrage absenden, warten und PDF speichern (benötigt jq; die Anfrage-Daten stehen in request.json):

#!/usr/bin/env bash
set -euo pipefail
API="https://api.energieberater-schneider.com/v1/request-document"
KEY="IHR_API_SCHLUESSEL"

# request.json enthält den {"data": {...}}-Body aus Schritt 1.
job=$(curl -sS -X POST "$API" -H "X-API-Key: $KEY" \
        -H "Content-Type: application/json" -d @request.json | jq -r .jobId)
echo "Job: $job"

while true; do
  resp=$(curl -sS "$API/$job" -H "X-API-Key: $KEY")
  status=$(echo "$resp" | jq -r .status)
  echo "  Status: $status"
  if [ "$status" = "error" ]; then echo "$resp" | jq .; exit 1; fi
  if [ "$status" = "done" ]; then
    url=$(echo "$resp" | jq -r .pdfUrl)
    curl -sS "$url" -o bza.pdf
    echo "Gespeichert: bza.pdf"
    break
  fi
  sleep 5
done

Zur Ausstellung eines API-Schlüssels oder bei Fragen wenden Sie sich an Heinrich Schneider.