Vom Objekt zum Exposé

Fünf Schritte, die sich vollständig automatisieren lassen – vom leeren Datensatz bis zum veröffentlichten Dokument.

Schritt 1: Objekt anlegen

Ein Exposé entsteht nie aus dem Nichts – es referenziert immer ein Objekt. Legen Sie es zuerst über die Objektverwaltung an.

curl -X POST https://api.maklerportal.example/v1/objekte \
  -H "apikey: $MAKLERPORTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "typ": "wohnung",
        "titel": "3-Zimmer-Altbau am Falkenried",
        "adresse": { "strasse": "Falkenried 42", "plz": "20251", "ort": "Hamburg" },
        "wohnflaeche_qm": 86.5,
        "zimmer": 3,
        "baujahr": 1908,
        "kaufpreis_eur": 645000,
        "provision": { "kaeufer_prozent": 3.57, "hinweis": "inkl. gesetzlicher USt." },
        "energieausweis": {
          "art": "verbrauchsausweis",
          "endenergiebedarf_kwh": 118.4,
          "energietraeger": "fernwaerme",
          "effizienzklasse": "D",
          "gueltig_bis": "2031-04-30"
        }
      }'

Der Block energieausweis ist beim Anlegen optional, für die spätere Veröffentlichung aber verpflichtend. Siehe Pflichtangaben.

Schritt 2: Medien hochladen

Bilder und Grundrisse werden dem Objekt zugeordnet, nicht dem Exposé. So stehen sie allen späteren Exposés und Vorlagen zur Verfügung.

curl -X POST https://api.maklerportal.example/v1/objekte/obj_8f2c1a/medien \
  -H "apikey: $MAKLERPORTAL_API_KEY" \
  -F "datei=@wohnzimmer.jpg" \
  -F "kategorie=innenansicht" \
  -F "reihenfolge=1"

Empfohlen sind mindestens ein Titelbild (kategorie=titelbild) und ein Grundriss (kategorie=grundriss). Fehlt das Titelbild, greift die Vorlage auf eine neutrale Platzhaltergrafik zurück.

Wer den Ablauf zuerst ohne Code sehen möchte: Der Exposé-Generator nimmt dieselben Objektdaten über ein Formular entgegen und erzeugt daraus per Sprachmodell einen fertigen Exposé-Text – der Aufruf läuft über das Kong AI Gateway.

curl -X POST https://api.maklerportal.example/v1/exposes \
  -H "apikey: $MAKLERPORTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "objekt_id": "obj_8f2c1a",
        "vorlage_id": "vrl_klassik",
        "sprache": "de",
        "abschnitte": ["lage", "ausstattung", "energie", "grundriss", "provision"]
      }'

{
  "id": "exp_4d9b2e",
  "objekt_id": "obj_8f2c1a",
  "vorlage_id": "vrl_klassik",
  "status": "in_arbeit",
  "erstellt_am": "2026-08-20T09:41:12Z"
}

Die Generierung ist asynchron, weil Bilder skaliert und das PDF gesetzt werden muss. Üblich sind zwei bis zehn Sekunden.

Schritt 4: Ergebnis abholen

Zwei Wege führen zum fertigen Dokument:

Ereignisgesteuert (empfohlen). Abonnieren Sie expose.fertiggestellt; der Webhook trägt die Exposé-ID und den Download-Link. Siehe Webhooks.

Abfragend. Fragen Sie GET /exposes/{id} mit ansteigendem Abstand ab (1 s, 2 s, 4 s, 8 s), bis status auf fertig steht:

curl https://api.maklerportal.example/v1/exposes/exp_4d9b2e/pdf \
  -H "apikey: $MAKLERPORTAL_API_KEY" \
  -o expose-falkenried.pdf

Der Link aus pdf_url ist 24 Stunden gültig. Speichern Sie das Dokument, statt den Link weiterzugeben.

Schritt 5: Veröffentlichen

curl -X POST https://api.maklerportal.example/v1/exposes/exp_4d9b2e/veroeffentlichen \
  -H "apikey: $MAKLERPORTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kanaele": ["portal", "website", "newsletter"] }'

Vor der Veröffentlichung prüft die API die Pflichtangaben. Fehlt etwas, kommt 422:

{
  "code": "pflichtangabe_fehlt",
  "nachricht": "Für die Veröffentlichung fehlen Pflichtangaben aus dem Energieausweis.",
  "details": [
    { "feld": "energieausweis.endenergiebedarf", "grund": "fehlt" }
  ]
}

Ergänzen Sie die Angabe am Objekt, generieren Sie das Exposé neu und veröffentlichen Sie erneut. Ein bereits erzeugtes Exposé wird nicht nachträglich verändert – das hält die Historie nachvollziehbar.

Typische Stolpersteine

Exposé ohne Objektbezug. objekt_id ist Pflicht; freie Exposés gibt es bewusst nicht.
Vorlage aus einer anderen Mandanteneinheit. vorlage_id muss zu Ihrem Mandanten gehören, sonst 404.
PDF zu früh abgeholt. Vor status: "fertig" liefert /pdf ein 409.
Preisänderung ohne Neugenerierung. Ein geändertes Objekt aktualisiert bestehende Exposés nicht automatisch.