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]

connector-superoffice/README.md

@@ -0,0 +1,75 @@
+# 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
+```bash
+cd connector-superoffice
+../.venv/bin/pip install -r requirements.txt
+```
+
+### Konfiguration (.env)
+Die Authentifizierung erfordert folgende Variablen in der zentralen `.env`:
+
+```ini
+# 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.
+
+```bash
+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.
+
+```bash
+../.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.