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

2.1. Mapping of CRM Concepts (SuperOffice vs. D365)

Um die Integration effizient zu gestalten, wurde eine strategische Entscheidung bezüglich der Abbildung von Kern-CRM-Konzepten getroffen:

D365 Konzept	SuperOffice Entität	Zweck & Begründung
Opportunity	Sale	Die Sale-Entität in SuperOffice ist das direkte Äquivalent zu einer Opportunity. Hier werden potenzielle Umsätze, Vertriebsphasen und Wahrscheinlichkeiten erfasst. Dies ist das primäre Zielobjekt, sobald eine konkrete Verkaufschance durch den Company Explorer identifiziert wird.
Campaign	Project	Für Marketing-Automatisierung und die Bündelung von Kontakten für Kampagnen dient die Project-Entität als idealer Container. Sie ermöglicht es, Kampagnen-Teilnehmer zu gruppieren, Aktivitäten zuzuordnen und den ROI durch Verknüpfung mit Sale-Objekten zu messen.

---

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