URBANETAURBANETA
URBANETAURBANETA

Sprache

Design

Developer Docs

REST-API-Dokumentation

Erstellen Sie Integrationen mit Urbaneta. Automatisieren Sie die Rechnungsstellung, synchronisieren Sie Bewohner, lesen Sie Zählerdaten und mehr.

API-Schlüssel

Generieren Sie API-Schlüssel in Ihren Kontoeinstellungen. Jeder Schlüssel ist Ihrer Organisation zugeordnet.

Bearer-Authentifizierung

Alle Endpunkte erfordern einen gültigen Bearer-Token. Token laufen nach 15 Minuten ab — verwenden Sie Refresh-Token für automatische Erneuerung.

Webhooks

Abonnieren Sie Ereignisse (invoice.created, payment.received, reading.submitted) mit HMAC-signierten Payloads.

Basis-URL
https://testlnp.workizon.com/api

Alle Anfragen müssen über HTTPS erfolgen. Ersetzen Sie durch Ihre eigene Server-URL, falls zutreffend.

Authentifizierung

Fügen Sie Ihren Zugriffstoken in jedem Request in den Authorization-Header ein.

# Token sind kurzlebig. Verwenden Sie POST /auth/refresh mit Ihrem Refresh-Token, um automatisch einen neuen Zugriffstoken zu erhalten. Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Schnellstart

Drei Schritte bis zur ersten API-Integration.

1. Authentifizieren und Token erhalten

curl -X POST https://testlnp.workizon.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"yourpassword"}'

# Response
{ "data": { "accessToken": "eyJ...", "refreshToken": "dGhp..." } }

2. Ihre Gebäude auflisten

curl https://testlnp.workizon.com/api/buildings \
  -H "Authorization: Bearer $ACCESS_TOKEN"

3. Rechnungen für ein Gebäude generieren

curl -X POST https://testlnp.workizon.com/api/invoices/generate-bulk \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"buildingId":"<uuid>","periodStart":"2025-01-01","periodEnd":"2025-01-31"}'

JavaScript / TypeScript Beispiel

Kein SDK nötig — die API nutzt Standard-REST. Ein Muster für das Abrufen von Rechnungen und das Erfassen einer Zahlung.

# Fetch unpaid invoices
curl "https://testlnp.workizon.com/api/invoices?buildingId=<uuid>&status=sent" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Mark invoice as paid
curl -X PATCH "https://testlnp.workizon.com/api/invoices/<invoice-id>" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"paid","paidDate":"2025-02-01"}'

Endpunkt-Referenz

Authentifizierung

POST/auth/loginMit E-Mail und Passwort anmelden, gibt Zugriffs- und Aktualisierungstoken zurück
POST/auth/refreshEinen abgelaufenen Zugriffstoken mit einem Aktualisierungstoken erneuern
POST/auth/logoutDie aktuelle Sitzung beenden
POST/auth/magic-linkEine Magic-Link-Anmelde-E-Mail anfordern

Gebäude

GET/buildingsAlle Gebäude des authentifizierten Mandanten auflisten
POST/buildingsEin neues Gebäude erstellen
GET/buildings/:idEin Gebäude anhand seiner ID abrufen
PATCH/buildings/:idGebäudeeinstellungen aktualisieren (Name, Adresse, Abrechnung usw.)
DELETE/buildings/:idEin Gebäude löschen (Passwortbestätigung erforderlich)

Wohnungen

GET/buildings/:id/apartmentsWohnungen in einem Gebäude auflisten
POST/buildings/:id/apartmentsEine Wohnung erstellen
PATCH/buildings/:id/apartments/:aptIdWohnungsdetails aktualisieren
DELETE/buildings/:id/apartments/:aptIdEine Wohnung löschen

Rechnungen

GET/invoicesRechnungen mit Filterung auflisten (Status, Gebäude, Datumsbereich)
GET/invoices/:idRechnungsdetails einschließlich Positionen abrufen
POST/invoices/generate-bulkRechnungen für ein Gebäude und einen Zeitraum generieren
PATCH/invoices/:idRechnungsstatus, Zahlungsdatum oder Referenz aktualisieren
POST/invoices/send-bulkRechnungen per E-Mail an Bewohner senden
GET/invoices/:id/pdfRechnung als PDF herunterladen

Zähler

GET/metersZählerdefinitionen für ein Gebäude auflisten
POST/metersEinen neuen Zähler erstellen
POST/meters/:id/readingsEinen Zählerstand übermitteln
POST/meters/ocrEinen Zählerstand aus einem Foto mit KI-OCR extrahieren

Bewohner & Nutzer

GET/residentsMit Ihren Gebäuden verknüpfte Bewohner auflisten
POST/invitationsEinen Benutzer zu einer Wohnung einladen
GET/invitationsAusstehende Einladungen auflisten
DELETE/invitations/:idEine Einladung stornieren

Zahlungen

POST/payments/banklinkEine Paysera / Maksekeskus Banklink-Zahlung einleiten
GET/paymentsErfasste Zahlungen des Mandanten auflisten
POST/bank-statements/importCSV/XML-Kontoauszug für automatischen Abgleich importieren

Webhooks

GET/webhooksKonfigurierte Webhook-Endpunkte auflisten
POST/webhooksEinen Webhook-Endpunkt erstellen (URL + Ereignistypen)
DELETE/webhooks/:idEinen Webhook-Endpunkt löschen

Webhook-Ereignistypen

Abonnieren Sie beliebige Kombinationen dieser Ereignisse beim Erstellen eines Webhook-Endpunkts.

invoice.createdEine neue Rechnung wurde generiert
invoice.sentRechnung wurde per E-Mail an den Bewohner gesendet
invoice.paidRechnung als bezahlt markiert (manuell oder per Banklink)
invoice.overdueRechnung nicht bis zum Fälligkeitsdatum bezahlt
payment.receivedEine Zahlung wurde einer Rechnung zugeordnet
reading.submittedEin Bewohner hat einen Zählerstand eingereicht
reading.confirmedManager hat einen Zählerstand bestätigt
maintenance.createdEine neue Wartungsanfrage wurde eingereicht
maintenance.updatedStatus der Wartungsanfrage geändert

Beispiel-Payload

POST https://your-server.com/webhook X-Urbaneta-Signature: sha256=... { "event": "invoice.paid", "timestamp": "2025-02-01T10:30:00Z", "tenantId": "550e8400-e29b-41d4-a716-...", "data": { "invoiceId": "...", "amount": 142.50 } }

HTTP-Fehlercodes

400Ungültige AnfrageUngültiger Anfrage-Body oder fehlende Pflichtfelder
401Nicht autorisiertFehlender oder abgelaufener Zugriffstoken
403VerbotenAuthentifiziert, aber unzureichende Berechtigungen
404Nicht gefundenRessource nicht gefunden oder für Ihren Mandanten nicht zugänglich
409KonfliktDoppelte Ressource (z.B. Wohnungsnummer bereits vorhanden)
422ValidierungsfehlerValidierung fehlgeschlagen — prüfen Sie das errors-Array in der Antwort
429Rate-LimitZu viele Anfragen — erneut versuchen nach dem Retry-After-Header-Wert
500ServerfehlerUnerwarteter Fehler — wenden Sie sich an den Support, wenn er anhält

Bereit zur Integration?

Melden Sie sich bei Ihrem Urbaneta-Konto an, um API-Schlüssel zu generieren und Webhooks zu konfigurieren.

Zum Dashboard