# REST API Endpunkte - EspoCRM Custom Entities

**Version:** 1.0  
**Datum:** 11. März 2026  
**Base URL:** `https://your-crm.com/api/v1`

---

## 🔐 Authentifizierung

Alle API-Requests benötigen einen API-Key im Header:

```bash
-H "X-Api-Key: your-api-key-here"
-H "Content-Type: application/json"
```

**API-Key erstellen:**
1. Admin → Users → [Your User] → API Users Tab
2. "Create API User" → Key kopieren

---

## 📋 Inhaltsverzeichnis

1. [CAdvowareAkten (Advoware Akten)](#cadvowareakten-advoware-akten)
2. [CAIKnowledge (AI Knowledge Base)](#caiknowledge-ai-knowledge-base)
3. [Junction Tables](#junction-tables)
   - [CAdvowareAktenCDokumente](#cadvowareaktencdokumente-junction)
   - [CAIKnowledgeCDokumente](#caiknowledgecdokumente-junction)
4. [CDokumente (Dokumente)](#cdokumente-dokumente)
5. [Filtering & Sorting](#filtering--sorting)
6. [Praktische Beispiele](#praktische-beispiele)

---

## CAdvowareAkten (Advoware Akten)

**Entity:** Verwaltung von Advoware-Akten mit Sync-Status-Tracking

### Standard CRUD Operationen

#### Liste aller Akten abrufen
```http
GET /api/v1/CAdvowareAkten
```

**Query Parameter:**
- `maxSize` - Max. Anzahl Ergebnisse (default: 20)
- `offset` - Offset für Pagination (default: 0)
- `select` - Komma-separierte Feldliste
- `orderBy` - Sortierfeld
- `order` - `asc` oder `desc`

**Response:**
```json
{
  "total": 150,
  "list": [
    {
      "id": "64e3f8a1b2c5d",
      "name": "Akte 2026-001",
      "aktenzeichen": "123/2026",
      "aktennummer": 123,
      "aktenpfad": "/advoware/2026/001",
      "syncStatus": "unclean",
      "lastSync": null,
      "createdAt": "2026-03-11 10:00:00",
      "modifiedAt": "2026-03-11 15:30:00"
    }
  ]
}
```

#### Einzelne Akte abrufen
```http
GET /api/v1/CAdvowareAkten/{id}
```

**Response:**
```json
{
  "id": "64e3f8a1b2c5d",
  "name": "Akte 2026-001",
  "aktenzeichen": "123/2026",
  "aktennummer": 123,
  "aktenpfad": "/advoware/2026/001",
  "syncStatus": "unclean",
  "lastSync": null,
  "vmhRumungsklageId": "64e3f8a1234ab",
  "vmhRumungsklageName": "Räumungsklage Muster",
  "assignedUserId": "user-id",
  "assignedUserName": "Max Mustermann"
}
```

#### Neue Akte erstellen
```http
POST /api/v1/CAdvowareAkten
Content-Type: application/json

{
  "name": "Akte 2026-002",
  "aktenzeichen": "124/2026",
  "aktennummer": 124,
  "aktenpfad": "/advoware/2026/002",
  "syncStatus": "unclean"
}
```

**Response:**
```json
{
  "id": "64e3f8a1b2c5e"
}
```

#### Akte aktualisieren
```http
PUT /api/v1/CAdvowareAkten/{id}
Content-Type: application/json

{
  "syncStatus": "synced",
  "lastSync": "2026-03-11T20:00:00+00:00"
}
```

**Response:**
```json
{
  "id": "64e3f8a1b2c5d"
}
```

#### Akte löschen
```http
DELETE /api/v1/CAdvowareAkten/{id}
```

**Response:**
```json
{
  "success": true
}
```

### Relationship-Endpunkte

#### Verknüpfte Dokumente abrufen
```http
GET /api/v1/CAdvowareAkten/{id}/dokumentes
```

**Response:**
```json
{
  "total": 5,
  "list": [
    {
      "id": "dok-123",
      "name": "Vertrag.pdf",
      "description": "Mietvertrag",
      "createdAt": "2026-03-10 09:00:00"
    }
  ]
}
```

**⚠️ WICHTIG:** Diese Endpoint gibt **KEINE** Junction-Spalten zurück (`hnr`, `syncstatus`, `lastSync`). Nutze dafür den [Junction API Endpoint](#cadvowareaktencdokumente-junction).

#### Dokument mit Akte verknüpfen
```http
POST /api/v1/CAdvowareAkten/{id}/dokumentes
Content-Type: application/json

{
  "id": "dokument-id-789"
}
```

**Hooks werden ausgelöst:**
- `DokumenteSyncStatus` - Setzt Junction `syncstatus = 'new'`
- `CheckGlobalSyncStatus` - Berechnet globalen `syncStatus`
- `PropagateDocumentsUp` - Verknüpft mit Räumungsklage/Mietinkasso

**Response:**
```json
{
  "success": true
}
```

#### Dokument von Akte entknüpfen
```http
DELETE /api/v1/CAdvowareAkten/{id}/dokumentes/{dokumentId}
```

**Hooks werden ausgelöst:**
- `PropagateDocumentsUp` - Entknüpft von Räumungsklage/Mietinkasso

#### Verknüpfte Räumungsklage
```http
GET /api/v1/CAdvowareAkten/{id}/vmhRumungsklage
```

#### Verknüpftes Mietinkasso
```http
GET /api/v1/CAdvowareAkten/{id}/mietinkasso
```

### Filterung & Suche

#### Nach syncStatus filtern
```http
GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean
```

#### Nach Aktenzeichen suchen
```http
GET /api/v1/CAdvowareAkten?where[0][type]=contains&where[0][attribute]=aktenzeichen&where[0][value]=2026
```

#### Mehrere Filter kombinieren
```http
GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean&where[1][type]=greaterThan&where[1][attribute]=createdAt&where[1][value]=2026-03-01
```

#### Nur bestimmte Felder
```http
GET /api/v1/CAdvowareAkten?select=name,aktenzeichen,syncStatus,lastSync
```

#### Mit Sortierung
```http
GET /api/v1/CAdvowareAkten?orderBy=createdAt&order=desc
```

---

## CAIKnowledge (AI Knowledge Base)

**Entity:** Verwaltung von AI Knowledge Base Entries mit Sync-Status

### Standard CRUD Operationen

#### Liste aller Knowledge Entries
```http
GET /api/v1/CAIKnowledge
```

**Response:**
```json
{
  "total": 50,
  "list": [
    {
      "id": "kb-123",
      "name": "Knowledge Base 2026-001",
      "datenbankId": "kb-external-123",
      "syncStatus": "synced",
      "lastSync": "2026-03-11 19:00:00",
      "createdAt": "2026-03-10 10:00:00"
    }
  ]
}
```

#### Einzelnen Entry abrufen
```http
GET /api/v1/CAIKnowledge/{id}
```

#### Neuen Entry erstellen
```http
POST /api/v1/CAIKnowledge
Content-Type: application/json

{
  "name": "Knowledge Base 2026-002",
  "datenbankId": "kb-external-456",
  "syncStatus": "unclean"
}
```

#### Entry aktualisieren
```http
PUT /api/v1/CAIKnowledge/{id}
Content-Type: application/json

{
  "syncStatus": "synced",
  "lastSync": "2026-03-11T20:00:00+00:00"
}
```

#### Entry löschen
```http
DELETE /api/v1/CAIKnowledge/{id}
```

### Relationship-Endpunkte

#### Verknüpfte Dokumente abrufen
```http
GET /api/v1/CAIKnowledge/{id}/dokumentes
```

**⚠️ WICHTIG:** Gibt **KEINE** Junction-Spalten zurück. Nutze [CAIKnowledgeCDokumente Junction API](#caiknowledgecdokumente-junction).

#### Dokument verknüpfen
```http
POST /api/v1/CAIKnowledge/{id}/dokumentes
Content-Type: application/json

{
  "id": "dokument-id-789"
}
```

**Hooks werden ausgelöst:**
- `DokumenteSyncStatus` - Setzt Junction `syncstatus = 'new'`
- `CheckGlobalSyncStatus` - Berechnet globalen `syncStatus`
- `PropagateDocumentsUp` - Verknüpft mit Räumungsklage/Mietinkasso

#### Dokument entknüpfen
```http
DELETE /api/v1/CAIKnowledge/{id}/dokumentes/{dokumentId}
```

### Filterung & Suche

#### Nach datenbankId suchen
```http
GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=datenbankId&where[0][value]=kb-123
```

#### Alle unclean Entries
```http
GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean
```

---

## Junction Tables

### CAdvowareAktenCDokumente (Junction)

**Entity:** Junction-Tabelle zwischen CAdvowareAkten und CDokumente mit additionalColumns

**Verfügbare Felder:**
- `cAdvowareAktenId` - ID der Akte
- `cDokumenteId` - ID des Dokuments
- `hnr` - Advoware HNR-Referenz (varchar, 255)
- `syncStatus` - Sync-Status (enum: new, changed, synced, deleted)
- `deleted` - Soft-Delete Flag

#### Alle Junction-Einträge
```http
GET /api/v1/CAdvowareAktenCDokumente
```

**Response:**
```json
{
  "total": 150,
  "list": [
    {
      "id": "1",
      "cAdvowareAktenId": "akte-123",
      "cDokumenteId": "dok-456",
      "hnr": "42",
      "syncStatus": "synced",
      "deleted": false
    },
    {
      "id": "2",
      "cAdvowareAktenId": "akte-123",
      "cDokumenteId": "dok-789",
      "hnr": "43",
      "syncStatus": "new",
      "deleted": false
    }
  ]
}
```

#### Einzelnen Junction-Eintrag abrufen
```http
GET /api/v1/CAdvowareAktenCDokumente/{id}
```

#### Alle Dokumente einer Akte mit Junction-Spalten
```http
GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123
```

**Response:**
```json
{
  "total": 5,
  "list": [
    {
      "id": "1",
      "cAdvowareAktenId": "akte-123",
      "cDokumenteId": "dok-456",
      "hnr": "42",
      "syncStatus": "synced"
    }
  ]
}
```

#### Nach HNR filtern
```http
GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=hnr&where[0][value]=42
```

#### Nach syncStatus filtern
```http
GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=changed
```

#### Neuen Junction-Eintrag erstellen (Dokument mit Akte + HNR verknüpfen)
```http
POST /api/v1/CAdvowareAktenCDokumente
Content-Type: application/json

{
  "cAdvowareAktenId": "akte-123",
  "cDokumenteId": "dok-999",
  "hnr": "50",
  "syncStatus": "new"
}
```

**Response:**
```json
{
  "id": "15"
}
```

#### Junction-Spalten aktualisieren
```http
PUT /api/v1/CAdvowareAktenCDokumente/{junctionId}
Content-Type: application/json

{
  "syncStatus": "synced",
  "hnr": "51"
}
```

#### Junction-Eintrag löschen
```http
DELETE /api/v1/CAdvowareAktenCDokumente/{id}
```

---

### CAIKnowledgeCDokumente (Junction)

**Entity:** Junction-Tabelle zwischen CAIKnowledge und CDokumente mit additionalColumns

**Verfügbare Felder:**
- `cAIKnowledgeId` - ID des AI Knowledge Entry
- `cDokumenteId` - ID des Dokuments
- `aiDocumentId` - Externe AI-Dokument-Referenz-ID (varchar, 255)
- `syncstatus` - Sync-Status (enum: new, unclean, synced, failed)
- `lastSync` - Zeitpunkt der letzten Synchronisation (datetime)
- `deleted` - Soft-Delete Flag

#### Alle Junction-Einträge
```http
GET /api/v1/CAIKnowledgeCDokumente
```

**Response:**
```json
{
  "total": 80,
  "list": [
    {
      "id": "1",
      "cAIKnowledgeId": "kb-123",
      "cDokumenteId": "dok-456",
      "aiDocumentId": "ai-doc-external-789",
      "syncstatus": "synced",
      "lastSync": "2026-03-11 19:00:00",
      "deleted": false
    }
  ]
}
```

#### Alle Dokumente eines Knowledge Entry mit Junction-Spalten
```http
GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=cAIKnowledgeId&where[0][value]=kb-123
```

#### Nach aiDocumentId suchen
```http
GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=aiDocumentId&where[0][value]=ai-doc-external-789
```

#### Nach syncstatus filtern
```http
GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=syncstatus&where[0][value]=unclean
```

#### Neuen Junction-Eintrag erstellen
```http
POST /api/v1/CAIKnowledgeCDokumente
Content-Type: application/json

{
  "cAIKnowledgeId": "kb-123",
  "cDokumenteId": "dok-999",
  "aiDocumentId": "ai-doc-new-123",
  "syncstatus": "new"
}
```

#### Junction-Spalten aktualisieren
```http
PUT /api/v1/CAIKnowledgeCDokumente/{junctionId}
Content-Type: application/json

{
  "syncstatus": "synced",
  "lastSync": "2026-03-11T20:30:00+00:00"
}
```

---

## CDokumente (Dokumente)

**Entity:** Dokumentenverwaltung

### Standard CRUD Operationen

#### Liste aller Dokumente
```http
GET /api/v1/CDokumente
```

#### Einzelnes Dokument abrufen
```http
GET /api/v1/CDokumente/{id}
```

#### Neues Dokument erstellen
```http
POST /api/v1/CDokumente
Content-Type: application/json

{
  "name": "Vertrag.pdf",
  "description": "Mietvertrag Mustermann"
}
```

#### Dokument aktualisieren
```http
PUT /api/v1/CDokumente/{id}
Content-Type: application/json

{
  "description": "Aktualisierte Beschreibung"
}
```

**⚠️ Hooks werden ausgelöst:**
- `UpdateJunctionSyncStatus` - Markiert alle Junction-Einträge als "unclean"

#### Dokument löschen
```http
DELETE /api/v1/CDokumente/{id}
```

### Relationship-Endpunkte

#### Verknüpfte AdvowareAkten
```http
GET /api/v1/CDokumente/{id}/advowareAktens
```

#### Verknüpfte AIKnowledge Entries
```http
GET /api/v1/CDokumente/{id}/aIKnowledges
```

---

## Filtering & Sorting

### Where-Clause Typen

#### equals (Exakte Übereinstimmung)
```http
GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean
```

#### contains (Text-Suche)
```http
GET /api/v1/CAdvowareAkten?where[0][type]=contains&where[0][attribute]=name&where[0][value]=2026
```

#### in (Liste von Werten)
```http
GET /api/v1/CAdvowareAkten?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=unclean
```

#### greaterThan / lessThan
```http
GET /api/v1/CAdvowareAkten?where[0][type]=greaterThan&where[0][attribute]=createdAt&where[0][value]=2026-03-01
```

#### isNull / isNotNull
```http
GET /api/v1/CAdvowareAkten?where[0][type]=isNull&where[0][attribute]=lastSync
```

### Sortierung

```http
GET /api/v1/CAdvowareAkten?orderBy=createdAt&order=desc
```

### Pagination

```http
GET /api/v1/CAdvowareAkten?maxSize=50&offset=100
```

### Feld-Selektion

```http
GET /api/v1/CAdvowareAkten?select=id,name,syncStatus,lastSync
```

---

## Praktische Beispiele

### Beispiel 1: Alle unsynchronisierten Akten mit Details

```bash
curl -X GET "https://crm.example.com/api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean&select=id,name,aktenzeichen,syncStatus&orderBy=createdAt&order=desc" \
  -H "X-Api-Key: your-api-key"
```

### Beispiel 2: Alle Dokumente einer Akte mit Junction-Spalten

```bash
# Schritt 1: Hole Akte
curl -X GET "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
  -H "X-Api-Key: your-api-key"

# Schritt 2: Hole Junction-Einträge mit HNR
curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123&select=cDokumenteId,hnr,syncStatus" \
  -H "X-Api-Key: your-api-key"
```

### Beispiel 3: Dokument mit Akte + HNR verknüpfen

```bash
# Via Junction API (empfohlen)
curl -X POST "https://crm.example.com/api/v1/CAdvowareAktenCDokumente" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "cAdvowareAktenId": "akte-123",
    "cDokumenteId": "dok-789",
    "hnr": "42",
    "syncStatus": "new"
  }'
```

### Beispiel 4: Sync-Status aktualisieren nach erfolgreicher Synchronisation

```bash
# Schritt 1: Finde Junction-Eintrag
JUNCTION_ID=$(curl -s -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123&where[1][type]=equals&where[1][attribute]=cDokumenteId&where[1][value]=dok-789&select=id" \
  -H "X-Api-Key: your-api-key" | jq -r '.list[0].id')

# Schritt 2: Update Junction-Status
curl -X PUT "https://crm.example.com/api/v1/CAdvowareAktenCDokumente/$JUNCTION_ID" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "syncStatus": "synced"
  }'

# Schritt 3: Update global status (optional, Hooks machen das automatisch)
curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "syncStatus": "synced",
    "lastSync": "2026-03-11T20:00:00+00:00"
  }'
```

### Beispiel 5: Suche AI-Dokument via externe ID

```bash
# Finde Junction-Eintrag via aiDocumentId
curl -X GET "https://crm.example.com/api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=aiDocumentId&where[0][value]=ai-doc-external-789" \
  -H "X-Api-Key: your-api-key"

# Response enthält cDokumenteId zum Abrufen des vollen Dokuments
```

### Beispiel 6: Alle neuen/geänderten Dokumente für Sync

```bash
# Finde alle Junction-Einträge die "new" oder "changed" sind
curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=changed&select=cAdvowareAktenId,cDokumenteId,hnr,syncStatus" \
  -H "X-Api-Key: your-api-key"
```

---

## 🎯 Wichtige Hinweise

### Junction-Spalten via REST API

**✅ RICHTIG:** Nutze Junction-Entity-APIs
```bash
GET /api/v1/CAdvowareAktenCDokumente
GET /api/v1/CAIKnowledgeCDokumente
```

**❌ FALSCH:** Standard Relationship-Endpoints geben additionalColumns NICHT zurück
```bash
GET /api/v1/CAdvowareAkten/{id}/dokumentes  # hnr/syncStatus NICHT in Response!
```

### Hooks & Automatische Updates

Folgende Operationen lösen automatisch Hooks aus:

**Dokument verknüpfen:**
```bash
POST /api/v1/CAdvowareAkten/{id}/dokumentes
```
- → `DokumenteSyncStatus`: Setzt Junction `syncstatus = 'new'`
- → `CheckGlobalSyncStatus`: Berechnet globalen Status
- → `PropagateDocumentsUp`: Verknüpft mit Räumungsklage/Mietinkasso

**Dokument ändern:**
```bash
PUT /api/v1/CDokumente/{id}
```
- → `UpdateJunctionSyncStatus`: Markiert alle Junction-Einträge als "unclean"

**Vor Entity speichern:**
```bash
PUT /api/v1/CAdvowareAkten/{id}
```
- → `CheckGlobalSyncStatus`: Berechnet globalen Status aus Junction-Einträgen

### ACL-Berechtigungen

Für Junction-Entities müssen Rollen explizit Zugriff haben:

```sql
-- Via Admin UI: Roles → [Your Role] → Add "CAdvowareAktenCDokumente"
-- Oder via SQL:
UPDATE role 
SET data = JSON_SET(data, '$.table.CAdvowareAktenCDokumente', 
  JSON_OBJECT('create','yes','read','all','edit','all','delete','all')
) 
WHERE name = 'Your Role Name';
```

---

**Letzte Aktualisierung:** 11. März 2026  
**Version:** 1.0

Für weitere Fragen: Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`