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 Ergebnisse & Finale Authentifizierungs-Strategie (Feb 2026)

Der Proof of Concept (POC) wurde erfolgreich abgeschlossen. Dabei wurde die Authentifizierungs-Strategie für maximale Stabilität und Einfachheit angepasst.

Ergebnis:

• Erfolg: Die Verbindung zum SOD-Tenant (Cust55774) steht. Der Connector kann Daten lesen und ist bereit zum Schreiben.
• Strategiewechsel: Statt des komplexen RSA-S2S-Flows wird der OAuth 2.0 Refresh Token Flow genutzt. Dies umgeht Lizenz- und UI-Einschränkungen in der SOD-Umgebung und bietet dieselbe Automatisierungsqualität für den Docker-Service.
• Subdomain-Handling: Es wurde festgestellt, dass SuperOffice Online (SOD) mandantenabhängige Subdomains nutzt. Für den Test-Tenant wurde https://app-sod.superoffice.com als valide API-Basis identifiziert.

Technische Umsetzung:

1. Einmalige Autorisierung: Ein langlebiger refresh_token wurde über einen manuellen Consent-Step generiert.
2. Automatisierung: Der AuthHandler tauscht diesen Token vollautomatisch gegen kurzlebige access_tokens (Bearer) aus.
3. Caching: Tokens werden lokal in token_cache.json gespeichert, um API-Limits zu schonen.

Aktueller Status & Nächste Schritte:

• Blocker gelöst: Die Authentifizierung und das URL-Routing sind stabil.
• Nächster Schritt: Manuelle Anlage der UDF-Felder (siehe Abschnitt 2) in der SuperOffice Administration durch den Admin. Erst danach kann der "Write-Back" (Phase 2) im Code final gemappt werden.

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).

6. Fragen an Manuel

1. Die "Lizenz-Gretchenfrage" (Development Tools) Frage: "Manuel, du sagtest, bei Wackler sind die 'Development Tools' aktiv. Weißt du, ob das eine globale Konzern-Lizenz ist oder ob wir für den RoboPlanet-Mandanten eine eigene Subskription brauchen? Mein Dev-Portal blockiert S2S aktuell mit dem Hinweis auf fehlende Lizenzen in Production." Ziel: Klären, ob es nur ein "Klick" im Admin-Panel ist oder ob Webkom (oder ein anderer Partner) eine neue Rechnung schreiben muss.

2. Der App-Registrierungs-Pfad Frage: "Hast du eure App als 'Custom Application' (privat für Wackler) oder als 'Standard Application' (über einen Partner-Account) registriert? Falls ihr einen Partner-Account nutzt: Könnten wir unsere GTM-Engine darüber mitlaufen lassen, um die Lizenz-Hürde zu umgehen?" Ziel: Prüfen, ob Manuel über ein Partner-Portal arbeitet. Partner-Apps brauchen manchmal keine Dev-Tools beim Kunden, weil der Partner die Validierung übernimmt.

3. Identifikation des "Gatekeepers" Frage: "Wer hat bei euch den Tenant technisch aufgesetzt? War das die Webkom? Ich muss herausfinden, wer die administrative Hoheit hat, um den 'System User' für S2S freizuschalten." Ziel: Den Namen des Ansprechpartners bei der Webkom oder intern bei Wackler-IT herausfinden.

4. Authentifizierungs-Deep-Dive (RSA vs. Token) Frage: "Nutzt ihr für eure S2S-App den RSA-Key-Flow (JWT) oder arbeitet ihr mit einem statischen System-User-Token? Ich bereite gerade den RSA-Handshake vor und wollte wissen, was in der SuperOffice Cloud stabiler läuft." Ziel: Fachsimpelei, um Manuel zu zeigen, dass du auf seinem Level spielst. Das öffnet Türen für Code-Sharing oder Tipps.

5. Das "Y-Tabellen" Problem Frage: "Nutzt ihr für eure Verkaufs-App auch Zusatztabellen (Y-Tabellen) oder schreibt ihr nur in Standardfelder? Ich plane eine Tabelle für dynamische Marketing-Texte (Rolle x Branche) – gab es bei euch Probleme mit dem Cache nach Strukturänderungen?" Ziel: Bestätigung einholen, dass Y-Tabellen mit ihrer Lizenz funktionieren. Das ist dein Beweis, dass du die Dev-Tools zwingend brauchst.

6. Authentifizierung beim S2S Call Wie authentifiziert ihr euch beim S2S-Call? Nutzt ihr den RSA-Flow mit Zertifikaten oder habt ihr einen Partner-Proxy dazwischen?" (Wenn er "Partner-Proxy" sagt, arbeitet er über Webkom-Infrastruktur).

7. Nutzung System User Wo habt ihr den 'System User' im CRM autorisiert?" (Er soll dir den Pfad in Einstellungen & Verwaltung zeigen).

8. Header API-Call Könntest du mir den Header eines eurer API-Calls zeigen (natürlich ohne den echten Token)?" (Daran sehen wir sofort, ob sie die v1 REST API oder die alte SOAP-Schnittstelle nutzen).