Files

Floke 938a81fd97 feat(connector-superoffice): implement OAuth 2.0 flow and S2S architecture

Completed POC for SuperOffice integration with the following key achievements:
- Switched from RSA/SOAP to OAuth 2.0 (Refresh Token Flow) for better compatibility with SOD environment.
- Implemented robust token refreshing and caching mechanism in .
- Solved 'Wrong Subdomain' issue by enforcing  for tenant .
- Created  for REST API interaction (Search, Create, Update UDFs).
- Added helper scripts: , , .
- Documented usage and configuration in .
- Updated  configuration requirements.

[2ff88f42]

2026-02-09 16:04:16 +00:00

3.0 KiB

Raw Blame History

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.
Datenabruf: Stammdaten (Contact ID 1) können gelesen werden.
Daten schreiben: Vorbereitet (Code ist fertig), erfordert jedoch noch das Anlegen der UDF-Felder im SuperOffice 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 (Main Script)

Führt einen Login durch und sucht nach einer Test-Firma.

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

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

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

3.0 KiB Raw Blame History