# KWP-API-Vertrag (Stand 2026-07-12 · Read-only-Entscheidung 2026-07-22) > **Auslöser:** KWP bekommt eine offizielle **API-Anbindung**. Die historische Planung > (M089–M095) war für **KWP OHNE API** gebaut: lokaler Windows-Client `kwpsync.exe` (NSSM-Dienst) > + MSSQL-Direktzugriff + lokale SQLite-Queue + MSSQL-Schema-Drift-Sentinel. > **Aktuelle Grundlage:** verifizierte Tenant-OpenAPI-/Staging-Proofs, AD-32, CR-003/CR-005 und die > Ticket-Docs `VR-P32*`/`VEXT-6`. > 🟢 **Initialer Produkt-Scope nach CR-003/AD-32 (2026-07-22):** HiveGrid nutzt KWP bis auf Weiteres > ausschließlich read-only. Der ausgelieferte Scope umfasst OAuth2/PKCE, die bestätigte 1:1-Mandantenbindung, > Connection-Health und spätere KWP→HiveGrid-Pulls. Keine KWP-Mutation wird registriert oder ausgeliefert. > M091, `kwp.push_auftrag`, M094-Outbound und M074-Outbound sind geparkt. `VEXT-6` hält den fehlenden > Write-/Project-Create-Vertrag nach; es blockiert den read-only Ausbau nicht. Read-only ist eine > HiveGrid-Produktgrenze und keine Behauptung über technisch mögliche BNWIN-Rechte. ## Maßgeblicher Vertrag für Geerkens KWP-Hosts sind **dynamisch**: Der Connector ermittelt den Relay-Host über `https://loadbalancer.kwp-online.de/Relay/GetAppUrl?linkId=` und hängt `/relay//pwa` an. Ein Host wie `app04` darf deshalb nicht dauerhaft in Code oder Tenant-Config festgeschrieben werden. Für `geerkens2` lieferte der Loadbalancer am 2026-07-12: | Vertragsmerkmal | Verifizierter Stand | |---|---| | Relay-Host | `https://geerkens2.app04.kwp-online.de` | | Tenant-OpenAPI | `/relay/geerkens2/pwa/swagger/v1/swagger.json` | | Vertrag | OAS 3.0.1 · 301 Pfade · 303 Operationen · 396 Schemas | | Snapshot-Proof | SHA-256 `5c504ffa955bc492fcc16ae01a92ad0491db29a904ad59058123fc3b24f26762` | | API-Metadaten | Title `KWP Api` · Version `v1` · Server `/relay/geerkens2/pwa` | Ergänzende Primärquelle ist die [offizielle KWP-API-Dokumentation](https://www.kwpsoftware.de/kwp-api-dokumentation/): Die API handelt im Namen eines bnWin-Benutzers; seine Rechte bestimmen Lese- und Schreibzugriff. Nutzt der Endkunde bnWin-Mandanten, muss jeder Request den Queryparameter `mandant=` erhalten. **Mandanten-Verbindungsflow, freigegeben 2026-07-21:** Die Tenant-OpenAPI enthält `GET /api/Mandant/Load`; der Endpoint beschreibt die für den angemeldeten Benutzer zulässigen Mandanten als `DtoMandant{id, kuerzel, bezeichnung}`. HiveGrid versucht diese Discovery direkt nach dem OAuth-Login. Ein Treffer wird vorausgewählt, muss aber vom Benutzer bestätigt werden; bei mehreren Treffern wird genau einer gewählt und bestätigt. Die OpenAPI-Security des Endpoints nennt allerdings andere KWP-interne Produkt-Scopes als die fünf für HiveGrid gelieferten `*-extern`-Scopes. Falls der externe Client die Liste nicht lesen darf, muss der Benutzer deshalb fail-closed entweder „kein bnWin-Mandant eingerichtet“ ausdrücklich bestätigen oder das exakte Kürzel manuell eingeben. Ein Fehler oder eine leere Liste ist keine implizite `none`-Bestätigung. Die Produktgrenze bleibt **1:1**: Ein HiveGrid-Tenant bindet genau ein KWP-Kundenkürzel plus genau eine bestätigte bnWin-Auswahl (`selected`) oder die bestätigte Abwesenheit eines bnWin-Mandanten (`none`). Ein fehlender Altwert ist `unconfirmed` und blockiert fachliche Calls. Der vorprovisionierte Geerkens-Pilot bleibt processweit auf `KWP_HIVEGRID_TENANT_ID` begrenzt. Die sichere Provisionierung mehrerer HiveGrid-Tenants oder weiterer KWP-Kundenclients ist Folge-Scope und wird nicht durch Entfernen dieses Gates vorgezogen. **OAuth-Runtime live geklärt (2026-07-22):** Die Freischaltungs-Mail nennt Keycloak unter `id.kwp-online.de/realms/kwp-federated`, die Tenant-OpenAPI dagegen Relay-lokale Endpunkte `/relay/geerkens2/pwa/connect/authorize` und `/connect/token`. Ein Authorization-Probe mit dem gelieferten externen Client, PKCE/S256 und allen fünf externen Scopes erreichte am Keycloak-Pfad für Produktions- und Staging-Redirect jeweils die Login-Seite (HTTP 200; weder `invalid_client` noch `invalid_redirect`). Damit sind Client und beide Redirects am Authorization-Endpunkt plausibilisiert. `client_credentials` ist wegen deaktiviertem Service-Account nicht erlaubt; der Device Authorization Grant ist ebenfalls für den Client deaktiviert. Gültig ist `openid` + fünf `*-extern`-Scopes + `offline_access`; `email` erzeugt für diesen Client `invalid_scope`. Somit bleibt ausschließlich Authorization Code + PKCE mit einem echten bnWin-Benutzer. Token-Austausch, geschützter read-only Resource-Call, bestätigte Mandantenbindung und neun automatische Refresh-Rotationen sind auf Staging belegt. `VN-1` bleibt nur für kontrollierte fachliche Testdaten offen. ## Architektur: von 3 auf 2 Komponenten **Vorher:** `HiveGrid Cloud ↔ kwpsync.exe (Windows, beim Kunden) ↔ KWP-MSSQL` **Nachher:** `HiveGrid Cloud ↔ HTTPS ↔ dynamisch aufgelöster KWP-Relay` Der „Kunde-vor-Ort"-Mittelteil entfällt. KWP wird damit ein **regulärer `oauth2`-Adapter** (statt `windows_client`-Sonderweg) und passt direkt ins generische Apps-Engine-Muster (`prisma/schema/appsEngine.prisma`: `App` / `DataConnection` / `AppSyncRun` / `AppSyncItem`). Egress (Cloud ruft KWP aktiv auf) statt Ingress (Client pollt Cloud). ## Überführung der historischen Milestones M089–M095 | Milestone | Vorher | Nachher (Re-Cut) | Verdict | |---|---|---|---| | **M089** Sync-Programm | externes `kwpsync.exe` (.NET/Go, NSSM, MSSQL, DPAPI, Auto-Update) | **KWP-API-Connector** (Host-Resolver + OAuth + userbezogener Kontext + bestätigte 1:1-`mandant`-Bindung über M33a) | **REPURPOSED** (Windows-Client entfällt) | | **M090** Heartbeat+Recovery | Client-Heartbeat 5min + 15-min-Watchdog + Auto-Restart | **KWP-API Connection-Health** (generischer M33a-Health-Probe) | **STARK VEREINFACHT** | | **M091** Warteschlange+Replay | zwei Queues (Cloud + lokale SQLite) | Zukünftige Cloud-Outbox nach belastbarem Write-Vertrag | **PARKED** hinter `VEXT-6` | | **M092** Schema-Drift-Sentinel | täglicher MSSQL-Schema-Snapshot+Hash-Diff | **API-Contract-Sentinel** (zod-Response-Validierung + OpenAPI-Fingerprint + `x-kwp-client-version`) | **VEREINFACHT** (ggf. in M089 integrierbar) | | **M093** Konflikt „KWP gewinnt" | Domain-Regel | Domain-Regel + HiveGrid-Snapshot/Audit; KWP-Änderungsfelder nur partiell | **UNVERÄNDERT**, technische Erkennung angepasst | | **M094** Plantafel-Sync | bidirektional via Client | initial nur KWP→HiveGrid per Cron-Pull; Outbound geparkt | **READ-ONLY RECUT** | | **M095** Dokumenten-Archiv-Sync | Client-Dateizugriff | Archiv-Metadaten via API, Dateiinhalt via Azure-Blob-Austausch → `@hivegrid/storage` | **VEREINFACHT** | **Netto:** M089 ändert sich grundlegend (Client → Connector), M090/M092/M094/M095 werden teils erheblich leichter, M093 bleibt als Schutz für eingehende KWP-Daten. M091 ist kein Vorläufer des read-only Ausbaus mehr. ## Datenmodell - **Aus Apps-Engine (`appsEngine.prisma`) nutzen:** `App{key:"kwp", connectionType:"oauth2"}`, `DataConnection{credentialsCiphertext:}`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem` (inkl. `rolledBackData` für M093-Restore). Plus `IdempotencyKey`/`FileObject` 1:1. Kundenkürzel und OAuth-Material liegen verschlüsselt in `DataConnection.credentialsCiphertext`; der dynamische Relay-Host wird nur gecacht. Die `mandantBinding` liegt ebenfalls ausschließlich im verschlüsselten Credential-Bundle und ist explizit `unconfirmed`, `none` oder `selected()`. Ein fehlendes Feld aus Alt-Credentials bedeutet `unconfirmed`, nicht `none`; dafür ist kein Prisma-Schema-Delta nötig. - **Neu im aktuellen Read-only-Scope in `prisma/schema/kwp.prisma`:** `KwpApiContractSnapshot` (API-Version + Schema-Fingerprint, ersetzt `KwpSchemaSnapshot`) und `KwpErrorReport`. - **PARKED, nicht im aktuellen Datenmodell:** `KwpProjectNumberSequence` und `KwpProjectNumberReservation` gehören ausschließlich zum Project-/Auftrag-Create. Sie dürfen erst nach belastbarem Providervertrag aus `VEXT-6` **und** erneuter ausdrücklicher Produktfreigabe angelegt werden. - **Credentials:** verschlüsselt in `DataConnection.credentialsCiphertext` via **Per-Tenant-DEK** (AD-8). Achtung: Spec 19.1.2 („KWP-Zugangsdaten verlassen das Kunden-Netz nie") gilt bei API-Anbindung nicht mehr 1:1 — API-Creds liegen jetzt (verschlüsselt) in der Cloud. DSGVO-konform, aber bewusst neu bewertet → in AVV/Subprozessoren (M166) vermerken. - **Pilot-Provisionierung:** Der bestehende Geerkens-OAuth-Client bleibt fail-closed an `KWP_HIVEGRID_TENANT_ID` gebunden. `KWP_MANDANT` wird für neue Connections nicht als processweite Mapping-Quelle verwendet. Ein späterer Mehr-Tenant-/Mehr-Kunden-Betrieb braucht einen eigenen sicheren Provisionierungsvertrag statt einer ersatzlosen Gate-Entfernung. ## Harte Vorbedingung **M008–M010 (M33a Apps-Engine-Adapter-Interface)** — das echte `connect/disconnect/validateConnection/syncPull/syncPush/handleWebhook`-Interface. `defineAdapter()` aus der Boilerplate ist nur eine 18-Zeilen-Status-Registry, **nicht** das Connector-Framework. KWP-API ist dann der **erste konkrete Adapter** dahinter. ## Vertragsstand der sieben Re-Cut-Fragen 1. **Auth:** OAuth2/Authorization Code + PKCE und Refresh/`offline_access` sind gesetzt; `App.connectionType='oauth2'`. Service-Account- und Device-Flow sind deaktiviert; der Request darf `openid` + fünf `*-extern`-Scopes + `offline_access`, aber nicht `email` enthalten. Userrechte sind bindend. Keycloak- versus Relay-`/connect/*`-Endpoint wird mit Token-Austausch und Resource-Call final entschieden. 2. **Endpoints/Capabilities:** Die externen Scopes erscheinen in der Tenant-Spec an folgenden Operationen: | Scope | Operationen | Fachliche Tags | |---|---:|---| | `adresse-extern` | 23 | `Adresse` | | `archiv-extern` | 15 | `ArchivExternal`, `VorgangInfo` | | `termin-extern` | 14 | `Termin`, `Monteursteuerung` | | `vorgang-extern` | 31 | `Projekt`, `Projektampel`, `VorgangAnzeige` | | `aktivitaet-extern` | 31 | `Aktivitaet`, `Aktivitaetenverwaltung`, Termin-Verknüpfungen | Die `*-extern`-Scopes fehlen allerdings in der Scope-Liste des OAuth-Flows und stehen in den Operation-Security-Arrays zusammen mit internen Scopes. Nach strikter OpenAPI-Semantik wäre das eine UND-Anforderung; praktisch sieht es nach alternativen KWP-Berechtigungen aus. Lese- und Schreibrechte sind deshalb pro Scope im Runtime-Probe zu beweisen. Der aktuelle HiveGrid-Scope führt unabhängig davon keine Schreiboperation aus. **Fachliche Lücke für einen späteren Writeback:** Es gibt keinen dokumentierten Endpoint zum Anlegen eines kaufmännischen Auftrags/Projekts. `/api/Projekt/Save` speichert laut Vertrag nur eine neue Bezeichnung für ein bereits bestehendes Projekt. Der Won→Auftrag-Use-Case benötigt eine KWP-Erweiterung oder ein bestätigtes Alternativ-Mapping. **Reale Vollinventur 2026-07-24 (CR-005):** Die 2.062.387-Byte-Tenant-OpenAPI enthält 554 Operationen. Wegen überlappender Security-Arrays ergeben die Scope-Zahlen zusammen nicht die eindeutige Anzahl: 113 Operationen liegen in mindestens einem der fünf HiveGrid-Scopes. Davon sind 77 semantisch lesend und 36 mutierend. Alle 113 erhalten einen expliziten Contract; nur die 77 Reads sind runtime-ausführbar. Die übrigen 441 Operationen gehören nicht zum lizenzierten HiveGrid-Umfang und werden nicht allowlisted. 3. **Webhooks:** In der vollständigen Tenant-OpenAPI gibt es weder Top-Level-`webhooks` noch Operation-`callbacks`. Das ist **Abwesenheit im Vertrag**, keine Bestätigung, dass KWP außerhalb davon keine Webhooks anbietet. M094 plant bis zur Herstellerantwort Cron-Pull. 4. **Rate-Limits:** KWP bestätigt ein Hard-Cap von 60 Requests/Minute pro Client. Read-only-Pulls müssen dieses Limit aggregiert einhalten. M091 bleibt bis zum Write-Vertrag geparkt und muss bei einer späteren Freigabe zusätzlich Backoff, Jitter und `429` konservativ behandeln. 5. **Versionierung:** OpenAPI/Info-Version `v1`; alle 303 Operationen führen optional `x-kwp-client-version`. Changelog- und Breaking-Change-Policy bleiben offen. M092 speichert deshalb OpenAPI-Hash plus beobachtete Serverversion und pausiert bei nicht validierbarer Drift. 6. **Dokumenten-API:** Listing, Suche, Details, Revisionen, Export und Import sind unter `/api/archiv-extern/*` vorhanden. Der Dateitransfer läuft gemäß offizieller KWP-Doku separat über Azure Blob: - `GetSetup.azureConnectionUri` höchstens **6 Stunden cachen**. - Upload in den Blob, danach `ImportDatei(containerId, dateiname)`. - Dateien im Austausch-Storage werden nach **24 Stunden automatisch gelöscht**. - Download: `ExportDatei(revisionId, guid)` → `exchangeFileUri` → JSON-Datei → eigentlicher Downloadlink. 7. **Konflikt-Felder:** Aktivitäten liefern `datumAenderung`/`userAenderung`; Archiv-Daten liefern `letzteAenderungAm`/`letzteAenderungVon` sowie `revisionId`/`revision`. Adresse, Termin und Projekt/Vorgang haben keine einheitlichen Versions-/Änderungsfelder. Es sind keine `ETag`-/`Last-Modified`- Response-Header oder `If-Match`-Preconditions dokumentiert. M093 verwendet daher KWP-Felder nur, wo vorhanden, und sonst HiveGrid-Snapshot + „KWP gewinnt" + Audit-Restore. ## Mandantenbindung als M089-Connector-Vertrag - OAuth-`tenant=` wählt die KWP-Installation; der Resource-Query `mandant=` wählt optional die Firma innerhalb dieser Installation. Die Werte dürfen nicht gleichgesetzt werden. - Nach dem Token-Austausch bleiben die Credentials bis zur ausdrücklichen Auswahl per-Tenant-DEK verschlüsselt in der reservierten `pending`-Connection. Erst eine bestätigte Bindung und ein geschützter Health-Probe dürfen die Connection aktivieren. - `selected` setzt den Queryparameter an jedem KWP-Resource-Request, `none` lässt ihn bewusst weg und `unconfirmed` blockiert fachliche Calls fail-closed. - Discovery über `Mandant/Load` ist bevorzugt, aber wegen des abweichenden Scope-Vertrags nicht garantiert; der manuelle Fallback ist deshalb Bestandteil des Connectors, kein Sync-Feature. - Der Slice enthält weiterhin keinen Pull, Push, manuellen Sync und keine automatische Anlage weiterer HiveGrid-Tenants. ## Noch extern zu bestätigen - für `VEXT-6`: belastbare Write-/Project-Create-Operationen, Scopes/BNWIN-Rechte, Payloads, Idempotenz-/Fehlervertrag und ein kontrollierbarer Testpfad; - kontrollierte fachliche Testdaten beziehungsweise ein sicherer Testpfad, obwohl KWP keine Sandbox und keinen Testkunden anbietet; - konkrete Pull-Intervalle innerhalb des bestätigten Hard-Caps von 60 Requests/Minute pro Client. ## Phase 2 (unverändert) Andere ERPs (Taifun/TopKontor/Streit) über dasselbe Adapter-Pattern. Streit hat ohnehin eine Cloud-API (analog zur KWP-API-Variante).