Add 'syncedHash' field to CAIKnowledge and CAdvowareAkten entities; update API documentation and configuration timestamps
This commit is contained in:
@@ -1,10 +1,11 @@
|
||||
# REST API Endpunkte - EspoCRM Custom Entities
|
||||
|
||||
**Version:** 1.1
|
||||
**Version:** 1.2
|
||||
**Datum:** 11. März 2026
|
||||
**Base URL:** `https://your-crm.com/api/v1`
|
||||
|
||||
**Changelog:**
|
||||
- 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
|
||||
|
||||
@@ -386,6 +387,7 @@ GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=syncStatus&wh
|
||||
- `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
|
||||
@@ -404,6 +406,7 @@ GET /api/v1/CAdvowareAktenCDokumente
|
||||
"cDokumenteId": "dok-456",
|
||||
"hnr": "42",
|
||||
"syncStatus": "synced",
|
||||
"syncedHash": "a3f5c8b9e2d1...",
|
||||
"deleted": false
|
||||
},
|
||||
{
|
||||
@@ -412,6 +415,7 @@ GET /api/v1/CAdvowareAktenCDokumente
|
||||
"cDokumenteId": "dok-789",
|
||||
"hnr": "43",
|
||||
"syncStatus": "new",
|
||||
"syncedHash": null,
|
||||
"deleted": false
|
||||
}
|
||||
]
|
||||
@@ -438,7 +442,8 @@ GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=c
|
||||
"cAdvowareAktenId": "akte-123",
|
||||
"cDokumenteId": "dok-456",
|
||||
"hnr": "42",
|
||||
"syncStatus": "synced"
|
||||
"syncStatus": "synced",
|
||||
"syncedHash": "a3f5c8b9e2d1..."
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -463,7 +468,8 @@ Content-Type: application/json
|
||||
"cAdvowareAktenId": "akte-123",
|
||||
"cDokumenteId": "dok-999",
|
||||
"hnr": "50",
|
||||
"syncStatus": "new"
|
||||
"syncStatus": "new",
|
||||
"syncedHash": null
|
||||
}
|
||||
```
|
||||
|
||||
@@ -481,6 +487,7 @@ Content-Type: application/json
|
||||
|
||||
{
|
||||
"syncStatus": "synced",
|
||||
"syncedHash": "a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4",
|
||||
"hnr": "51"
|
||||
}
|
||||
```
|
||||
@@ -502,6 +509,7 @@ DELETE /api/v1/CAdvowareAktenCDokumente/{id}
|
||||
- `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
|
||||
@@ -521,6 +529,7 @@ GET /api/v1/CAIKnowledgeCDokumente
|
||||
"aiDocumentId": "ai-doc-external-789",
|
||||
"syncstatus": "synced",
|
||||
"lastSync": "2026-03-11 19:00:00",
|
||||
"syncedHash": "b4e2a9c7f3d8...",
|
||||
"deleted": false
|
||||
}
|
||||
]
|
||||
@@ -551,7 +560,8 @@ Content-Type: application/json
|
||||
"cAIKnowledgeId": "kb-123",
|
||||
"cDokumenteId": "dok-999",
|
||||
"aiDocumentId": "ai-doc-new-123",
|
||||
"syncstatus": "new"
|
||||
"syncstatus": "new",
|
||||
"syncedHash": null
|
||||
}
|
||||
```
|
||||
|
||||
@@ -562,7 +572,8 @@ Content-Type: application/json
|
||||
|
||||
{
|
||||
"syncstatus": "synced",
|
||||
"lastSync": "2026-03-11T20:30:00+00:00"
|
||||
"lastSync": "2026-03-11T20:30:00+00:00",
|
||||
"syncedHash": "b4e2a9c7f3d8e1a5c6b7d8e9f0a1b2c3"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -693,7 +704,7 @@ 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" \
|
||||
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"
|
||||
```
|
||||
|
||||
@@ -708,7 +719,8 @@ curl -X POST "https://crm.example.com/api/v1/CAdvowareAktenCDokumente" \
|
||||
"cAdvowareAktenId": "akte-123",
|
||||
"cDokumenteId": "dok-789",
|
||||
"hnr": "42",
|
||||
"syncStatus": "new"
|
||||
"syncStatus": "new",
|
||||
"syncedHash": null
|
||||
}'
|
||||
```
|
||||
|
||||
@@ -724,7 +736,8 @@ curl -X PUT "https://crm.example.com/api/v1/CAdvowareAktenCDokumente/$JUNCTION_I
|
||||
-H "X-Api-Key: your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"syncStatus": "synced"
|
||||
"syncStatus": "synced",
|
||||
"syncedHash": "a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4"
|
||||
}'
|
||||
|
||||
# Schritt 3: Update global status (optional, Hooks machen das automatisch)
|
||||
@@ -752,7 +765,7 @@ curl -X GET "https://crm.example.com/api/v1/CAIKnowledgeCDokumente?where[0][type
|
||||
|
||||
```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" \
|
||||
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"
|
||||
```
|
||||
|
||||
@@ -780,6 +793,49 @@ curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
|
||||
|
||||
## 🎯 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
|
||||
@@ -868,6 +924,6 @@ WHERE name = 'Your Role Name';
|
||||
---
|
||||
|
||||
**Letzte Aktualisierung:** 11. März 2026
|
||||
**Version:** 1.1
|
||||
**Version:** 1.2
|
||||
|
||||
Für weitere Fragen: Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`
|
||||
|
||||
Reference in New Issue
Block a user