# 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`