Dokumente per API an Kontakte in VtigerCRM anbinden – Eine Anleitung

Dokumente per API an Kontakte in VtigerCRM anbinden – Eine Anleitung

Das Anhängen externer Dokumente (z. B. Scans, Verträge) an Kontakte via API spart Zeit und automatisert Workflows. In dieser Anleitung zeigen wir, wie Sie:

1. Dokumente mit externen Links erstellen
2. Sie automatisch an Kontakte binden
3. Fehler bei der Relationierung beheben

Voraussetzungen

• API-Zugriff: Aktiviert in Einstellungen > Entwickler > API
• Session-Key: Erhalten via getchallenge und login Endpoints
• Modul-IDs: Dokumente (Documents), Kontakte (Contacts)

Schritt 1: Dokument mit externem Link erstellen

Senden Sie einen POST-Request an /webservice.php:

// Beispiel in PHP mit cURL
$data = [
    'operation' => 'create',
    'sessionName' => 'SESSION_KEY_HIER_EINFÜGEN',
    'elementType' => 'Documents',
    'element' => json_encode([
        "notes_title" => "Externer Vertrag",
        "filename" => "https://ihr-service.com/vertrag.pdf", // Externe URL
        "assigned_user_id" => "19x1", // Benutzer-ID
        "filelocationtype" => "E", // "E" = Extern
        "relations" => "12x100" // Kontakt-ID (Format: [Modul-ID]x[Record-ID])
    ])
];

$ch = curl_init('https://ihre-domain.de/webservice.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Erklärung der Felder:

• relations: Bindet das Dokument an den Kontakt mit der ID 100 (Modul-ID 12x für Kontakte)
• filelocationtype: E für externe Links, I für hochgeladene Dateien

Problem: Dokument erscheint nicht im Kontakt

Obwohl das Dokument erstellt wird, fehlt die Verknüpfung in der Kontaktkarte. Grund: Die Relation wird beim API-Call nicht automatisch gesetzt.

Schritt 2: Code-Anpassungen für Relationierung

A. Hilfsfunktion hinzufügen

Fügen Sie diese Funktion in include/Webservices/Utils.php ein:

// Gibt die Modul-ID zurück (z. B. für "Contacts")
function vtws_getEntityId($entityName) {
    global $adb;
    $result = $adb->pquery('SELECT id FROM vtiger_ws_entity WHERE name = ?', [$entityName]);
    return ($result && $adb->num_rows($result) > 0)
        ? $adb->query_result($result, 0, 'id')
        : 0;
}

B. Relation-Logik korrigieren

Ändern Sie die Funktion vtws_internal_setrelation in include/Webservices/SetRelation.php (ca. Zeile 57):

Vorher:

relateEntities($focus, $moduleName, $elementId, $withModuleName, $withElementId);

Nachher:

// Korrektur der Dokument-Kontakt-Relation
if ($moduleName === 'Documents' && $withModuleName === 'Contacts') {
    $focus = CRMEntity::getInstance($withModuleName);
// Variablen tauschen
    list($elementId, $withElementId) = [$withElementId, $elementId];
    list($moduleName, $withModuleName) = [$withModuleName, $moduleName];
}

relateEntities($focus, $moduleName, $elementId, $withModuleName, $withElementId);

Ergebnis

• Das Dokument wird angelegt und erscheint unter Dokumente.
• Die Verknüpfung zum Kontakt ist in dessen Detailansicht sichtbar.

Tipps & Fehlerbehebung

• Modul-IDs prüfen: SELECT * FROM vtiger_ws_entity WHERE name IN ('Contacts', 'Documents');
• Session-Key erneuern: Bei Timeout-Fehlern neu anmelden.
• Berechtigungen: Stellen Sie sicher, dass der API-Benutzer Rechte für beide Module hat.

Fazit

Mit diesen Anpassungen integrieren Sie externe Dokumente nahtlos in VtigerCRM. Für komplexere Szenarien (z. B. Datei-Uploads) nutzen Sie filelocationtype = "I" und kodieren Sie die Datei in Base64.

📩 Fragen? Kontaktieren Sie uns für Support bei individuellen Anpassungen!