bsiggel/espocrm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ae359048afd521475702774cafb5944f6aec4ab3
espocrm/custom/docs/API_ENDPOINTS.md

20 KiB
Raw Blame History

REST API Endpunkte - EspoCRM Custom Entities

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

Changelog:

  • 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:

-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)
  2. CAIKnowledge (AI Knowledge Base)
  3. Junction Tables
  4. CDokumente (Dokumente)
  5. Filtering & Sorting
  6. Praktische Beispiele

CAdvowareAkten (Advoware Akten)

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

Standard CRUD Operationen

Liste aller Akten abrufen

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:

{
  "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

GET /api/v1/CAdvowareAkten/{id}

Response:

{
  "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

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:

{
  "id": "64e3f8a1b2c5e"
}

Akte aktualisieren

PUT /api/v1/CAdvowareAkten/{id}
Content-Type: application/json

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

Response:

{
  "id": "64e3f8a1b2c5d"
}

Akte löschen

DELETE /api/v1/CAdvowareAkten/{id}

Response:

{
  "success": true
}

Relationship-Endpunkte

Verknüpfte Dokumente abrufen

GET /api/v1/CAdvowareAkten/{id}/dokumentes

Response:

{
  "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.

Dokument mit Akte verknüpfen

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:

{
  "success": true
}

Dokument von Akte entknüpfen

DELETE /api/v1/CAdvowareAkten/{id}/dokumentes/{dokumentId}

Hooks werden ausgelöst:

  • PropagateDocumentsUp - Entknüpft von Räumungsklage/Mietinkasso

Verknüpfte Räumungsklage

GET /api/v1/CAdvowareAkten/{id}/vmhRumungsklage

Verknüpftes Mietinkasso

GET /api/v1/CAdvowareAkten/{id}/mietinkasso

Filterung & Suche

Nach aktivierungsstatus filtern

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

GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean

Nach Aktenzeichen suchen

GET /api/v1/CAdvowareAkten?where[0][type]=contains&where[0][attribute]=aktenzeichen&where[0][value]=2026

Mehrere Filter kombinieren

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

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

Mit Sortierung

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

GET /api/v1/CAIKnowledge

Response:

{
  "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

GET /api/v1/CAIKnowledge/{id}

Neuen Entry erstellen

POST /api/v1/CAIKnowledge
Content-Type: application/json

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

Entry aktualisieren

PUT /api/v1/CAIKnowledge/{id}
Content-Type: application/json

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

Entry löschen

DELETE /api/v1/CAIKnowledge/{id}

Relationship-Endpunkte

Verknüpfte Dokumente abrufen

GET /api/v1/CAIKnowledge/{id}/dokumentes

⚠️ WICHTIG: Gibt KEINE Junction-Spalten zurück. Nutze CAIKnowledgeCDokumente Junction API.

Dokument verknüpfen

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

DELETE /api/v1/CAIKnowledge/{id}/dokumentes/{dokumentId}

Filterung & Suche

Nach aktivierungsstatus filtern

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

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

Alle unclean Entries

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

GET /api/v1/CAdvowareAktenCDokumente

Response:

{
  "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

GET /api/v1/CAdvowareAktenCDokumente/{id}

Alle Dokumente einer Akte mit Junction-Spalten

GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123

Response:

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

Nach HNR filtern

GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=hnr&where[0][value]=42

Nach syncStatus filtern

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)

POST /api/v1/CAdvowareAktenCDokumente
Content-Type: application/json

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

Response:

{
  "id": "15"
}

Junction-Spalten aktualisieren

PUT /api/v1/CAdvowareAktenCDokumente/{junctionId}
Content-Type: application/json

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

Junction-Eintrag löschen

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)
  • deleted - Soft-Delete Flag

Alle Junction-Einträge

GET /api/v1/CAIKnowledgeCDokumente

Response:

{
  "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

GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=cAIKnowledgeId&where[0][value]=kb-123

Nach aiDocumentId suchen

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

Nach syncstatus filtern

GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=syncstatus&where[0][value]=unclean

Neuen Junction-Eintrag erstellen

POST /api/v1/CAIKnowledgeCDokumente
Content-Type: application/json

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

Junction-Spalten aktualisieren

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

GET /api/v1/CDokumente

Einzelnes Dokument abrufen

GET /api/v1/CDokumente/{id}

Neues Dokument erstellen

POST /api/v1/CDokumente
Content-Type: application/json

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

Dokument aktualisieren

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

DELETE /api/v1/CDokumente/{id}

Relationship-Endpunkte

Verknüpfte AdvowareAkten

GET /api/v1/CDokumente/{id}/advowareAktens

Verknüpfte AIKnowledge Entries

GET /api/v1/CDokumente/{id}/aIKnowledges

Filtering & Sorting

Where-Clause Typen

equals (Exakte Übereinstimmung)

GET /api/v1/CAdvowareAkten?where[0][type]=equals&where[0][attribute]=syncStatus&where[0][value]=unclean

contains (Text-Suche)

GET /api/v1/CAdvowareAkten?where[0][type]=contains&where[0][attribute]=name&where[0][value]=2026

in (Liste von Werten)

GET /api/v1/CAdvowareAkten?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=unclean

greaterThan / lessThan

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

isNull / isNotNull

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

Sortierung

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

Pagination

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

Feld-Selektion

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

Praktische Beispiele

Beispiel 1: Alle unsynchronisierten Akten mit Details

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

# 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

# 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

# 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 '{
    "aktivierungsstatus": "active",
    "syncStatus": "synced",
    "lastSync": "2026-03-11T20:00:00+00:00"
  }'

Beispiel 5: Suche AI-Dokument via externe ID

# 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

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

Beispiel 7: Alle aktiven Akten abrufen

# 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

# 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"
  }'

🎯 Wichtige Hinweise

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

Anwendungsfälle:

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

# 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

GET /api/v1/CAdvowareAktenCDokumente
GET /api/v1/CAIKnowledgeCDokumente

❌ FALSCH: Standard Relationship-Endpoints geben additionalColumns NICHT zurück

GET /api/v1/CAdvowareAkten/{id}/dokumentes  # hnr/syncStatus NICHT in Response!

Hooks & Automatische Updates

Folgende Operationen lösen automatisch Hooks aus:

Dokument verknüpfen:

POST /api/v1/CAdvowareAkten/{id}/dokumentes
  • → DokumenteSyncStatus: Setzt Junction syncstatus = 'new'
  • → CheckGlobalSyncStatus: Berechnet globalen Status
  • → PropagateDocumentsUp: Verknüpft mit Räumungsklage/Mietinkasso

Dokument ändern:

PUT /api/v1/CDokumente/{id}
  • → UpdateJunctionSyncStatus: Markiert alle Junction-Einträge als "unclean"

Vor Entity speichern:

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:

-- 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.1

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

Reference in New Issue View Git Blame Copy Permalink