Erster API-Call

In dieser Kurzanleitung setzt du in wenigen Minuten deinen ersten erfolgreichen API-Request an die etg24-Plattform ab. Einzige Voraussetzung: ein gültiger API-Key.

1. API-Key erstellen

API-Keys erstellst du eigenständig in der etg24-App. Lege einen dedizierten Schlüssel für deine Integration oder deinen Agenten an und speichere ihn sicher – das Token wird aus Sicherheitsgründen nur ein einziges Mal im Klartext angezeigt. Alles zu Scopes und Akteur-Bindungen erfährst du unter Key-Lebenszyklus.

2. Erste Anfrage senden

Die Property Management v2 API wird über die Basis-URL https://api.etg24.de/propertymanagement/v2 bereitgestellt. Jeder Request authentifiziert sich über den HTTP-Header Authorization: Bearer <API_KEY>.

Der folgende cURL-Befehl ruft eine paginierte Liste der Kontakte in deinem Portal ab – eine reine, gefahrlose Leseoperation:

curl -s "https://api.etg24.de/propertymanagement/v2/query/contacts" \
  -H "Authorization: Bearer DEIN_API_KEY"

Als Antwort liefert die API ein JSON-Objekt mit Paginierungsmetadaten und dem Array der Kontakte:

{
  "pagination": { "total": 12, "limit": 50, "offset": 0 },
  "contacts": [
    {
      "id": "c1f7a28e-49b1-4f16-83b6-123456789abc",
      "firstName": "Erika",
      "lastName": "Mustermann",
      "email": "erika.mustermann@example.com"
    }
  ]
}

3. Die Struktur der API verstehen

Jeder Endpunkt folgt einem klaren Architekturmuster (CQRS): Operationen sind strikt getrennt in reine Leseoperationen (Queries) und zustandsändernde Schreiboperationen (Commands). Dies spiegelt sich unmittelbar im URL-Pfad wider:

GET  /propertymanagement/v2/query/contacts           Liste von Kontakten abrufen
GET  /propertymanagement/v2/query/contacts.show      Einzelnen Kontakt anhand der ID laden
POST /propertymanagement/v2/command/contacts.create  Neuen Kontakt anlegen

Dieses konsistente Schema gilt 1:1 auch für MCP-Tools: Queries sind idempotent und risikolos wiederholbar, während Commands gezielte, protokollierte Aktionen ausführen. Lies das CQRS-Konzept für Hintergründe zu Berechtigungen und Rollback.

4. Die interaktive Referenz nutzen

Die vollständige Spezifikation wird live aus den aktuellen OpenAPI-Definitionen generiert: siehe Property Management v2. Bereit für echte Implementierungen? Direkt lauffähige Vorlagen für Python und Node.js findest du in unserer Snippet-Sammlung.

Typische Fehlerquellen beim ersten Request

• 401 Unauthorized – Der API-Key fehlt, ist ungültig oder wurde deaktiviert. Prüfe das Format des Authorization-Headers (Bearer <KEY>) und den Status des Keys in den Portaleinstellungen.
• 400 Bad Request – Schreibende Command-Endpunkte erwarten einen validen JSON-Request-Body mit dem Header Content-Type: application/json.
• 403 Forbidden – Der API-Key verfügt nicht über die erforderlichen Berechtigungs-Scopes (z. B. wenn mit einem Read-only-Key ein Command aufgerufen wird).