Brancheneinstufung2/connector-superoffice

SuperOffice Connector (POC)

Dies ist der Microservice zur Anbindung von SuperOffice CRM (SOD / Cloud) an die GTM-Engine. Der Connector nutzt die REST API (v1) und authentifiziert sich via OAuth 2.0 (Refresh Token Flow).

1. Status Quo (Februar 2026)

Der Proof of Concept (POC) ist erfolgreich abgeschlossen.

• Verbindung: Erfolgreich hergestellt (Cust55774).
• Authentifizierung: Funktioniert automatisch via Refresh Token (gehärtet via load_dotenv(override=True)).
• Daten schreiben (Erfolg):
  • Firmen (Contacts): Erfolgreich angelegt (inkl. Name, URL, OrgNr).
  • Personen (Persons): Erfolgreich angelegt und mit Firmen verknüpft (inkl. E-Mail).
  • Verkauf (Sale): Erfolgreich angelegt.
  • Projekt (Project): Erfolgreich angelegt und Person als Mitglied hinzugefügt.
  • UDF-Felder: Erfolgreich aktualisiert für Contact und Person.
  • Sync to CE: Erfolgreiche Übertragung der Firmendaten an den Company Explorer.

2. Einrichtung & Installation

Voraussetzungen

• Python 3.11+
• Zugriff auf die .env Datei im Root-Verzeichnis (siehe unten).

Installation

cd connector-superoffice
../.venv/bin/pip install -r requirements.txt

Konfiguration (.env)

Die Authentifizierung erfordert folgende Variablen in der zentralen .env:

# SuperOffice Client Configuration
SO_SOD="<Client ID / App ID>"           # Aus dem Developer Portal
SO_CLIENT_SECRET="<Client Secret>"      # Aus dem Developer Portal
SO_CONTEXT_IDENTIFIER="CustXXXXX"       # Deine Tenant ID (z.B. Cust55774)

# Authentication Token
SO_REFRESH_TOKEN="<Dein langlebiger Refresh Token>"

# (Optional / Legacy S2S Configuration - aktuell nicht genutzt)
# SO_PRIVATE_KEY="..."
# SO_SYSTEM_USER_TOKEN="..."

# Company Explorer Configuration (Optional Override)
# CE_API_URL="http://company-explorer:8000"
# CE_API_USER="admin"
# CE_API_PASSWORD="gemini"

3. Nutzung

Verbindungstest & Demo

Führt einen Login durch, sucht nach einer Test-Firma und legt bei Bedarf einen Demo-Account mit Ansprechpartner an.

cd connector-superoffice
../.venv/bin/python main.py

Verfügbare Methoden (SuperOfficeClient)

• find_contact_by_criteria(...): Suche nach Name, URL oder OrgNr.
• create_contact(...): Erstellt eine neue Firma.
• create_person(...): Erstellt einen Ansprechpartner (verknüpft mit ContactId).
• create_sale(...): Erstellt einen Verkauf/Opportunity.
• create_project(...): Erstellt ein Projekt und fügt optional eine Person als Mitglied hinzu.
• update_entity_udfs(...): Aktualisiert UDFs für Kontakte und Personen.

Felder entdecken

Listet alle verfügbaren Felder (inkl. UDFs) auf, um die technischen Namen (ProgId) für das Mapping zu finden.

../.venv/bin/python discover_fields.py

4. Technische Details & "Gotchas"

Subdomain-Auflösung (app-sod)

Eine wichtige Erkenntnis des POCs war, dass die Standard-API-URL sod.superoffice.com nicht für alle Tenants funktioniert. Der AuthHandler wurde so angepasst, dass er (für diesen Tenant) https://app-sod.superoffice.com als Basis-URL erzwingt.

• Code-Stelle: auth_handler.py -> refresh_access_token

OAuth vs. System User

Ursprünglich war ein "Server-to-Server" (S2S) Flow mittels RSA-Zertifikaten geplant. Da der Zugriff auf den System-User-Token im SOD-Tenant Cust55774 aufgrund von UI-Änderungen und Berechtigungen erschwert war, wurde auf den OAuth 2.0 Refresh Token Flow ("Plan B") gewechselt.

• Vorteil: Einfacher einzurichten, Token ist "ewig" gültig (solange er genutzt wird).
• Nachteil: Muss einmalig manuell via Browser generiert werden (bereits erledigt).

5. Nächste Schritte

Detaillierter Plan: Marketing Automation (SuperOffice-zentrisch)

Der Versand von hyper-personalisierten E-Mails aus SuperOffice heraus ist ein zentrales Ziel. Das Vorgehen wird sich auf die Vorbereitung der E-Mails durch den Connector konzentrieren, während der Versand und die finale Kontrolle im SuperOffice-Client durch den Endbenutzer erfolgen.

Anwenderplan für die Marketing Automation (Ihre Beschreibung)

1. Wichtig: Versand aus SuperOffice heraus: Der Versand sollte aus SuperOffice heraus erfolgen (wir haben alle technischen Erforderungen ergriffen, um die E-Mail aus SuperOffice heraus in unserem Namen zu senden und vertrauenswürdig erscheinen zu lassen). Dies ist wichtig, um Transparenz zu haben (man sieht im System genau, was passiert ist).
2. Versand im NAMEN des angemeldeten CRM-Users: Der Versand erfolgt im NAMEN des angemeldeten CRM-Users / Account-Verantwortlichen. Ggf. muss er sogar manuell einen Knopf drücken, damit etwas passiert.
3. Statuswechsel bei Antwort: Der Statuswechsel bei Antwort kann ein manueller Prozess sein – wenn wir dies sinnvoll automatisieren können (bei eingehender Antwort automatisch Status auf "hat geantwortet" setzen wäre auch denkbar, wenn dies technisch möglich ist).
4. Crafting der E-Mail (Vorab-Generierung): Das "Crafting" der E-Mail ist für mich wichtiger als die reine Automation des im Wochenabstand Aussendens: Eine E-Mail besteht aus einem unternehmensspezifischen Satz, der gezielt die Herausforderungen des Unternehmens in Bezug auf Roboter als Herausforderung formuliert. Dieser Satz wird VORAB am Account gespeichert, nicht erst zur Laufzeit. Der zweite Teil der E-Mail besteht aus einer rollen- und branchenspezifischen "Antwort" auf die in Satz 1 formulierte Herausforderung, die als logische Schlussfolgerung den Einsatz unserer Roboter ins Feld führt. Im weiteren wird ein persönlicher Buchungslink zu einer Erstberatung des ABSENDERS ergänzt. (Dies ist unsere CTA, es gibt nichts anderes, was er klicken soll). Abgeschlossen wird die E-Mail durch einen Social Proof, der wiederum branchen- und rollenspezifische KPIs, die die Referenz durch Einsatz unserer Lösungen erreicht hat, aufführt. Die rollen- und branchenspezifischen Texte werden ebenfalls VORAB generiert. Sie liegen in einem eigenen Entitätstypen "marketingansprache". Der unternehmensspezifische Satz wird am Contact (Firma) gespeichert.
5. Zusammenführen im E-Mail-Template: Im E-Mail-Template werden dann alle Felder zusammengebracht. Da Satz 1 immer eine Herausforderung formuliert (egal welche dies ist) und Satz 2 immer eine Auflösung dieser Herausforderung formuliert, passt es am Ende so gut zusammen, dass niemand merkt, dass diese beiden Sätze nie voneinander wussten.
6. E-Mail-Signatur: Die E-Mail-Signatur (Name, Telefon, E-Mail) werden vom USER gezogen, der den Prozess anstößt.

Architekturentwurf: "Der Butler-Service"

Dieser Plan wird durch ein "Butler-Service"-Modell umgesetzt, bei dem der Connector die E-Mail-Inhalte intelligent vorbereitet und SuperOffice als Sendeplattform und "Single Source of Truth" für den Status dient.

Phase 1: Die Vorbereitung (Unser Connector, der Butler) Der Connector läuft im Hintergrund (z.B. alle Stunde) und führt folgende Aufgaben aus:

1. Identifiziere Kandidaten: Er fragt die SuperOffice API: "Gib mir alle Firmen (Contact), die für eine Ansprache vorgesehen sind (z.B. in einem bestimmten Project oder mit einem Status Ready_for_Crafting)."
2. Generiere Satz 1 (Unternehmens-spezifisch): Für jede Firma ruft der Connector die Company Explorer API auf und generiert den hyper-personalisierten "Herausforderungs-Satz".
3. Speichere Satz 1: Der Connector speichert diesen Satz in einem neuen, benutzerdefinierten Text-Feld (UDF) direkt an der Firma (Contact) in SuperOffice. Vorschlag: AI_Challenge_Sentence.
4. Hole Satz 2 & Social Proof (Rollen/Branchen-spezifisch): Der Connector weiß, welche Rolle und Branche der Ansprechpartner hat. Er greift auf die "marketingansprache"-Bibliothek zu (diese kann in einer einfachen Datenbank oder sogar einer JSON-Datei liegen, die der Connector verwaltet) und holt die passenden Textbausteine.
5. Stelle die E-Mail zusammen: Der Connector kombiniert nun alles:
   • Satz 1 (vom Contact-Feld)
   • Satz 2 (aus der Bibliothek)
   • Social Proof (aus der Bibliothek)
6. Speichere den E-Mail-Entwurf: Der komplette, fertige E-Mail-Text wird in einem zweiten, großen UDF-Textfeld gespeichert, diesmal aber an der Person, dem Ansprechpartner. Vorschlag: AI_Email_Draft.
7. Setze den Status: Der Connector aktualisiert den MA-Status der Person auf Ready_to_Send.

Phase 2: Die Ausführung (Der SuperOffice User) Der Vertriebsmitarbeiter hat eine extrem einfache Aufgabe:

1. Dashboard-Ansicht: Er öffnet in SuperOffice eine Selektion oder ein Projekt, das ihm alle Kontakte mit dem Status Ready_to_Send anzeigt.
2. Klick, Klick, Senden: Er öffnet den Kontakt. Im E-Mail-Editor von SuperOffice gibt es eine Vorlage. Diese Vorlage tut nichts anderes, als den Inhalt des Feldes AI_Email_Draft zu laden, den persönlichen Buchungslink des Mitarbeiters und seine Signatur hinzuzufügen.
3. Manuelle Kontrolle: Er kann den Text kurz überfliegen, wenn er möchte, und klickt auf "Senden".
4. Status-Update: Nach dem Senden ändert er den MA-Status manuell auf Sent_Week1.

Erforderliche UDFs für die Marketing Automation

Um diesen Plan umzusetzen, werden die folgenden UDFs in SuperOffice benötigt (Anlage durch den Admin):

1. Am Objekt Contact (Firma): Ein Textfeld. Vorschlag: AI_Challenge_Sentence
2. Am Objekt Person (Ansprechpartner): Ein großes Textfeld (Memo/Long Text). Vorschlag: AI_Email_Draft
3. Am Objekt Person (Ansprechpartner): Ein Listenfeld. Vorschlag: MA_Status mit den Werten Init, Ready_to_Craft, Ready_to_Send, Sent_Week1, Sent_Week2, Replied, Paused.

Wichtiger Blocker: Das Erstellen von E-Mail-Aktivitäten per API ist aktuell blockiert, da das E-Mail-Modul in der Zielumgebung (SOD) nicht aktiviert oder konfiguriert zu sein scheint. Dies führt zu einem 500 Internal Server Error bei API-Aufrufen. Die Implementierung dieser Funktionalität im Connector ist daher bis auf Weiteres ausgesetzt.