Floke/Brancheneinstufung2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(superoffice): POC API handshake & auth flow [2ff88f42]

Browse Source 
Establishes the initial structure for the SuperOffice connector. Implements the complete, iterative authentication process, culminating in a successful refresh token exchange. Documents the process and the final blocker (API authorization) in the integration plan, awaiting IT action to change the application type to 'Server to server'.
This commit is contained in:
Floke
2026-02-06 13:52:44 +00:00
parent 0f9e651d95
commit 53b92c76de
10 changed files with 310 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
SUPEROFFICE_INTEGRATION_PLAN.md
View File

@@ -95,6 +95,31 @@ Folgende Felder sollten am Objekt `Company` (bzw. `Contact` in SuperOffice-Termi
* **Scope:** Der API-User benötigt Lesezugriff auf `Contact` und Schreibzugriff auf die `UDFs`.
* **Datenschutz:** Es werden nur Firmendaten (Name, Webseite, Stadt) übertragen. Personenbezogene Ansprechpartner bleiben im CRM und werden nicht an die KI gesendet.
### 4.1. POC Erkenntnisse & Manueller Setup-Prozess (Feb 2026)
Während des initialen Proof of Concepts (POC) wurde der Authentifizierungs-Flow für die SOD-Umgebung (SuperOffice Development) erfolgreich etabliert. Dabei wurden folgende wichtige Erkenntnisse gewonnen:
**Problemstellung:** Ein direkter "Client Credentials Flow" (rein maschinell) ist mit dem Anwendungstyp "empty" nicht möglich. Stattdessen ist ein einmaliger, interaktiver Schritt notwendig, um einen langlebigen `refresh_token` zu generieren, der dann für die automatisierte Kommunikation genutzt werden kann.
**Durchgeführte Schritte zur Token-Generierung:**
1. **App-Konfiguration:** Im SuperOffice Developer Portal wurde für die Anwendung "Robo_GTM-Engine" die URL `http://localhost` als "Allowed redirect URL" hinzugefügt.
2. **Autorisierungs-URL:** Ein Benutzer hat die folgende, speziell konstruierte URL im Browser geöffnet, um den Autorisierungsprozess zu starten:
`https://sod.superoffice.com/login/common/oauth/authorize?client_id=[IHRE_CLIENT_ID]&redirect_uri=http%3A%2F%2Flocalhost&response_type=code`
3. **Manuelle Zustimmung:** Der Benutzer hat sich in SuperOffice eingeloggt und der Anwendung die angeforderten Berechtigungen erteilt.
4. **Code-Extraktion:** Nach der Zustimmung wurde der Browser auf eine `localhost`-URL umgeleitet. Obwohl die Seite nicht geladen wurde, enthielt die URL den notwendigen `authorization_code` (z.B. `http://localhost/?code=ABC-123...`).
5. **Token-Austausch:** Mit einem Skript wurde dieser einmalige `code` an den SuperOffice Token-Endpunkt gesendet. Im Gegenzug wurden ein kurzlebiger `access_token` und der entscheidende, langlebige `refresh_token` empfangen.
6. **Sichere Speicherung:** Der `refresh_token` wurde in der `.env`-Datei des Connectors als `SO_REFRESH_TOKEN` hinterlegt.
**Ergebnis & Aktueller Blocker:**
* **Erfolg:** Der Authentifizierungs-Handshake ist erfolgreich. Der Connector kann den `SO_REFRESH_TOKEN` nutzen, um jederzeit vollautomatisch neue, gültige `access_token` von SuperOffice zu erhalten.
* **Blocker:** Trotz gültigem `access_token` werden alle nachfolgenden API-Aufrufe (z.B. an `/api/v1/User/currentPrincipal`) von SuperOffice auf die Login-Seite umgeleitet (`HTTP 302 Found`). Dies ist ein klares Indiz dafür, dass der Token zwar gültig, aber nicht für den API-Zugriff **autorisiert** ist.
**Empfehlung für die IT:**
Die Ursache für die fehlende Autorisierung liegt sehr wahrscheinlich im Anwendungstyp "empty". Um eine echte Server-zu-Server-Integration zu ermöglichen, **muss der Anwendungstyp im SuperOffice Developer Portal auf "Server to server" geändert werden.** Dies wird voraussichtlich erfordern, dass die Schritte 2-6 erneut durchgeführt werden, um neue Tokens mit den korrekten Berechtigungen zu erhalten.
## 5. Vorbereitung für die IT
Um den Connector in Betrieb zu nehmen, benötigen wir: