Brancheneinstufung2/SUPEROFFICE_INTEGRATION_PLAN.md

Technisches Konzept: SuperOffice CRM Integration

Dieses Dokument beschreibt die Integrationsstrategie zwischen SuperOffice CRM (führendes System für Stammdaten) und dem Company Explorer (KI-gestützte Anreicherungs-Engine).

Zielsetzung

Automatisierte Anreicherung von B2B-Firmendaten im CRM mit KI-generierten Insights (z.B. Robotik-Affinität, Branchen-Einstufung), ohne die Hoheit über die Stammdaten zu gefährden.

---

1. Architektur: Der "SuperOffice Connector"

Wir implementieren einen dedizierten Microservice (connector-superoffice), der als Brücke fungiert.

graph LR
    subgraph CRM ["SuperOffice CRM (Cloud/On-Prem)"]
        SO_DB[("Stammdaten<br/>(Contact)")]
        SO_UDF[("KI-Felder<br/>(UDFs)")]
    end

    subgraph Middleware ["Integration Layer (Docker)"]
        Connector["🔄 SuperOffice Connector<br/>(Python Service)"]
    end

    subgraph Intelligence ["GTM Engine"]
        CE_API["⚡ Company Explorer API"]
        CE_DB[("Enrichment DB")]
    end

    %% Data Flow
    SO_DB -->|"1. Pull (Delta/Initial)"| Connector
    Connector -->|"2. Push (Import)"| CE_API
    CE_API -.->|"3. Enrichment Process"| CE_DB
    CE_DB -->|"4. Result"| CE_API
    Connector -->|"5. Poll Results"| CE_API
    Connector -->|"6. Write-Back (Update UDFs)"| SO_UDF

    %% Styling
    style CRM fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style Middleware fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    style Intelligence fill:#fff3e0,stroke:#ef6c00,stroke-width:2px

2. Datenmodell & Erweiterung

Um die CRM-Daten sauber zu halten, schreiben wir niemals in Standardfelder (wie Name, Department), sondern ausschließlich in dedizierte, benutzerdefinierte Felder (User Defined Fields - UDFs).

Benötigte Felder in SuperOffice (Anforderung an IT/Admin)

Folgende Felder sollten am Objekt Company (bzw. Contact in SuperOffice-Terminologie) angelegt werden:

Feldname (Label)	Typ	Zweck
AI Robotics Potential	List/Select	High / Medium / Low / None
AI Industry	Text (Short)	KI-ermittelte Branche (z.B. "Logistik - Intralogistik")
AI Summary	Text (Long/Memo)	Kurze Zusammenfassung der Analyse
AI Last Update	Date	Zeitstempel der letzten Anreicherung
AI Status	List/Select	Pending / Enriched / Error

Benötigtes Feld im Company Explorer

Feldname	Typ	Zweck
external_crm_id	String/Int	Speichert die ContactId aus SuperOffice zur eindeutigen Zuordnung (Primary Key Mapping).

---

3. Phasenplan

Phase 1: Initial Load (Snapshot)

Ziel: Bestandskunden und aktive Leads einmalig bewerten.

1. Filter: Der Connector lädt alle Firmen mit Status "Kunde" oder "Prospect".
2. Import: Daten werden via POST /api/companies/bulk an den Explorer gesendet. Die ContactId wird mitgegeben.
3. Verarbeitung: Der Explorer arbeitet die Queue ab (Web-Scraping -> Klassifizierung).

Phase 2: Write-Back (Ergebnisse speichern)

Ziel: Ergebnisse im CRM sichtbar machen.

1. Der Connector prüft regelmäßig (GET /api/companies?status=ENRICHED) auf fertige Analysen.
2. Für jeden Treffer sendet er ein Update an die SuperOffice API (PUT /Contact/{id}).
3. Es werden nur die oben definierten UDFs aktualisiert.

Phase 3: Continuous Sync (Polling)

Ziel: Neue Firmen automatisch verarbeiten.

1. Zyklus: Alle 60 Minuten.
2. Logik: "Gib mir alle Firmen, die seit LAST_RUN erstellt oder geändert wurden."
3. Aktion: Neue Firmen werden automatisch zur Analyse geschickt.
4. Vorteil: Keine komplexe Firewall-Konfiguration für eingehende Webhooks nötig (Outbound-Only Traffic).

---

4. Sicherheit & Authentifizierung

• Authentifizierung: Nutzung eines System User Tokens (Machine-to-Machine). Dies verhindert, dass Passwörter von persönlichen Accounts im Code hinterlegt werden müssen.
• 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:

1. API Zugangsdaten: Client ID, Client Secret, Customer ID (Tenant) und einen System User Token.
2. UDF Definitionen: Die ProgId (technischen Namen) der neu angelegten Felder (z.B. userdef_id_123).