Floke
53f8fad7f2
1. Analyse der Änderungen:
* superoffice_client.py: Implementierung der Methoden create_contact (Standardfelder) und create_person (inkl. Firmenverknüpfung).
* auth_handler.py: Härtung der Authentifizierung durch Priorisierung von SO_CLIENT_ID und Unterstützung für load_dotenv(override=True).
* main.py: Erweiterung des Test-Workflows für den vollständigen Lese- und Schreib-Durchstich (Erstellung von Demo-Firmen und Personen).
* README.md: Aktualisierung des Status Quo und der verfügbaren Client-Methoden.
84 lines
3.5 KiB
Markdown
84 lines
3.5 KiB
Markdown
# 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
|
|
```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 & Demo
|
|
Führt einen Login durch, sucht nach einer Test-Firma und legt bei Bedarf einen Demo-Account mit Ansprechpartner an.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```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.
|