Sprache

Design

Blog/9 Min. Lesezeit

Urbaneta hat jetzt eine öffentliche API — das können Sie damit tun

Urbaneta Team

1 July 2026

Urbaneta hat jetzt eine öffentliche API — das können Sie damit tun

Urbaneta hat jetzt eine öffentliche API — das können Sie damit tun

Vor einigen Wochen hat mich ein Immobilienverwalter etwas gefragt, das mir im Gedächtnis geblieben ist. „Wir nutzen Urbaneta für unsere Gebäude, aber unsere Buchhaltungssoftware ist maßgeschneidert. Können wir die Rechnungsdaten automatisch abrufen, anstatt jeden Monat CSVs zu exportieren?“

Meine Antwort damals war „noch nicht“. Meine Antwort heute ist eine andere.

Urbaneta hat jetzt eine öffentliche API. Sie ist live, dokumentiert und bereit für Integrationen. Wenn Sie Entwickler sind, ein Immobilienverwaltungsunternehmen mit eigener IT oder einfach jemand, der aufhören möchte, Daten zwischen Systemen zu kopieren, ist das für Sie.

Was tatsächlich ausgeliefert wurde

Drei Dinge gingen zusammen live, und sie funktionieren als Set:

  1. API-Dokumentation — eine öffentliche Referenz unter /api-docs, die Ihnen genau sagt, welche Endpunkte existieren, was sie akzeptieren und was sie zurückgeben.
  2. API-Schlüssel — bereichsbezogene Tokens, die Sie in Ihrem Admin-Panel generieren, um Anfragen zu authentifizieren.
  3. Webhooks — Echtzeit-Benachrichtigungen, die Ereignisse an Ihren eigenen Server pushen, anstatt Sie zum Polling von Änderungen zu zwingen.

Lassen Sie uns jeden einzelnen durchgehen.

API-Dokumentation: die Landkarte

Das Erste, was Sie beim Aufbau gegen eine API brauchen, ist eine klare Dokumentation. Wir haben unsere unter /api-docs auf der Hauptdomain von Urbaneta platziert. Kein Login erforderlich — sie ist öffentlich.

Sie deckt ab:

  • Authentifizierung: Wie Sie Ihren API-Schlüssel in den Authorization: Bearer-Header einfügen.
  • Gebäude, Wohnungen und Bewohner: CRUD-Operationen für die Kernentitäten.
  • Rechnungen und Zählerstände: Die Daten, die Immobilienverwalter tatsächlich interessieren.
  • Webhook-Abonnement: Wie Sie Webhook-Endpunkte registrieren und verwalten.
  • Fehlercodes: Was 400, 401, 403 und 429 in der Praxis bedeuten, plus das Verhalten bei Ratenbegrenzung.

Die Dokumentation wird aus der tatsächlichen API-Quelle generiert, sodass sie nicht veraltet. Wenn sich ein Endpunkt ändert, wird die Dokumentation mit aktualisiert.

API-Schlüssel: bereichsbezogen, nicht allmächtig

Hier ist etwas, auf dem ich während des Designs bestanden habe: API-Schlüssel sollten bereichsbezogen sein. Sie sollten einer Drittanbieter-Integration keinen Schlüssel geben, der Gebäude löschen kann, nur weil sie Rechnungsdaten lesen müssen.

In Ihrem Admin-Panel unter Integrationen → API-Schlüssel können Sie Schlüssel mit spezifischen Berechtigungen erstellen:

  • read:buildings — Gebäude und Wohnungen auflisten
  • read:invoices — Rechnungsdaten abrufen
  • write:invoices — Rechnungen erstellen oder aktualisieren
  • read:residents — Zugriff auf das Bewohnerverzeichnis
  • webhooks:manage — Webhook-Endpunkte abonnieren und verwalten

Sie können mehrere Schlüssel für verschiedene Integrationen erstellen. Wenn ein Schlüssel eines Anbieters durchsickert, widerrufen Sie nur diesen einen. Kein Bedarf, alles zu rotieren.

Die Schlüssel haben das Präfix nmv_, damit sie in Logs und Code-Reviews leicht zu erkennen sind. Sie verwenden SHA-256-Hashing auf unserer Seite, sodass selbst eine Datenbankverletzung die tatsächlichen Tokens nicht offenlegt.

Webhooks: Hören Sie auf zu pollen, fangen Sie an zu reagieren

Das ist das, worauf ich persönlich am meisten gespannt bin. Polling ist verschwenderisch. Wenn Sie alle 5 Minuten prüfen, ob eine neue Rechnung erstellt wurde, machen Sie 288 Anfragen pro Tag für Daten, die sich vielleicht zweimal geändert haben.

Mit Webhooks pusht Urbaneta Ereignisse an Ihre URL, sobald sie passieren:

  • invoice.created
  • invoice.paid
  • resident.invited
  • maintenance_request.updated
  • meter_reading.submitted

Sie abonnieren die Ereignisse, die Sie interessieren, unter Integrationen → Webhooks. Urbaneta sendet eine POST-Anfrage an Ihren Endpunkt mit einer signierten Nutzlast. Sie verifizieren die Signatur, verarbeiten das Ereignis und sind fertig.

Wir integrieren einen Wiederholungsmechanismus: Wenn Ihr Endpunkt einen Nicht-2xx-Status zurückgibt oder eine Zeitüberschreitung auftritt, wiederholen wir mit exponentiellem Backoff für bis zu 24 Stunden. Die Zustellung erfolgt mindestens einmal, daher sollte Ihr Endpunkt idempotent sein. Wir fügen außerdem einen X-Urbaneta-Event-ID-Header hinzu, damit Sie bei Bedarf deduplizieren können.

Ein praktisches Beispiel

Angenommen, Sie führen ein Immobilienverwaltungsunternehmen mit einem Dutzend Gebäuden. Sie möchten:

  1. Alle in diesem Monat erstellten Rechnungen in Ihr Buchhaltungssystem ziehen.
  2. Eine Rechnung als bezahlt markieren, wenn die Banküberweisung eingeht.
  3. Ihr Wartungsteam benachrichtigen, wenn ein Bewohner ein Foto eines Zählerstands einreicht.

Vor der API waren dies manuelle CSV-Exporte, Tabellenabgleich und Telefonanrufe. Jetzt ist es:

  • Ein Cron-Job, der einmal täglich GET /api/v1/invoices?created_after=2026-07-01 aufruft.
  • Ein Webhook-Handler für invoice.paid, der Ihr Hauptbuch automatisch aktualisiert.
  • Ein Webhook-Handler für meter_reading.submitted, der in Ihren internen Slack-Kanal postet.

Die gesamte Integration könnte einen Entwickler ein oder zwei Tage kosten. Die Zeitersparnis beginnt sofort.

Was das für Immobilienverwalter bedeutet

Wenn Sie kein Entwickler sind, denken Sie vielleicht: „Das ist nett, aber ich schreibe keinen Code.“ Berechtigt. Hier ist, warum es trotzdem wichtig ist:

Ihre Anbieter können integrieren. Wenn Sie ein Buchhaltungstool, eine Wartungsplattform oder eine Bewohnerkommunikations-App nutzen, können Sie diese bitten, eine Urbaneta-Integration zu erstellen. Die API und Webhooks geben ihnen alles, was sie brauchen. Sie erhalten automatische Datensynchronisierung, ohne eine Zeile Code anzufassen.

White-Label-Portale bleiben unabhängig. API-Schlüssel sind pro Mandant bereichsbezogen. Wenn Sie ein White-Label-Immobilienverwaltungsportal unter Ihrer eigenen Domain betreiben, sehen Ihre API-Schlüssel nur Ihre Daten. Es gibt keine mandantenübergreifende Datenleckage.

Wie es weitergeht

Die aktuelle API deckt die Kernabläufe der Immobilienverwaltung ab: Gebäude, Bewohner, Rechnungen, Zählerstände, Wartung und Zahlungen. Wir erweitern sie basierend auf dem, was Integratoren tatsächlich anfragen.

Wenn Sie etwas bauen und einen Endpunkt benötigen, der noch nicht existiert, lassen Sie es uns wissen. Die API ist darauf ausgelegt zu wachsen — wir bevorzugen es, eine kleine, solide Oberfläche auszuliefern und sie zu erweitern, anstatt eine riesige Spezifikation zu bauen, die niemand nutzt.

Erste Schritte

  1. Öffnen Sie /api-docs in Ihrem Browser. Lesen Sie den Abschnitt zur Authentifizierung.
  2. Gehen Sie zu Ihrem Admin-Panel → Integrationen → API-Schlüssel und erstellen Sie einen Testschlüssel.
  3. Stellen Sie Ihre erste Anfrage: GET /api/v1/buildings mit Ihrem Schlüssel im Header.
  4. Wenn Sie Echtzeit-Ereignisse benötigen, gehen Sie zu Integrationen → Webhooks und registrieren Sie Ihren Endpunkt.

Die Dokumentation enthält kopierbare curl-Beispiele für jeden Endpunkt. Sie müssen die Nutzlaststruktur nicht erraten.

Vor einem Jahr sagte mir jemand, Immobilienverwaltungssoftware sollte „einfach funktionieren“ ohne Integrationen. Das habe ich früher geglaubt. Jetzt denke ich das Gegenteil: Die beste Immobilienverwaltungsplattform ist diejenige, die sich mit allem anderen verbindet, was Sie bereits nutzen.

Das ist es, was wir bauen.

Verwandte Artikel