Brancheneinstufung2/connector-superoffice

SuperOffice Connector ("The Butler") - GTM Engine

Dies ist der Microservice zur Anbindung von SuperOffice CRM an die GTM-Engine. Der Connector agiert als "Butler": Er bereitet im Hintergrund hyper-personalisierte Marketing-Texte vor und legt sie im CRM ab, damit der Vertrieb sie mit minimalem Aufwand versenden kann.

1. Architektur: Das "Butler-Modell"

Wir haben uns gegen eine komplexe Automatisierung innerhalb von SuperOffice (via CRMScript-Trigger) entschieden, da die DEV-Umgebung limitiert ist und die Logik extern flexibler ist.

Der Datenfluss:

1. Master-Daten (Notion): Pains & Gains werden pro Vertical in Notion gepflegt.
2. Text-Matrix (Lokal): Das Skript build_matrix.py "multipliziert" die Vertical-Daten mit den Rollen-Daten, generiert via Gemini die finalen Texte und speichert sie in einer lokalen SQLite DB (marketing_matrix.db).
3. Polling & Injection (Daemon): Das Skript polling_daemon_final.py läuft periodisch, prüft auf Änderungen an Kontakten in SuperOffice und "injiziert" die passenden Texte aus der lokalen Matrix-DB in die UDF-Felder.

graph TD
    subgraph "A: Strategie & Content"
        NotionDB["🏢 Notion DB<br/>(Industries & Roles)"]
    end

    subgraph "B: Lokale Engine (Python)"
        MatrixBuilder["⚙️ build_matrix.py"]
        GeminiAPI["🧠 Gemini API"]
        MatrixDB[("💾 marketing_matrix.db")]
        PollingDaemon["🤖 polling_daemon_final.py"]
    end

    subgraph "C: CRM-System"
        SuperOfficeAPI["☁️ SuperOffice API"]
        Contact["👤 Contact / Person<br/>(mit UDFs)"]
    end

    NotionDB -->|1. Liest Pains/Gains| MatrixBuilder
    MatrixBuilder -->|2. Promptet| GeminiAPI
    GeminiAPI -->|3. Generiert Texte| MatrixBuilder
    MatrixBuilder -->|4. Speichert in DB| MatrixDB
    
    PollingDaemon -->|5. Prüft Änderungen| SuperOfficeAPI
    PollingDaemon -->|6. Holt passende Texte| MatrixDB
    PollingDaemon -->|7. Schreibt in UDFs| SuperOfficeAPI
    SuperOfficeAPI -->|8. Aktualisiert| Contact

2. Kern-Komponenten (Skripte)

• superoffice_client.py:

  • Das Herzstück. Eine Python-Klasse, die die gesamte Kommunikation mit der SuperOffice API kapselt (Auth, GET, PUT, Search).
  • Beherrscht Paginierung, um auch große Datensätze zu verarbeiten.

• build_matrix.py:

  • Der "Content Generator".
  • Liest Pains/Gains aus Notion.
  • Iteriert über definierte Verticals und Rollen.
  • Nutzt Gemini, um die spezifischen Textbausteine (Subject, Intro, SocialProof) zu erstellen.
  • Speichert das Ergebnis in der marketing_matrix.db.

• polling_daemon_final.py:

  • Der Automatisierungs-Motor.
  • Läuft in einer Schleife (z.B. alle 15 Minuten) nur zu Geschäftszeiten (Mo-Fr, 7-18 Uhr).
  • Fragt SuperOffice nach kürzlich geänderten Kontakten.
  • Nutzt ein Hash-System, um zu prüfen, ob sich eine relevante Eigenschaft (Vertical oder Rolle) geändert hat, um unnötige API-Schreibvorgänge zu vermeiden.
  • Wenn eine Änderung erkannt wird, stößt er den Update-Prozess an.

• normalize_persona.py:

  • Ein Hilfs-Skript (Classifier), um Jobtitel auf unsere 4 Archetypen (Operativ, Infrastruktur, Wirtschaftlich, Innovation) zu mappen.

3. Setup & Konfiguration

Installation

# In einer Python 3.11+ Umgebung:
pip install -r requirements.txt

Konfiguration (.env)

Der Connector benötigt eine .env Datei im Root-Verzeichnis mit folgendem Inhalt:

# Gemini API Keys (DEV für Tests, PROD für Live-Tools)
GEMINI_API_KEY_DEV="AIza..."
GEMINI_API_KEY_PROD="AIza..."
GEMINI_API_KEY=${GEMINI_API_KEY_DEV} # Setzt den Default

# Notion
NOTION_API_KEY="secret_..."

# SuperOffice Client Configuration
SO_CLIENT_ID="<Client ID / App ID>"
SO_CLIENT_SECRET="<Client Secret>"
SO_CONTEXT_IDENTIFIER="CustXXXXX"
SO_REFRESH_TOKEN="<Refresh Token>"
SO_ENVIRONMENT="sod" # oder "online" für Produktion

4. SuperOffice Konfiguration (Admin)

Folgende Benutzerdefinierte Felder (UDFs) müssen angelegt sein. Die ProgIds sind umgebungs-spezifisch und müssen pro System (DEV/PROD) geprüft werden.

Objekt	Feldname (Label)	Typ	ProgId (DEV)	ProgId (PROD)
Firma	Contact Vertical	Liste	SuperOffice:5	tbd
Firma	AI Challenge Satz	Text	SuperOffice:6	tbd
Person	Person Role	Liste	SuperOffice:3	tbd
Person	Marketing Subject	Text	SuperOffice:5	tbd
Person	Marketing Intro	Text	SuperOffice:6	tbd
Person	Marketing Proof	Text	SuperOffice:7	tbd
Person	AI Copy Hash	Text	SuperOffice:8	tbd

B. Listen-Werte & IDs (DEV Environment)

Folgende IDs werden in den Skripten als Referenz genutzt. Diese müssen für PROD neu validiert werden.

MA Status (x_ma_status):

• Init
• Ready_to_Craft
• Ready_to_Send
• Sent_Week1
• ...

Rollen (x_person_role / SuperOffice:3):

ID	Name
19	Operativer Entscheider
20	Infrastruktur-Verantwortlicher
21	Wirtschaftlicher Entscheider
22	Innovations-Treiber

Verticals (x_contact_vertical / SuperOffice:5):

ID	Name
23	Logistics - Warehouse
24	Healthcare - Hospital
25	Infrastructure - Transport
26	Leisure - Indoor Active
...	tbd

5. "Gotchas" & Lessons Learned (POC)

• API-URL: Der sod Tenant Cust55774 ist nur über https://app-sod.superoffice.com erreichbar, nicht sod.superoffice.com.
• Listen-IDs: Die API gibt IDs von Listenfeldern im Format [I:26] zurück. Der String muss vor der DB-Abfrage auf den Integer 26 geparst werden.
• Dev-System Limits: Die Textfelder im DEV-System sind auf 40 Zeichen limitiert. Die generierten Texte müssen vor dem Senden gekürzt werden.
• Y-Tabellen: Der direkte API-Zugriff auf Zusatz-Tabellen ist in diesem Mandanten blockiert (403 Forbidden). Daher der Workaround mit UDFs.
• CRMScript Trigger: Die Erstellung von Triggern ist im DEV-System nicht möglich. Daher die Umstellung auf den externen Polling-Daemon.