---
title: "Erste Schritte"
description: "In zehn Minuten vom Zugang zum ersten erzeugten Exposé."
url: "https://maklerportal.apim.eu/erste-schritte"
image: "https://maklerportal.apim.eu/_og/d/c_Ocean.takumi,title_Erste+Schritte,description_~SW4gemVobiBNaW51dGVuIHZvbSBadWdhbmcgenVtIGVyc3RlbiBlcnpldWd0ZW4gRXhwb3PDqS4,props_eyJ0aGVtZSI6eyJtb2RlIjoiZGFyayIsImNvbG9ycyI6eyJwcmltYXJ5IjoiI0Q0QTI0QyJ9fX0,p_Ii9lcnN0ZS1zY2hyaXR0ZSI,s_ucidk_4mhuFUHMqE.png"
---

## Erste Schritte

Vom Zugang über die erste Anwendung bis zum fertig generierten Exposé – dieser Leitfaden führt Sie durch den kompletten Einstieg.

## [1\. Zugang anfordern](#_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](#_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](#_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.

```text
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](#_4-erster-aufruf)

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

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

```json
{
  "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é](#_5-das-erste-exposé)

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

```bash
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é](https://maklerportal.apim.eu/leitfaeden/expose-workflow).

## [Fehlerformat](#fehlerformat)

Alle APIs antworten im Fehlerfall gleich:

```json
{
  "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" }
  ]
}
```

| HTTP | code                       | Bedeutung                                                  |
| :--- | :------------------------- | :--------------------------------------------------------- |
| 400  | validierung_fehlgeschlagen | Anfrage entspricht nicht dem Schema                        |
| 401  | nicht_authentifiziert      | Schlüssel fehlt, ist gesperrt oder ungültig                |
| 403  | scope_fehlt                | Dem Schlüssel fehlt der nötige Scope                       |
| 404  | nicht_gefunden             | Objekt, Exposé oder Termin existiert nicht                 |
| 409  | konflikt                   | Zustand passt nicht, z. B. Veröffentlichung eines Entwurfs |
| 422  | pflichtangabe_fehlt        | Fachliche Pflichtangabe fehlt                              |
| 429  | zu_viele_anfragen          | Rate Limit erreicht                                        |

## [Rate Limits](#rate-limits)

| Umgebung   | Anfragen pro Minute | Exposé-Generierungen pro Stunde |
| :--------- | :------------------ | :------------------------------ |
| Sandbox    | 60                  | 20                              |
| Produktion | 600                 | 200                             |

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.

## Bereit für die erste Anbindung?

Registrieren Sie sich, legen Sie eine Anwendung an und erzeugen Sie Ihr erstes Exposé in unter zehn Minuten.

[Zugang anfordern](https://maklerportal.apim.eu/erste-schritte)[API-Katalog ansehen](https://maklerportal.apim.eu/apis)