1021 lines
26 KiB
Markdown
1021 lines
26 KiB
Markdown
# REST API Endpunkte - EspoCRM Custom Entities
|
|
|
|
**Version:** 1.3
|
|
**Datum:** 11. März 2026
|
|
**Base URL:** `https://your-crm.com/api/v1`
|
|
|
|
**Changelog:**
|
|
- v1.3 (11. März 2026): pending_sync Status zu globalem syncStatus hinzugefügt
|
|
- v1.2 (11. März 2026): syncedHash-Feld zu Junction-Tables hinzugefügt
|
|
- v1.1 (11. März 2026): Aktivierungsstatus-Feld hinzugefügt (new, active, paused, deactivated)
|
|
- v1.0 (11. März 2026): Initiale Version
|
|
|
|
---
|
|
|
|
## 🔐 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",
|
|
"aktivierungsstatus": "new",
|
|
"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",
|
|
"aktivierungsstatus": "new",
|
|
"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",
|
|
"aktivierungsstatus": "new",
|
|
"syncStatus": "unclean"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"id": "64e3f8a1b2c5e"
|
|
}
|
|
```
|
|
|
|
#### Akte aktualisieren
|
|
```http
|
|
PUT /api/v1/CAdvowareAkten/{id}
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"aktivierungsstatus": "active",
|
|
"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 aktivierungsstatus filtern
|
|
```http
|
|
GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=aktivierungsstatus&where[0][value]=new
|
|
```
|
|
|
|
**Verfügbare Werte:**
|
|
- `new` - Neu angelegt (Standard, blaue Badge)
|
|
- `active` - Aktiv synchronisiert (grüne Badge)
|
|
- `paused` - Synchronisation pausiert (gelbe Badge)
|
|
- `deactivated` - Synchronisation deaktiviert (rote Badge)
|
|
|
|
#### Nach syncStatus filtern
|
|
```http
|
|
GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean
|
|
```
|
|
|
|
**Verfügbare Werte:**
|
|
- `synced` - Alle Dokumente synchronisiert (grüne Badge)
|
|
- `unclean` - Mindestens ein Dokument neu oder geändert (gelbe Badge)
|
|
- `pending_sync` - Synchronisierung läuft (blaue Badge)
|
|
|
|
#### 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=id,name,aktivierungsstatus,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",
|
|
"aktivierungsstatus": "active",
|
|
"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",
|
|
"aktivierungsstatus": "new",
|
|
"syncStatus": "unclean"
|
|
}
|
|
```
|
|
|
|
#### Entry aktualisieren
|
|
```http
|
|
PUT /api/v1/CAIKnowledge/{id}
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"aktivierungsstatus": "active",
|
|
"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 aktivierungsstatus filtern
|
|
```http
|
|
GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=aktivierungsstatus&where[0][value]=active
|
|
```
|
|
|
|
**Verfügbare Werte:**
|
|
- `new` - Neu angelegt (Standard, blaue Badge)
|
|
- `active` - Aktiv synchronisiert (grüne Badge)
|
|
- `paused` - Synchronisation pausiert (gelbe Badge)
|
|
- `deactivated` - Synchronisation deaktiviert (rote Badge)
|
|
|
|
#### 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
|
|
```
|
|
|
|
**Verfügbare syncStatus Werte:**
|
|
- `synced` - Alle Dokumente synchronisiert (grüne Badge)
|
|
- `unclean` - Mindestens ein Dokument neu oder geändert (gelbe Badge)
|
|
- `pending_sync` - Synchronisierung läuft (blaue Badge)
|
|
|
|
---
|
|
|
|
## 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)
|
|
- `syncedHash` - Hash-Wert des synchronisierten Zustands (varchar, 64)
|
|
- `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",
|
|
"syncedHash": "a3f5c8b9e2d1...",
|
|
"deleted": false
|
|
},
|
|
{
|
|
"id": "2",
|
|
"cAdvowareAktenId": "akte-123",
|
|
"cDokumenteId": "dok-789",
|
|
"hnr": "43",
|
|
"syncStatus": "new",
|
|
"syncedHash": null,
|
|
"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",
|
|
"syncedHash": "a3f5c8b9e2d1..."
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### 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",
|
|
"syncedHash": null
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"id": "15"
|
|
}
|
|
```
|
|
|
|
#### Junction-Spalten aktualisieren
|
|
```http
|
|
PUT /api/v1/CAdvowareAktenCDokumente/{junctionId}
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"syncStatus": "synced",
|
|
"syncedHash": "a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4",
|
|
"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, unsupported)
|
|
- `lastSync` - Zeitpunkt der letzten Synchronisation (datetime)
|
|
- `syncedHash` - Hash-Wert des synchronisierten Zustands (varchar, 64)
|
|
- `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",
|
|
"syncedHash": "b4e2a9c7f3d8...",
|
|
"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",
|
|
"syncedHash": null
|
|
}
|
|
```
|
|
|
|
#### Junction-Spalten aktualisieren
|
|
```http
|
|
PUT /api/v1/CAIKnowledgeCDokumente/{junctionId}
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"syncstatus": "synced",
|
|
"lastSync": "2026-03-11T20:30:00+00:00",
|
|
"syncedHash": "b4e2a9c7f3d8e1a5c6b7d8e9f0a1b2c3"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 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,aktivierungsstatus,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,syncedHash" \
|
|
-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",
|
|
"syncedHash": null
|
|
}'
|
|
```
|
|
|
|
### 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",
|
|
"syncedHash": "a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4"
|
|
}'
|
|
|
|
# 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 '{
|
|
"aktivierungsstatus": "active",
|
|
"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,syncedHash" \
|
|
-H "X-Api-Key: your-api-key"
|
|
```
|
|
|
|
### Beispiel 7: Alle aktiven Akten abrufen
|
|
|
|
```bash
|
|
# Finde alle Akten die aktiv synchronisiert werden
|
|
curl -X GET "https://crm.example.com/api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=aktivierungsstatus&where[0][value]=active&select=id,name,aktenzeichen,aktivierungsstatus,syncStatus" \
|
|
-H "X-Api-Key: your-api-key"
|
|
```
|
|
|
|
### Beispiel 8: Akte von "new" auf "active" setzen
|
|
|
|
```bash
|
|
# Aktiviere eine neu angelegte Akte
|
|
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 '{
|
|
"aktivierungsstatus": "active"
|
|
}'
|
|
```
|
|
|
|
### Beispiel 9: Synchronisations-Workflow mit pending_sync
|
|
|
|
```bash
|
|
# Schritt 1: Hole alle Akten mit Status "unclean" die synchronisiert werden müssen
|
|
AKTEN=$(curl -s -X GET "https://crm.example.com/api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean&where[1][type]=equals&where[1][attribute]=aktivierungsstatus&where[1][value]=active" \
|
|
-H "X-Api-Key: your-api-key")
|
|
|
|
# Schritt 2: Setze Status auf "pending_sync" vor Synchronisation
|
|
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": "pending_sync"
|
|
}'
|
|
|
|
# Schritt 3: Führe Synchronisation durch...
|
|
# (Hole Junction-Einträge, synchronisiere mit Advoware, etc.)
|
|
|
|
# Schritt 4: Nach erfolgreicher Synchronisation
|
|
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"
|
|
}'
|
|
|
|
# Schritt 5: Bei Fehler während Synchronisation
|
|
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": "unclean"
|
|
}'
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 Wichtige Hinweise
|
|
|
|
### syncedHash - Änderungserkennung
|
|
|
|
**Zweck:** Hash-basierte Versionierung zur Erkennung von Dokumentänderungen zwischen Synchronisationen
|
|
|
|
**Verwendung:**
|
|
```bash
|
|
# 1. Nach erfolgreicher Synchronisation: Hash berechnen und speichern
|
|
curl -X PUT "https://crm.example.com/api/v1/CAdvowareAktenCDokumente/123" \
|
|
-H "X-Api-Key: your-api-key" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"syncStatus": "synced",
|
|
"syncedHash": "sha256:a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0"
|
|
}'
|
|
|
|
# 2. Bei nächster Synchronisation: Aktuellen Hash mit syncedHash vergleichen
|
|
# Wenn unterschiedlich → Dokument wurde geändert → syncStatus = "changed"
|
|
```
|
|
|
|
**Hash-Berechnung:**
|
|
```python
|
|
import hashlib
|
|
|
|
# Beispiel: Hash aus Dokument-Metadaten berechnen
|
|
def calculate_document_hash(document):
|
|
content = f"{document['name']}|{document['modifiedAt']}|{document['size']}"
|
|
return hashlib.sha256(content.encode()).hexdigest()
|
|
```
|
|
|
|
**Workflow:**
|
|
1. **Initial Sync:** syncedHash = NULL, syncStatus = "new"
|
|
2. **Sync durchgeführt:** syncedHash = berechnet, syncStatus = "synced"
|
|
3. **Dokument geändert:** Hook setzt syncStatus = "unclean"
|
|
4. **Nächster Sync:** Vergleiche aktuellen Hash mit syncedHash
|
|
- Gleich → Keine Änderung, skip
|
|
- Unterschiedlich → Sync durchführen, neuen Hash speichern
|
|
|
|
**Frontend-Anzeige:**
|
|
Das Feld wird automatisch in der Link-Multiple-Spalte "Dokumente" angezeigt:
|
|
- In CAdvowareAkten: Spalte "Sync-Hash" zeigt den Hash-Wert
|
|
- In CAIKnowledge: Spalte "Sync-Hash" zeigt den Hash-Wert
|
|
- Tooltip: "Hash-Wert des zuletzt synchronisierten Dokument-Zustands (zur Änderungserkennung)"
|
|
|
|
### Aktivierungsstatus
|
|
|
|
**Zweck:** Steuerung der Synchronisations-Aktivität für Akten und AI Knowledge Entries
|
|
|
|
**Verfügbare Status:**
|
|
- `new` (Standard) - Neu angelegte Einträge, noch nicht für Sync aktiviert
|
|
- `active` - Aktiv synchronisiert, alle Sync-Prozesse laufen
|
|
- `paused` - Synchronisation temporär pausiert, kann wieder aktiviert werden
|
|
- `deactivated` - Synchronisation dauerhaft deaktiviert
|
|
|
|
### Globaler syncStatus
|
|
|
|
**Zweck:** Übersicht über den Synchronisationszustand aller Dokumente einer Akte/eines AI Knowledge Entries
|
|
|
|
**Verfügbare Status:**
|
|
- `synced` (grün) - Alle Dokumente vollständig synchronisiert
|
|
- `unclean` (gelb) - Mindestens ein Dokument ist neu, geändert oder gelöscht
|
|
- `pending_sync` (blau) - Synchronisierung wurde gestartet aber noch nicht abgeschlossen
|
|
|
|
**Status-Übergänge:**
|
|
```
|
|
unclean → pending_sync (beim Start der Synchronisation)
|
|
pending_sync → synced (nach erfolgreicher Synchronisation aller Dokumente)
|
|
pending_sync → unclean (bei Fehler oder wenn ein Dokument während Sync geändert wurde)
|
|
synced → unclean (wenn ein Dokument geändert/hinzugefügt/gelöscht wird)
|
|
```
|
|
|
|
**Verwendung:**
|
|
```bash
|
|
# 1. Vor Synchronisation: Status auf pending_sync setzen
|
|
PUT /api/v1/CAdvowareAkten/{id} { "syncStatus": "pending_sync" }
|
|
|
|
# 2. Nach erfolgreicher Synchronisation: Status auf synced setzen
|
|
PUT /api/v1/CAdvowareAkten/{id} {
|
|
"syncStatus": "synced",
|
|
"lastSync": "2026-03-11T20:00:00+00:00"
|
|
}
|
|
|
|
# 3. Bei Fehler: Zurück auf unclean
|
|
PUT /api/v1/CAdvowareAkten/{id} { "syncStatus": "unclean" }
|
|
```
|
|
|
|
**Filterung:**
|
|
```bash
|
|
# Alle Akten die auf Synchronisation warten
|
|
GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean
|
|
|
|
# Alle Akten bei denen gerade eine Synchronisation läuft
|
|
GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=pending_sync
|
|
|
|
# Alle erfolgreich synchronisierten Akten
|
|
GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=synced
|
|
```
|
|
|
|
**Anwendungsfälle:**
|
|
```bash
|
|
# Neue Akte anlegen (automatisch status="new")
|
|
POST /api/v1/CAdvowareAkten { "name": "...", "aktivierungsstatus": "new" }
|
|
|
|
# Akte für Sync aktivieren
|
|
PUT /api/v1/CAdvowareAkten/{id} { "aktivierungsstatus": "active" }
|
|
|
|
# Sync temporär pausieren (z.B. während Wartung)
|
|
PUT /api/v1/CAdvowareAkten/{id} { "aktivierungsstatus": "paused" }
|
|
|
|
# Sync permanent deaktivieren
|
|
PUT /api/v1/CAdvowareAkten/{id} { "aktivierungsstatus": "deactivated" }
|
|
```
|
|
|
|
**Filterung:**
|
|
```bash
|
|
# Nur aktive Einträge für Sync-Job
|
|
GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=aktivierungsstatus&where[0][value]=active
|
|
|
|
# Alle pausierte oder deaktivierte
|
|
GET /api/v1/CAdvowareAkten?where[0][type]=in&where[0][attribute]=aktivierungsstatus&where[0][value][0]=paused&where[0][value][1]=deactivated
|
|
```
|
|
|
|
### 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.3
|
|
|
|
Für weitere Fragen: Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`
|