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

32 KiB
Raw Permalink Blame History

REST API Endpunkte - EspoCRM Custom Entities

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

Changelog:

  • v1.4 (12. März 2026): Custom API Endpoints mit routes.json Pattern hinzugefügt; Standard Junction Entity API Dokumentation entfernt (nur Custom API Pattern wird verwendet)
  • v1.3 (11. März 2026): pending_sync Status zu globalem syncStatus 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:

-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. CDokumente (Dokumente)
  4. Custom API Endpoints für Junction Tables
  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: Dieser Endpoint gibt KEINE Junction-Spalten zurück (hnr, syncstatus, lastSync). Nutze dafür den Custom 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

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

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 Custom Junction API Endpoint.

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

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)

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

# Custom API Endpoint für CAIKnowledge (siehe Custom API Sektion unten)
curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes" \
  -H "X-Api-Key: your-api-key"

# Response enthält alle Dokumente MIT Junction-Spalten in einem Call

Beispiel 3: Junction-Spalten aktualisieren

# Via Custom Junction API Endpoint (empfohlen)
curl -X PUT "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes/dok-789" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "aiDocumentId": "EXTERNAL-AI-123",
    "syncstatus": "synced",
    "updateLastSync": true
  }'

Beispiel 4: Sync-Status aktualisieren nach erfolgreicher Synchronisation

# Direktes Update mit Custom API (kein Suchen nötig!)
curl -X PUT "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes/dok-789" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "syncstatus": "synced",
    "updateLastSync": true
  }'

# Update global status (optional, Hooks machen das automatisch)
curl -X PUT "https://crm.example.com/api/v1/CAIKnowledge/kb-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

# Custom API gibt alle Dokumente mit Junction-Daten zurück
# Clientseitig filtern nach aiDocumentId:
curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes" \
  -H "X-Api-Key: your-api-key" | jq '.list[] | select(.aiDocumentId=="ai-doc-external-789")'

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

# Custom API gibt alle Dokumente zurück - clientseitig filtern nach syncstatus
curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes" \
  -H "X-Api-Key: your-api-key" | jq '.list[] | select(.syncstatus=="new" or .syncstatus=="unclean")'

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

Beispiel 9: Synchronisations-Workflow mit pending_sync

# 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

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

Blake3 Hash für Änderungserkennung

Zweck: Dokumentänderungen zwischen Synchronisationen erkennen

Das blake3hash Feld ist direkt am CDokumente Entity verfügbar und wird automatisch vom CDokumente Hook berechnet:

# Custom API gibt blake3hash mit zurück
curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes" \
  -H "X-Api-Key: your-api-key"

# Response enthält blake3hash für jedes Dokument:
{
  "list": [{
    "documentId": "dok-123",
    "documentName": "contract.pdf",
    "blake3hash": "b7cb1f2a3fd62f86aabff41a51921d96d10b54371c74d31c917b3c3074a204ca",
    "syncstatus": "synced"
  }]
}

Änderungserkennung:

  1. Bei Sync: Speichere aktuellen blake3hash clientseitig oder in eigenem System
  2. Nächster Sync: Frage Custom API ab, vergleiche blake3hash
  3. Wenn unterschiedlich → Dokument geändert → Re-Sync nötig
  4. Update syncstatus via Custom API PUT Endpoint

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:

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

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

# 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 Custom API Endpoints

GET /api/v1/JunctionData/CAIKnowledge/{knowledgeId}/dokumentes
# (Siehe Custom API Endpoints Sektion unten)

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

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

🚀 Custom API Endpoints für Junction Tables (Best Practice)

Problem: Die Standard Junction-Entity-API hat folgende Einschränkungen:

  • ACL-Zugriffsprobleme (oft 403 Forbidden trotz korrekter Konfiguration)
  • Keine JOIN-Queries → Separater Call für Dokumentdetails nötig
  • Umständliche Filterung
  • Hooks können unerwünschte Seiteneffekte haben

Lösung: Custom API Endpoint mit direkten SQL-Queries (seit EspoCRM 7.4+)

Implementation (Beispiel: CAIKnowledge Junction API)

1. Routes definieren

Datei: custom/Espo/Custom/Resources/routes.json

[
    {
        "route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes",
        "method": "get",
        "actionClassName": "Espo\\Custom\\Api\\JunctionData\\GetDokumentes"
    },
    {
        "route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId",
        "method": "put",
        "actionClassName": "Espo\\Custom\\Api\\JunctionData\\UpdateJunction"
    },
    {
        "route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId",
        "method": "post",
        "actionClassName": "Espo\\Custom\\Api\\JunctionData\\LinkDokument"
    }
]

Wichtig:

  • Nach Änderungen: Administration → Clear Cache (erforderlich!)
  • Route-Parameter mit :paramName → verfügbar als $request->getRouteParam('paramName')
  • actionClassName mit vollständigem Namespace (doppelte Backslashes!)

2. Action Class: GET - Alle Dokumente mit Junction-Daten

Datei: custom/Espo/Custom/Api/JunctionData/GetDokumentes.php

<?php

namespace Espo\Custom\Api\JunctionData;

use Espo\Core\Api\Action;
use Espo\Core\Api\Request;
use Espo\Core\Api\Response;
use Espo\Core\Api\ResponseComposer;
use Espo\Core\Exceptions\BadRequest;
use Espo\Core\Exceptions\NotFound;
use Espo\ORM\EntityManager;

/**
 * GET /api/v1/JunctionData/CAIKnowledge/:knowledgeId/dokumentes
 * 
 * Returns all documents linked to a knowledge entry with junction table data
 */
class GetDokumentes implements Action
{
    public function __construct(
        private EntityManager $entityManager
    ) {}
    
    public function process(Request $request): Response
    {
        $knowledgeId = $request->getRouteParam('knowledgeId');
        
        if (!$knowledgeId) {
            throw new BadRequest('Knowledge ID is required');
        }
        
        // Verify knowledge exists
        $knowledge = $this->entityManager->getEntityById('CAIKnowledge', $knowledgeId);
        if (!$knowledge) {
            throw new NotFound('Knowledge entry not found');
        }
        
        $pdo = $this->entityManager->getPDO();
        
        // Direct SQL query with JOIN - much more efficient!
        $sql = "
            SELECT 
                j.id as junctionId,
                j.c_a_i_knowledge_id as cAIKnowledgeId,
                j.c_dokumente_id as cDokumenteId,
                j.ai_document_id as aiDocumentId,
                j.syncstatus,
                j.last_sync as lastSync,
                d.id as documentId,
                d.name as documentName,
                d.blake3hash as blake3hash,
                d.created_at as documentCreatedAt,
                d.modified_at as documentModifiedAt
            FROM c_a_i_knowledge_dokumente j
            INNER JOIN c_dokumente d ON j.c_dokumente_id = d.id
            WHERE j.c_a_i_knowledge_id = :knowledgeId
              AND j.deleted = 0
              AND d.deleted = 0
            ORDER BY j.id DESC
        ";
        
        $sth = $pdo->prepare($sql);
        $sth->execute(['knowledgeId' => $knowledgeId]);
        
        $results = $sth->fetchAll(\PDO::FETCH_ASSOC);
        
        return ResponseComposer::json([
            'total' => count($results),
            'list' => $results
        ]);
    }
}

Wichtige Details:

  • Snake_case: DB-Spaltennamen verwenden snake_case (z.B. last_sync, nicht lastSync)
  • Dependency Injection: Constructor Injection funktioniert automatisch
  • PDO direkt: $this->entityManager->getPDO() für rohe SQL-Queries
  • Validierung: Entity-Existenz prüfen für bessere Errors
  • ResponseComposer::json(): Moderne Response-Methode

3. Action Class: PUT - Junction-Spalten aktualisieren

Datei: custom/Espo/Custom/Api/JunctionData/UpdateJunction.php

<?php

namespace Espo\Custom\Api\JunctionData;

use Espo\Core\Api\Action;
use Espo\Core\Api\Request;
use Espo\Core\Api\Response;
use Espo\Core\Api\ResponseComposer;
use Espo\Core\Exceptions\BadRequest;
use Espo\Core\Exceptions\NotFound;
use Espo\ORM\EntityManager;

/**
 * PUT /api/v1/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId
 * 
 * Updates junction table columns for an existing relationship
 */
class UpdateJunction implements Action
{
    public function __construct(
        private EntityManager $entityManager
    ) {}
    
    public function process(Request $request): Response
    {
        $knowledgeId = $request->getRouteParam('knowledgeId');
        $documentId = $request->getRouteParam('documentId');
        $data = $request->getParsedBody();
        
        if (!$knowledgeId || !$documentId) {
            throw new BadRequest('Knowledge ID and Document ID are required');
        }
        
        $pdo = $this->entityManager->getPDO();
        
        // Build dynamic UPDATE with only provided fields
        $setClauses = [];
        $params = [
            'knowledgeId' => $knowledgeId,
            'documentId' => $documentId
        ];
        
        if (isset($data->aiDocumentId)) {
            $setClauses[] = "ai_document_id = :aiDocumentId";
            $params['aiDocumentId'] = $data->aiDocumentId;
        }
        
        if (isset($data->syncstatus)) {
            $allowedStatuses = ['new', 'unclean', 'synced', 'failed', 'unsupported'];
            if (!in_array($data->syncstatus, $allowedStatuses)) {
                throw new BadRequest('Invalid syncstatus. Allowed: ' . implode(', ', $allowedStatuses));
            }
            $setClauses[] = "syncstatus = :syncstatus";
            $params['syncstatus'] = $data->syncstatus;
        }
        
        if (isset($data->lastSync)) {
            $setClauses[] = "last_sync = :lastSync";
            $params['lastSync'] = $data->lastSync;
        } elseif (isset($data->updateLastSync) && $data->updateLastSync === true) {
            $setClauses[] = "last_sync = NOW()";
        }
        
        if (empty($setClauses)) {
            throw new BadRequest('No fields to update. Provide: aiDocumentId, syncstatus, or lastSync');
        }
        
        $sql = "
            UPDATE c_a_i_knowledge_dokumente
            SET " . implode(', ', $setClauses) . "
            WHERE c_a_i_knowledge_id = :knowledgeId
              AND c_dokumente_id = :documentId
              AND deleted = 0
        ";
        
        $sth = $pdo->prepare($sql);
        $sth->execute($params);
        
        if ($sth->rowCount() === 0) {
            throw new NotFound('Junction entry not found or no changes made');
        }
        
        // Return updated data
        return ResponseComposer::json($this->getJunctionEntry($knowledgeId, $documentId));
    }
    
    private function getJunctionEntry(string $knowledgeId, string $documentId): array
    {
        $pdo = $this->entityManager->getPDO();
        
        $sql = "
            SELECT 
                id as junctionId,
                c_a_i_knowledge_id as cAIKnowledgeId,
                c_dokumente_id as cDokumenteId,
                ai_document_id as aiDocumentId,
                syncstatus,
                last_sync as lastSync
            FROM c_a_i_knowledge_dokumente
            WHERE c_a_i_knowledge_id = :knowledgeId
              AND c_dokumente_id = :documentId
              AND deleted = 0
        ";
        
        $sth = $pdo->prepare($sql);
        $sth->execute([
            'knowledgeId' => $knowledgeId,
            'documentId' => $documentId
        ]);
        
        $result = $sth->fetch(\PDO::FETCH_ASSOC);
        
        if (!$result) {
            throw new NotFound('Junction entry not found');
        }
        
        return $result;
    }
}

Highlights:

  • Dynamisches UPDATE: Nur Felder updaten, die im Request Body übergeben wurden
  • Validierung: Enum-Werte prüfen bevor DB-Update
  • NOW()-Trick: updateLastSync: true → Automatischer Timestamp
  • rowCount(): Prüfen ob wirklich ein Record betroffen war

4. Praktische API-Verwendung

GET: Alle Dokumente mit Junction-Daten abrufen

curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes" \
  -H "X-Api-Key: e53def10eea27b92a6cd00f40a3e09a4"

Response:

{
  "total": 2,
  "list": [
    {
      "junctionId": 5,
      "cAIKnowledgeId": "69b1b03582bb6e2da",
      "cDokumenteId": "6974aba30cd69c723",
      "aiDocumentId": "NEW-DOC-FROM-API",
      "syncstatus": "new",
      "lastSync": "2026-03-12 21:38:24",
      "documentId": "6974aba30cd69c723",
      "documentName": "2. dokuments",
      "blake3hash": null,
      "documentCreatedAt": "2026-01-24 11:23:15",
      "documentModifiedAt": "2026-03-03 09:48:14"
    },
    {
      "junctionId": 1,
      "cAIKnowledgeId": "69b1b03582bb6e2da",
      "cDokumenteId": "69a68b556a39771bf",
      "aiDocumentId": "UPDATED-VIA-API-123",
      "syncstatus": "synced",
      "lastSync": "2026-03-12 21:37:44",
      "documentId": "69a68b556a39771bf",
      "documentName": "hollibolli",
      "blake3hash": "b7cb1f2a3fd62f86aabff41a51921d96d10b54371c74d31c917b3c3074a204ca",
      "documentCreatedAt": "2026-03-03 07:18:45",
      "documentModifiedAt": "2026-03-12 20:19:01"
    }
  ]
}

PUT: Junction-Spalten aktualisieren

curl -X PUT "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes/69a68b556a39771bf" \
  -H "X-Api-Key: e53def10eea27b92a6cd00f40a3e09a4" \
  -H "Content-Type: application/json" \
  -d '{
    "aiDocumentId": "EXTERNAL-AI-DOC-123",
    "syncstatus": "synced",
    "updateLastSync": true
  }'

Response:

{
  "junctionId": 1,
  "cAIKnowledgeId": "69b1b03582bb6e2da",
  "cDokumenteId": "69a68b556a39771bf",
  "aiDocumentId": "EXTERNAL-AI-DOC-123",
  "syncstatus": "synced",
  "lastSync": "2026-03-12 21:42:15"
}

POST: Neues Dokument verknüpfen + Junction-Daten setzen

curl -X POST "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes/6974aba30cd69c723" \
  -H "X-Api-Key: e53def10eea27b92a6cd00f40a3e09a4" \
  -H "Content-Type: application/json" \
  -d '{
    "aiDocumentId": "NEW-EXTERNAL-DOC",
    "syncstatus": "new",
    "updateLastSync": true
  }'

Vorteile Custom API Endpoints

✅ Performance: JOIN-Queries in einem Call statt mehrere API-Requests
✅ Keine ACL-Probleme: Direkter DB-Zugriff umgeht ACL-System
✅ Volle Kontrolle: Exakte Control über SQL und Response-Struktur
✅ Hooks umgehen: SQL-Updates lösen keine Entity-Hooks aus (wenn gewünscht)
✅ Flexible Responses: Kann mehrere Entities in einer Response joinen
✅ Type Safety: Moderne PHP 8+ mit Constructor Property Promotion
✅ Wartbar: Klare Trennung zwischen Routes, Actions und Business Logic

Best Practices

  1. Immer validieren: Entity-Existenz prüfen bevor DB-Operations
  2. Snake_case beachten: DB-Spaltennamen verwenden Unterstriche
  3. Prepared Statements: Immer PDO Prepared Statements für SQL-Injection-Schutz
  4. Error Handling: Spezifische Exceptions (BadRequest, NotFound, Forbidden)
  5. Documentation: PHPDoc für jede Action Class mit Endpoint-Beschreibung
  6. Testing: API-Endpoints mit Python/Bash testen vor Produktiveinsatz
  7. Cache löschen: Nach routes.json Änderungen IMMER Cache clearen!

Wann Custom API verwenden?

✅ Verwende Custom API wenn:

  • Junction-Spalten häufig gelesen/geschrieben werden
  • JOINs über mehrere Tabellen nötig sind
  • Performance kritisch ist (viele Dokumente)
  • ACL-Probleme mit Standard Junction-Entity API
  • Spezielle Business Logic beim Read/Write nötig

❌ Verwende Standard API wenn:

  • Einfache CRUD ohne Junction-Spalten
  • ACL-System explizit gewünscht
  • Hooks sollen ausgelöst werden
  • Wenig Datenvolumen

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

Letzte Aktualisierung: 12. März 2026
Version: 1.4

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

Reference in New Issue View Git Blame Copy Permalink