# Integrationsleitfaden für Verwaltungssysteme

Dieser Leitfaden beschreibt, wie externe Verwaltungssysteme Verwalter365 anbinden sollen.

## Integrationsarten

### 1. Stammdaten-Sync

Das Verwaltungssystem ist führend für:

- Verwaltungstypen: GdWE, MV, SEV, Gewerbeverwaltung
- Verwaltungsidentitäten: z. B. einzelne GdWE, Mietverwaltungsbestände oder Gewerbeverwaltungen
- Immobilien
- Einheiten
- Eigentümer/Mieter-Zuordnung
- Mietverträge
- Mieter-Eigentümer-Kommunikation
- Nebenkostenabrechnungen
- Ansprechpartner
- Dienstleister
- Dokumente

Verwalter365 übernimmt diese Daten über Partner-Endpunkte.

Die Stammdaten-Hierarchie lautet:

```txt
Verwaltungstyp
└── Verwaltungsidentität
    └── Objekt
        └── Einheit
```

Der Verwaltungstyp beschreibt die Klasse der Verwaltung. Die Verwaltungsidentität ist die konkrete Gruppe, unter der Objekte geführt werden. Jedes Objekt gehört genau zu einer Verwaltungsidentität. Jede Einheit gehört genau zu einem Objekt.

Die Zustelladresse einer Verwaltungsidentität wird als c/o-Adresse über die Verwalterfirma geführt:

```txt
Verwalterfirma
c/o Verwaltungstyp Name
Straße Hausnummer der Verwalterfirma
PLZ Ort der Verwalterfirma
```

Objekte behalten davon unabhängig ihre eigene Objektadresse.

Objektadressen sind reine Standortadressen ohne Empfänger:

```txt
Straße Hausnummer
PLZ Ort
```

### 2. Vorgangs-Sync

Verwalter365 ist Eingangskanal für Bewohneranliegen.

Ablauf:

1. Bewohner erstellt Vorgang in Web/iOS/Android.
2. Verwalter365 speichert `service_case`.
3. Webhook `case.created` geht an Verwaltungssystem.
4. Verwaltungssystem übernimmt Vorgang und gibt externe ID zurück.
5. Statusupdates kommen per `PATCH /api/cases/{caseId}` zurück.
6. Bewohner sehen Status und Kommentare im Portal.

### 3. Dokumenten-Sync

Verwaltungssystem oder DMS übermittelt Dokument-Metadaten.

Dateien sollten nicht dauerhaft über Partner-APIs gestreamt werden. Empfohlen:

- Upload zu Supabase Storage oder S3-kompatiblem Storage
- API speichert Metadaten
- Download über kurzlebige signed URLs

Mietverträge und Nebenkostenabrechnungen werden als Dokument-Metadaten gespeichert und zusätzlich mit `lease_agreements` bzw. `utility_billing_items` verknüpft.

## Authentifizierung

Empfohlen:

- pro Partner-System ein API Token
- Token wird gehasht in Supabase gespeichert
- Mandant/Tenant wird über Token oder `X-Verwalter365-Tenant` bestimmt
- schreibende Requests benötigen `Idempotency-Key`

## Webhook-Signatur

Empfohlenes Header-Set:

```http
X-Verwalter365-Event: case.created
X-Verwalter365-Delivery: <uuid>
X-Verwalter365-Signature: sha256=<hmac>
```

Signatur:

```txt
hmac_sha256(webhook_secret, raw_request_body)
```

## Status-Mapping

Verwalter365:

```txt
open
inProgress
done
```

Supabase intern:

```txt
open
in_progress
done
```

Partner-Systeme sollten beim Import ein Mapping hinterlegen.

## Mindestanforderung für eine produktive Partner-API

- OpenAPI-Datei versioniert
- API Tokens mit Ablauf/Rotation
- RLS oder serverseitige Mandantenprüfung
- Audit Log für schreibende Requests
- Idempotency bei `POST`
- Webhook-Retry mit Backoff
- Rate Limits
- Push-Provider-Anbindung für APNS, FCM und Web Push
- Notification Outbox mit Zustellstatus
- Audit Log für Status- und Stammdatenänderungen
- stabile Fehlercodes
- Sandbox-Umgebung

## Aktueller Repository-Stand

Implementiert:

- Snapshot für Portal-Clients
- Vorgänge listen/anlegen
- Supabase Tabellen und Seed-Daten
- Migrationen für Geräte, Notifications, Notification Deliveries, Kommentare, Anhänge, Webhooks und Audit Logs

Geplant:

- Management Types
- Properties
- Units
- Contacts CRUD
- Documents CRUD + Storage
- Messages CRUD
- Case comments
- Case attachments
- Webhooks
- Partner tokens
- Push Worker für APNS, FCM und Web Push