1. Zugang anfordern

Registrieren Sie sich mit Ihrer geschäftlichen E-Mail-Adresse. Wir gleichen den Eintrag mit Ihrer Gewerbeerlaubnis nach § 34c GewO ab; die Freischaltung erfolgt in der Regel am nächsten Werktag.

Bis zur Freischaltung steht Ihnen die Sandbox offen. Sie enthält einen vollständigen Beispielbestand aus zwölf Objekten, dreißig Interessenten und einer Handvoll Terminen. Daten in der Sandbox werden jede Nacht zurückgesetzt.

2. Anwendung anlegen

Jede Integration ist eine eigene Anwendung. Legen Sie unter Meine Anwendungen eine an und wählen Sie die APIs aus, die sie nutzen darf.

Vergeben Sie pro Umgebung eine eigene Anwendung – so lässt sich ein Schlüssel einzeln zurückziehen, ohne den Produktivbetrieb zu unterbrechen.

3. API-Schlüssel erzeugen

Zu jeder Anwendung erzeugen Sie einen API-Schlüssel. Er wird genau einmal angezeigt – danach lässt er sich nicht mehr auslesen, nur ersetzen.

mp_live_7f3c9a24b1e84d05a6c2f8e1d3b70945

Am Schlüssel hängen die Scopes, die er nutzen darf. Vergeben Sie nur, was der jeweilige Prozess wirklich braucht: Ein Import-Job kommt ohne Schreibrechte auf Provisionen aus.

Bewahren Sie den Schlüssel in einem Secret-Store auf, nicht in der Versionsverwaltung.

4. Erster Aufruf

Der Schlüssel geht bei jedem Aufruf im Header apikey mit. Der schnellste sinnvolle Aufruf ist die Liste Ihrer Objekte:

curl "https://api.maklerportal.example/v1/objekte?status=aktiv&limit=5" \
  -H "apikey: $MAKLERPORTAL_API_KEY"

{
  "daten": [
    {
      "id": "obj_8f2c1a",
      "typ": "wohnung",
      "titel": "3-Zimmer-Altbau am Falkenried",
      "adresse": { "strasse": "Falkenried 42", "plz": "20251", "ort": "Hamburg" },
      "wohnflaeche_qm": 86.5,
      "kaufpreis_eur": 645000,
      "status": "aktiv"
    }
  ],
  "seite": { "anzahl": 1, "gesamt": 12, "cursor_naechste": null }
}

5. Das erste Exposé

Mit einer Objekt-ID und einer Vorlage erzeugen Sie ein Exposé:

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

Die Generierung läuft asynchron. Die Antwort enthält den Status in_arbeit; sobald fertig erreicht ist, liefert GET /exposes/{id}/pdf das fertige Dokument. Alternativ abonnieren Sie das Ereignis expose.fertiggestellt per Webhook.

Details zu Vorlagen, Abschnitten und Pflichtangaben stehen im Leitfaden Vom Objekt zum Exposé.

Fehlerformat

Alle APIs antworten im Fehlerfall gleich:

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

Rate Limits

Jede Antwort trägt RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset. Bei 429 wartet ein gut gebauter Client die in Retry-After genannten Sekunden ab, statt sofort erneut anzufragen.