---
title: "Exposé erstellen"
url: "https://maklerportal.apim.eu/apis/expose-erstellen/versions/68a05fe4-408a-4a77-bd68-eebadc995624"
---

# Exposé erstellen

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Exposé erstellen","version":"1.0.0","description":"Erzeugt aus strukturierten Objektdaten ein fertiges Exposé – als PDF und als\nWeb-Ansicht – und veröffentlicht es auf den gewünschten Kanälen.\n\nEin Exposé referenziert immer genau ein Objekt aus der **Objektverwaltung**.\nFreie Exposés ohne Objektbezug gibt es bewusst nicht, damit Pflichtangaben\nund Historie an einer Stelle gepflegt werden.\n\n## Ablauf\n\n1. `POST /exposes` startet die Generierung. Die Antwort trägt `status: \"in_arbeit\"`.\n2. Sobald das Dokument gesetzt ist, wechselt der Status auf `fertig`. Wir empfehlen\n   das Ereignis `expose.fertiggestellt` statt wiederholter Abfragen.\n3. `GET /exposes/{exposeId}/pdf` liefert das Dokument.\n4. `POST /exposes/{exposeId}/veroeffentlichen` stellt es auf den Kanälen ein.\n\n## Pflichtangaben\n\nVor der Veröffentlichung prüft die API die anzeigepflichtigen Angaben – vor allem\ndie Kennwerte aus dem Energieausweis und die Provisionsangabe. Fehlt etwas,\nantwortet die API mit `422` und `code: \"pflichtangabe_fehlt\"`.\n","contact":{"name":"API-Support Objektwerk GmbH","email":"api-support@objektwerk.example"},"license":{"name":"Nur zu Demonstrationszwecken"}},"servers":[{"url":"https://api.maklerportal.example/v1","description":"Produktion"},{"url":"https://sandbox.api.maklerportal.example/v1","description":"Sandbox – Bestand wird nächtlich zurückgesetzt"}],"tags":[{"name":"Exposés","description":"Erzeugen, abrufen und veröffentlichen"},{"name":"Vorlagen","description":"Gestaltungsvorlagen des Mandanten"}],"security":[{"apiKey":[]}],"paths":{"/exposes":{"get":{"tags":["Exposés"],"summary":"Exposés auflisten","description":"Liefert die Exposés des Mandanten, optional gefiltert nach Objekt und Status.","operationId":"exposesAuflisten","parameters":[{"name":"objekt_id","in":"query","description":"Nur Exposés zu diesem Objekt.","schema":{"type":"string","example":"obj_8f2c1a"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/ExposeStatus"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","description":"Cursor aus `seite.cursor_naechste` der vorigen Antwort.","schema":{"type":"string"}}],"responses":{"200":{"description":"Trefferliste","content":{"application/json":{"schema":{"type":"object","properties":{"daten":{"type":"array","items":{"$ref":"#/components/schemas/Expose"}},"seite":{"$ref":"#/components/schemas/Seite"}}}}}},"401":{"$ref":"#/components/responses/NichtAuthentifiziert"},"429":{"$ref":"#/components/responses/ZuVieleAnfragen"}}},"post":{"tags":["Exposés"],"summary":"Exposé erstellen","description":"Startet die Generierung eines Exposés aus einem Objekt und einer Vorlage.\nDie Verarbeitung läuft asynchron; die Antwort trägt zunächst `status: \"in_arbeit\"`.\n","operationId":"exposeErstellen","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExposeAnlegen"},"examples":{"standard":{"summary":"Eigentumswohnung mit Standardabschnitten","value":{"objekt_id":"obj_8f2c1a","vorlage_id":"vrl_klassik","sprache":"de","abschnitte":["lage","ausstattung","energie","grundriss","provision"]}},"zweisprachig":{"summary":"Englische Fassung für internationale Interessenten","value":{"objekt_id":"obj_8f2c1a","vorlage_id":"vrl_modern","sprache":"en","abschnitte":["lage","ausstattung","energie"]}}}}}},"responses":{"202":{"description":"Generierung angenommen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expose"},"example":{"id":"exp_4d9b2e","objekt_id":"obj_8f2c1a","vorlage_id":"vrl_klassik","sprache":"de","status":"in_arbeit","erstellt_am":"2026-08-20T09:41:12Z"}}}},"400":{"$ref":"#/components/responses/Validierungsfehler"},"401":{"$ref":"#/components/responses/NichtAuthentifiziert"},"403":{"$ref":"#/components/responses/ScopeFehlt"},"404":{"description":"Objekt oder Vorlage nicht gefunden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"429":{"$ref":"#/components/responses/ZuVieleAnfragen"}}}},"/exposes/{exposeId}":{"parameters":[{"$ref":"#/components/parameters/ExposeId"}],"get":{"tags":["Exposés"],"summary":"Exposé abrufen","description":"Liefert Status, Metadaten und den Prüfbericht der Pflichtangaben.","operationId":"exposeAbrufen","responses":{"200":{"description":"Exposé","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expose"}}}},"401":{"$ref":"#/components/responses/NichtAuthentifiziert"},"404":{"$ref":"#/components/responses/NichtGefunden"}}},"delete":{"tags":["Exposés"],"summary":"Exposé zurückziehen","description":"Nimmt ein Exposé von allen Kanälen und markiert es als `zurueckgezogen`.\nDas Dokument bleibt zu Nachweiszwecken abrufbar.\n","operationId":"exposeZurueckziehen","responses":{"204":{"description":"Zurückgezogen"},"401":{"$ref":"#/components/responses/NichtAuthentifiziert"},"404":{"$ref":"#/components/responses/NichtGefunden"}}}},"/exposes/{exposeId}/pdf":{"parameters":[{"$ref":"#/components/parameters/ExposeId"}],"get":{"tags":["Exposés"],"summary":"Exposé als PDF laden","description":"Liefert das gesetzte Dokument. Erst verfügbar, wenn `status` auf `fertig` steht –\nvorher antwortet die API mit `409`.\n","operationId":"exposePdfLaden","responses":{"200":{"description":"PDF-Dokument","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/NichtAuthentifiziert"},"404":{"$ref":"#/components/responses/NichtGefunden"},"409":{"description":"Generierung noch nicht abgeschlossen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"},"example":{"code":"konflikt","nachricht":"Das Exposé wird noch erzeugt.","details":[{"feld":"status","grund":"in_arbeit"}]}}}}}}},"/exposes/{exposeId}/veroeffentlichen":{"parameters":[{"$ref":"#/components/parameters/ExposeId"}],"post":{"tags":["Exposés"],"summary":"Exposé veröffentlichen","description":"Stellt das Exposé auf den gewählten Kanälen ein. Vorher werden die\nPflichtangaben geprüft.\n","operationId":"exposeVeroeffentlichen","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kanaele"],"properties":{"kanaele":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Kanal"}},"geplant_ab":{"type":"string","format":"date-time","description":"Optionaler Zeitpunkt für eine spätere Veröffentlichung."}}},"example":{"kanaele":["portal","website","newsletter"]}}}},"responses":{"200":{"description":"Veröffentlicht bzw. eingeplant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Veroeffentlichung"}}}},"401":{"$ref":"#/components/responses/NichtAuthentifiziert"},"404":{"$ref":"#/components/responses/NichtGefunden"},"422":{"description":"Fachliche Pflichtangaben fehlen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"},"examples":{"energieausweis":{"summary":"Kennwerte aus dem Energieausweis fehlen","value":{"code":"pflichtangabe_fehlt","nachricht":"Für die Veröffentlichung fehlen Pflichtangaben aus dem Energieausweis.","details":[{"feld":"energieausweis.endenergiebedarf_kwh","grund":"fehlt"},{"feld":"energieausweis.gueltig_bis","grund":"abgelaufen"}]}},"provision":{"summary":"Käuferanteil übersteigt Verkäuferanteil","value":{"code":"provision_unzulaessig","nachricht":"Der Käuferanteil der Courtage darf den Verkäuferanteil nicht übersteigen.","details":[{"feld":"provision.kaeufer_prozent","grund":"groesser_als_verkaeufer"}]}}}}}}}}},"/vorlagen":{"get":{"tags":["Vorlagen"],"summary":"Vorlagen auflisten","description":"Die Gestaltungsvorlagen des Mandanten, jeweils mit den unterstützten Abschnitten.","operationId":"vorlagenAuflisten","responses":{"200":{"description":"Vorlagen","content":{"application/json":{"schema":{"type":"object","properties":{"daten":{"type":"array","items":{"$ref":"#/components/schemas/Vorlage"}}}},"example":{"daten":[{"id":"vrl_klassik","name":"Klassik","beschreibung":"Zurückhaltendes Layout mit großem Titelbild.","abschnitte":["lage","ausstattung","energie","grundriss","provision"]},{"id":"vrl_modern","name":"Modern","beschreibung":"Zweispaltig, kräftige Typografie, für Neubauprojekte.","abschnitte":["lage","ausstattung","energie"]}]}}}},"401":{"$ref":"#/components/responses/NichtAuthentifiziert"}}}}},"components":{"parameters":{"ExposeId":{"name":"exposeId","in":"path","required":true,"description":"Kennung des Exposés.","schema":{"type":"string","example":"exp_4d9b2e"}}},"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"apikey","description":"Jeder Aufruf trägt einen API-Schlüssel im Header `apikey`. Den Schlüssel\nerzeugen Sie im Maklerportal unter \"Meine Anwendungen\"; er wird genau einmal\nangezeigt.\n\nAn jedem Schlüssel hängen die Scopes, die er nutzen darf. Fehlt einer,\nantwortet die API mit `403` und `code: \"scope_fehlt\"`; der fehlende Scope\nsteht in `details[].feld`.\n"}},"responses":{"NichtAuthentifiziert":{"description":"Schlüssel fehlt, ist gesperrt oder ungültig","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"},"example":{"code":"nicht_authentifiziert","nachricht":"Der API-Schlüssel ist ungültig oder wurde zurückgezogen.","details":[]}}}},"ScopeFehlt":{"description":"Dem Schlüssel fehlt der nötige Scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"},"example":{"code":"scope_fehlt","nachricht":"Dem API-Schlüssel fehlt ein erforderlicher Scope.","details":[{"feld":"exposes:schreiben","grund":"nicht_erteilt"}]}}}},"NichtGefunden":{"description":"Das Exposé existiert nicht","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"Validierungsfehler":{"description":"Die Anfrage entspricht nicht dem Schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}},"ZuVieleAnfragen":{"description":"Rate Limit erreicht","headers":{"Retry-After":{"description":"Wartezeit in Sekunden","schema":{"type":"integer","example":12}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fehler"}}}}},"schemas":{"ExposeStatus":{"type":"string","description":"Lebenszyklus eines Exposés.","enum":["in_arbeit","fertig","veroeffentlicht","zurueckgezogen","fehlgeschlagen"],"example":"fertig"},"Kanal":{"type":"string","description":"Veröffentlichungskanal.","enum":["portal","website","newsletter","schaufenster"]},"Abschnitt":{"type":"string","description":"Inhaltlicher Block des Exposés.","enum":["lage","ausstattung","energie","grundriss","provision","umgebung","historie"]},"ExposeAnlegen":{"type":"object","required":["objekt_id","vorlage_id"],"properties":{"objekt_id":{"type":"string","description":"Objekt, aus dem das Exposé erzeugt wird.","example":"obj_8f2c1a"},"vorlage_id":{"type":"string","description":"Gestaltungsvorlage des Mandanten.","example":"vrl_klassik"},"sprache":{"type":"string","description":"Sprache des erzeugten Dokuments.","enum":["de","en"],"default":"de"},"abschnitte":{"type":"array","description":"Reihenfolge und Auswahl der Abschnitte. Ohne Angabe gelten die der Vorlage.","items":{"$ref":"#/components/schemas/Abschnitt"}},"notiz_intern":{"type":"string","maxLength":500,"description":"Interne Bemerkung, erscheint nicht im Dokument.","example":"Eigentümerin wünscht Besichtigungen erst ab dem 1. September."}}},"Expose":{"type":"object","properties":{"id":{"type":"string","example":"exp_4d9b2e"},"objekt_id":{"type":"string","example":"obj_8f2c1a"},"vorlage_id":{"type":"string","example":"vrl_klassik"},"sprache":{"type":"string","example":"de"},"status":{"$ref":"#/components/schemas/ExposeStatus"},"pdf_url":{"type":"string","format":"uri","description":"Nur bei `status: fertig` gesetzt. Der Link ist 24 Stunden gültig.","example":"https://api.maklerportal.example/v1/exposes/exp_4d9b2e/pdf"},"seiten":{"type":"integer","description":"Seitenzahl des erzeugten Dokuments.","example":6},"pflichtangaben":{"$ref":"#/components/schemas/Pflichtangabenbericht"},"erstellt_am":{"type":"string","format":"date-time","example":"2026-08-20T09:41:12Z"},"fertig_am":{"type":"string","format":"date-time","nullable":true,"example":"2026-08-20T09:41:20Z"}}},"Pflichtangabenbericht":{"type":"object","description":"Ergebnis der Prüfung anzeigepflichtiger Angaben.","properties":{"vollstaendig":{"type":"boolean","example":false},"fehlend":{"type":"array","items":{"$ref":"#/components/schemas/Fehlerdetail"}}}},"Veroeffentlichung":{"type":"object","properties":{"expose_id":{"type":"string","example":"exp_4d9b2e"},"status":{"$ref":"#/components/schemas/ExposeStatus"},"kanaele":{"type":"array","items":{"type":"object","properties":{"kanal":{"$ref":"#/components/schemas/Kanal"},"zustand":{"type":"string","enum":["live","geplant","fehlgeschlagen"]},"url":{"type":"string","format":"uri"}}}},"veroeffentlicht_am":{"type":"string","format":"date-time","example":"2026-08-20T09:44:03Z"}}},"Vorlage":{"type":"object","properties":{"id":{"type":"string","example":"vrl_klassik"},"name":{"type":"string","example":"Klassik"},"beschreibung":{"type":"string","example":"Zurückhaltendes Layout mit großem Titelbild."},"abschnitte":{"type":"array","items":{"$ref":"#/components/schemas/Abschnitt"}}}},"Seite":{"type":"object","description":"Cursor-basierte Paginierung.","properties":{"anzahl":{"type":"integer","example":25},"gesamt":{"type":"integer","example":138},"cursor_naechste":{"type":"string","nullable":true,"example":"eyJzIjoyNX0"}}},"Fehlerdetail":{"type":"object","properties":{"feld":{"type":"string","example":"energieausweis.endenergiebedarf_kwh"},"grund":{"type":"string","example":"fehlt"}}},"Fehler":{"type":"object","description":"Einheitliches Fehlerformat aller Maklerportal-APIs.","required":["code","nachricht"],"properties":{"code":{"type":"string","example":"pflichtangabe_fehlt"},"nachricht":{"type":"string","example":"Für die Veröffentlichung fehlen Pflichtangaben aus dem Energieausweis."},"details":{"type":"array","items":{"$ref":"#/components/schemas/Fehlerdetail"}}}}}}}
```