# Verwalter365 API Übersicht Stand: vorbereitet für Web, iOS, Android und externe Verwaltungssysteme. ## Status Die API ist **teilweise implementiert** und **integrationsfähig vorbereitet**, aber noch nicht vollständig als öffentliche Partner-API produktionsreif. Bereits implementiert: - `GET /api/portal/snapshot` - `GET /api/cases` - `POST /api/cases` - Supabase-Datenmodell für Verwaltungstypen, Objekte, Einheiten, Ansprechpartner, Dienstleister, Vorgänge, Meldungen und Dokumente - Web/iOS/Android-Clients mit Mock-Fallback Noch vorzubereiten, bevor externe Verwaltungssysteme produktiv anbinden: - Authentifizierung für Partner-Systeme - Mandanten-/Objektberechtigungen - Push-Provider-Anbindung an APNS, FCM und Web Push - serverseitige Worker/Queues für Notification Delivery und Webhook Retry - CRUD-Endpunkte für Stammdaten - Audit-Logs und Idempotency Keys - Versionierte API-Dokumentation mit stabilen Fehlercodes ## Zielbild Verwalter365 soll zwei API-Flächen anbieten: - **Portal API** für Web, iOS und Android - **Partner API** für Verwaltungssysteme, ERP, DMS, Ticketing und Dienstleister-Systeme ## Basis-URL ```txt https://verwalter365.de/api ``` Für lokale Entwicklung: ```txt http://localhost:3000/api ``` ## Authentifizierung Aktueller Implementierungsstand: - Vercel Functions greifen serverseitig mit `SUPABASE_SERVICE_ROLE_KEY` auf Supabase zu. - Browser und Apps erhalten **niemals** den Supabase Service Role Key. Empfohlen für Partner-Systeme: ```http Authorization: Bearer X-Verwalter365-Tenant: ``` Für schreibende Partner-Endpunkte zusätzlich: ```http Idempotency-Key: ``` ## Implementierte Endpunkte ### Portal Snapshot ```http GET /api/portal/snapshot ``` Liefert die komplette Portal-Startansicht für eine Immobilie. Antwort: ```json { "property": { "id": "isarhof", "name": "Wohnanlage Isarhof", "address": "Musterstraße 18, 80331 München", "addressLines": [ "Musterstraße 18", "80331 München" ], "streetAddress": "Musterstraße 18", "postalCode": "80331", "city": "München", "countryCode": "DE", "unit": "Einheit 3. OG links", "imageURL": null }, "cases": [], "messages": [], "documents": [], "contacts": [], "serviceProviders": [] } ``` ### Vorgänge listen ```http GET /api/cases ``` Liefert alle Vorgänge, aktuell noch ohne Filterparameter. Geplante Filter: ```txt ?propertyId=isarhof&status=open&updatedSince=2026-05-01T00:00:00Z ``` ### Vorgang anlegen ```http POST /api/cases Content-Type: application/json ``` Body: ```json { "category": "Schadensmeldung", "subject": "Wasserschaden im Bad", "detail": "Beschreibung des Schadens" } ``` Antwort: ```json { "id": "A-123456", "title": "Wasserschaden im Bad", "category": "Schadensmeldung", "status": "open", "createdAt": "2026-05-09T10:00:00Z", "detail": "Beschreibung des Schadens", "assignedProviderID": null } ``` ## Empfohlene Partner-API-Endpunkte Diese Endpunkte sollten als nächstes implementiert werden, damit Verwaltungssysteme sich sauber verknüpfen können. ### Immobilien und Einheiten ```http GET /api/management-types GET /api/management-entities GET /api/properties GET /api/properties/{propertyId} GET /api/properties/{propertyId}/units PUT /api/properties/{propertyId} ``` Zweck: - Verwaltungstypen wie GdWE, MV, SEV und Gewerbeverwaltung abbilden - konkrete Verwaltungsidentitäten wie eine einzelne GdWE oder einen Mietverwaltungsbestand abbilden - Objektstammdaten synchronisieren - Einheiten aus Verwaltungssystemen übernehmen - Objektbilder und Adressen pflegen Hierarchie: ```txt Verwaltungstyp └── Verwaltungsidentität └── Objekt / Immobilie └── Einheit ``` Der Verwaltungstyp ist die Klassifikation. Die Verwaltungsidentität ist der fachliche Container, unter dem mehrere Objekte liegen können, z. B. `Isarhof`, `München Nord` oder `Campus Süd`. Für c/o-Adressen wird daraus zusammen mit dem Typ z. B. `c/o GdWE Isarhof`. Die Verwaltungsidentität hat eine c/o-Zustelladresse über die Verwalterfirma. Das Objekt selbst hat zusätzlich immer seine eigene Objektadresse. ```txt Verwalterfirma c/o Verwaltungstyp Name Straße Hausnummer der Verwalterfirma PLZ Ort der Verwalterfirma ``` Unterstützte Verwaltungstypen: | ID | Anzeige | Bedeutung | | --- | --- | --- | | `gdwe` | GdWE | Gemeinschaft der Wohnungseigentümer / WEG-Verwaltung | | `mv` | MV | Mietverwaltung | | `sev` | SEV | Sondereigentumsverwaltung | | `commercial` | Gewerbeverwaltung | Gewerbe- und gemischt genutzte Objekte | Beispiel Objekt: ```json { "id": "isarhof", "managementEntityId": "gdwe-isarhof", "name": "Wohnanlage Isarhof", "addressLines": [ "Musterstraße 18", "80331 München" ], "streetAddress": "Musterstraße 18", "postalCode": "80331", "city": "München", "countryCode": "DE" } ``` Beispiel Einheit: ```json { "id": "isarhof-3og-links", "propertyId": "isarhof", "unitNumber": "3.OG-L", "label": "Einheit 3. OG links", "floor": "3. OG", "usageType": "residential" } ``` ### Eigentümer, Mieter und Mietverträge ```http GET /api/parties POST /api/parties GET /api/units/{unitId}/parties PUT /api/units/{unitId}/parties GET /api/leases POST /api/leases GET /api/leases/{leaseId}/documents POST /api/leases/{leaseId}/documents GET /api/owner-tenant-messages POST /api/owner-tenant-messages GET /api/utility-billing-periods POST /api/utility-billing-periods GET /api/utility-billing-periods/{periodId}/items POST /api/utility-billing-periods/{periodId}/items ``` Zweck: - Eigentümer, Mieter und Bewohner als eigene Personen/Firmen führen - Rollen je Einheit zeitlich abbilden, z. B. Eigentümer, Mieter, Bewohner - Mietverträge inklusive Dokumentverknüpfung hinterlegen - Mieter-Eigentümer-Kommunikation einheitenbezogen speichern - Nebenkostenabrechnungen pro Objekt, Einheit, Mietvertrag und Zeitraum vorbereiten ### Ansprechpartner und Dienstleister ```http GET /api/contacts POST /api/contacts PUT /api/contacts/{contactId} DELETE /api/contacts/{contactId} ``` Zweck: - Verwalter, Buchhaltung, technische Verwaltung pflegen - Dienstleisterlisten synchronisieren - Zuständigkeiten je Objekt abbilden ### Vorgänge ```http GET /api/cases POST /api/cases GET /api/cases/{caseId} PATCH /api/cases/{caseId} POST /api/cases/{caseId}/comments POST /api/cases/{caseId}/attachments ``` Zweck: - Schadensmeldungen und Anfragen übernehmen - Status aus Verwaltungssystemen zurückspielen - Dienstleister zuweisen - Kommunikation historisieren ### Meldungen ```http GET /api/messages POST /api/messages PATCH /api/messages/{messageId} DELETE /api/messages/{messageId} ``` Zweck: - Schwarzes Brett / Objektmeldungen pflegen - Push-/E-Mail-Kommunikation vorbereiten ### Dokumente ```http GET /api/documents POST /api/documents GET /api/documents/{documentId}/download-url DELETE /api/documents/{documentId} ``` Zweck: - Abrechnungen, Hausordnung, Protokolle und Bescheide bereitstellen - Download-Links zeitlich begrenzt signieren ### Webhooks ```http POST /api/webhooks GET /api/webhooks DELETE /api/webhooks/{webhookId} ``` Events: ```txt case.created case.updated case.comment.created case.attachment.created document.created message.created contact.updated property.updated ``` Zweck: - Verwaltungssysteme über Änderungen informieren - bidirektionale Synchronisation ermöglichen ### Benachrichtigungen und Geräte ```http POST /api/devices DELETE /api/devices/{deviceId} GET /api/notifications PATCH /api/notifications/{notificationId} ``` Vorbereitete Plattformen: | Plattform | Push Provider | | --- | --- | | iOS | APNS | | Android | FCM | | Webapp | Web Push | | Desktop | Web Push oder nativer Desktop-Provider | Die Migration enthält bereits: - `device_registrations` - `notifications` - `notification_deliveries` Damit können Apps Geräte registrieren, In-App-Benachrichtigungen anzeigen und serverseitige Push-Zustellung nachverfolgen. ### Änderungshistorie ```http GET /api/audit-logs ``` Die Migration enthält `audit_logs`, damit Änderungen an Vorgängen, Kontakten, Dokumenten und Stammdaten nachvollziehbar werden. ## Integration mit Verwaltungssystemen Typischer Ablauf: 1. Verwaltungssystem legt Immobilie und Einheiten an. 2. Verwalter365 importiert Kontakte, Dienstleister und Dokumente. 3. Bewohner erstellen Vorgänge über Web/iOS/Android. 4. Verwaltungssystem erhält `case.created` Webhook. 5. Verwaltungssystem aktualisiert Status und Dienstleister. 6. Verwalter365 informiert Bewohner über Statusänderungen. ## Fehlerformat Empfohlenes Standardformat: ```json { "error": "case_create_failed", "message": "Human readable error", "requestId": "req_123" } ``` ## Nächste technische Schritte 1. Partner-Token-Modell in Supabase ergänzen. 2. Endpunkte für Management Types, Properties, Units, Contacts, Messages und Documents implementieren. 3. Uploads über Supabase Storage vorbereiten. 4. Webhook-Tabelle und Signaturprüfung implementieren. 5. Push-Provider-Credentials für APNS, FCM und Web Push anbinden. 6. Notification Worker für `notification_deliveries` implementieren. 7. OpenAPI-Spezifikation in CI validieren. 8. API-Dokumentation im Web unter `/api-docs` bereitstellen.