feat: Add EspoCRM and Advoware integration for Beteiligte comparison

- Implemented `compare_beteiligte.py` script for comparing Beteiligte structures between EspoCRM and Advoware.
- Created `beteiligte_comparison_result.json` to store comparison results.
- Developed `EspoCRMAPI` service for handling API interactions with EspoCRM.
- Added comprehensive documentation for the EspoCRM API service.
- Included error handling and logging for API operations.
- Enhanced entity management with CRUD operations and search capabilities.

bitbylaw/ESPOCRM_INTEGRATION_NEXT_STEPS.md

@@ -0,0 +1,114 @@
+# EspoCRM Integration - Nächste Schritte
+
+## ✅ Bereits erstellt:
+
+### 1. EspoCRM Service (`services/espocrm.py`)
+- Vollständiger API-Client mit allen CRUD-Operationen
+- X-Api-Key Authentifizierung
+- Error Handling und Logging
+- Redis-Integration für Caching/Rate Limiting
+
+### 2. Compare Script (`scripts/compare_beteiligte.py`)
+- Liest Beteiligten-Daten aus EspoCRM und Advoware
+- Zeigt Struktur-Unterschiede
+- Hilft beim Entity-Mapping
+
+## 🔧 Setup
+
+1. **Umgebungsvariablen setzen**:
+   ```bash
+   cp .env.example .env
+   # Dann .env editieren und echte Keys eintragen
+   ```
+
+2. **EspoCRM API Key besorgen**:
+   - In EspoCRM Admin Panel: Administration → API Users
+   - Neuen API User erstellen oder bestehenden Key kopieren
+   - In `.env` als `ESPOCRM_MARVIN_API_KEY` eintragen
+
+## 🧪 Testing
+
+### Compare Script ausführen:
+```bash
+cd /opt/motia-app/bitbylaw
+source python_modules/bin/activate
+
+# Mit EspoCRM ID (sucht automatisch in Advoware nach Namen)
+python scripts/compare_beteiligte.py <espocrm_entity_id>
+
+# Mit beiden IDs
+python scripts/compare_beteiligte.py <espocrm_id> <advoware_id>
+```
+
+**Beispiel**:
+```bash
+python scripts/compare_beteiligte.py 507f1f77bcf86cd799439011 12345
+```
+
+### Output zeigt:
+- Alle Felder aus EspoCRM
+- Alle Felder aus Advoware
+- Strukturunterschiede
+- Mapping-Vorschläge
+
+## 📋 Nächste Schritte
+
+### 1. Entity-Mapping definieren
+Basierend auf dem Compare-Output:
+- `bitbylaw/services/espocrm_mapper.py` erstellen
+- Mapping-Funktionen für Beteiligte ↔ Personen/Firmen
+- Feld-Transformationen
+
+### 2. Sync Event Step implementieren
+`bitbylaw/steps/vmh/beteiligte_sync_event_step.py`:
+- Events von Webhooks verarbeiten
+- EspoCRM API Client nutzen
+- Mapper für Transformation
+- In Advoware schreiben (via Proxy)
+- Redis Cleanup
+
+### 3. Testing & Integration
+- Unit Tests für Mapper
+- Integration Tests mit echten APIs
+- Error Handling testen
+- Rate Limiting verifizieren
+
+## 📚 Dokumentation
+
+- **Service**: `services/ESPOCRM_SERVICE.md`
+- **Script README**: `scripts/compare_beteiligte_README.md`
+- **API Docs**: `docs/API.md` (VMH Webhooks Sektion)
+- **Architektur**: `docs/ARCHITECTURE.md` (EspoCRM Integration)
+
+## 🔍 Tipps
+
+### EspoCRM Entity Types
+Häufige Entity-Types in EspoCRM:
+- `Contact` - Personen
+- `Account` - Firmen/Organisationen
+- `Lead` - Leads
+- `Opportunity` - Verkaufschancen
+- Custom Entities (z.B. `CVmhBeteiligte`, `CVmhErstgespraech`)
+
+### Advoware Mapping
+- Person → `personen` Endpoint
+- Firma → `firmen` Endpoint
+- Beide sind "Beteiligte" in Advoware-Sprache
+
+### API Endpoints
+```bash
+# EspoCRM
+curl -X GET "https://crm.bitbylaw.com/api/v1/Contact/ID" \
+  -H "X-Api-Key: YOUR_KEY"
+
+# Advoware (via Proxy)
+curl -X GET "http://localhost:3000/advoware/personen/ID" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+## ❓ Support
+
+Bei Fragen siehe:
+- EspoCRM API Docs: https://docs.espocrm.com/development/api/
+- Advoware Integration: `docs/ADVOWARE_SERVICE.md`
+- Motia Framework: `docs/DEVELOPMENT.md`