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).
• UDF-Felder: Vorbereitet im Code, erfordert finalen Abgleich der ProgId nach Anlage im Admin-Panel.

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="..."

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).
• update_udfs(...): (Vorbereitet) Aktualisiert KI-Felder.

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

1. Felder anlegen: In SuperOffice Admin -> Felder -> Firma die UDFs (AI Robotics Potential, AI Summary etc.) anlegen.
2. Mapping aktualisieren: Die technischen Namen (ProgId) in superoffice_client.py eintragen.
3. Schreib-Test: main.py ausführen, um Daten zurückzuschreiben.