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:

Master-Daten (Notion): Pains & Gains werden pro Vertical in Notion gepflegt.
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).
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 (Update Feb 16, 2026)

API-URL: Der sod Tenant Cust55774 ist nur über https://app-sod.superoffice.com erreichbar.
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.
Write-Back (Stammfelder):
- UrlAddress & Phones: Das einfache Root-Feld UrlAddress ist beim PUT oft schreibgeschützt. Um die Website oder Telefonnummern zu setzen, muss die entsprechende Liste (Urls oder Phones) als Array von Objekten gesendet werden (z.B. {"Value": "...", "Description": "..."}).
- Mandatory Fields: Beim Update eines Contact Objekts müssen Pflichtfelder wie Name und Number2 (oder Number1) zwingend im Payload enthalten sein, sonst schlägt die Validierung serverseitig fehl.
- Full Object PUT: SuperOffice REST überschreibt das gesamte Objekt. Felder, die im PUT-Payload fehlen, werden im CRM geleert. Es empfiehlt sich, das Objekt erst per GET zu laden, die Änderungen vorzunehmen und dann das gesamte Objekt zurückzusenden.
Dev-System Limits: Die Textfelder im DEV-System sind auf 40 Zeichen limitiert.
Y-Tabellen & Trigger: Direkter Zugriff auf Zusatz-Tabellen und CRMScript-Trigger sind im SOD-DEV Mandanten blockiert.

6.6 KiB Raw Blame History