Hier folgt eine kurze Anleitung zur Arbeit mit der API in Vtiger CRM

Hier folgt eine kurze Anleitung zur Arbeit mit der API in Vtiger CRM

Vtiger CRM stellt eine umfassende API bereit, die es Drittanwendungen und Webdiensten ermöglicht, mit dem System zu interagieren – sei es zum Abrufen, Ändern oder Erstellen von Datensätzen. Dank zahlreicher Integrationsmöglichkeiten können Benutzer und Entwickler das CRM optimal an individuelle Bedürfnisse anpassen. In dieser Anleitung beantworte ich häufig gestellte Fragen rund um die API-Interaktion, erläutere den Authentifizierungsprozess und zeige anhand von Beispielen, wie typische Operationen durchgeführt werden.

────────────────────────────
Authentifizierung: So stellen Sie eine Verbindung her

Bevor Sie auf Daten zugreifen können, müssen Sie sich gegenüber Vtiger CRM authentifizieren und einen Sitzungsschlüssel (Session Key) erhalten. Der Authentifizierungsprozess erfolgt in zwei Schritten:

Schritt 1 – Erhalten eines Verschlüsselungstokens

Um den Sitzungsschlüssel zu generieren, benötigen Sie zunächst einen „challenge token“. Senden Sie hierfür einen einfachen GET-Request ohne Passwort und geben Sie lediglich den Benutzernamen an, für den der Token erstellt werden soll.

Beispiel:
GET
http://VTIGER_URL/webservice.php?operation=getchallenge&username=admin

Der Server antwortet mit einem JSON-Dokument, etwa so:

{
"success": true,
"result": {
"token": "610a740fbbd66",
"serverTime": 1628075023,
"expireTime": 1628075323
}
}

Notiz: Ich empfehle, für API-Zugriffe entweder einen speziellen API-Benutzer oder einen Benutzer mit eingeschränkten Rechten zu verwenden. Der im Antwortobjekt enthaltene Token wird im nächsten Schritt benötigt.

Schritt 2 – Sitzungsschlüssel anfordern

Nachdem Sie den Token erhalten haben, müssen Sie Ihr Passwort verschlüsseln. Hierzu:

• Suchen Sie den Access Key des Benutzers in dessen Profil (dieser ist vom Passwort zu unterscheiden).
• Erstellen Sie die Verschlüsselung, indem Sie den erhaltenen Token mit dem Access Key verketten und die Kombination mittels MD5-Hashing verarbeiten (z. B. über http://www.md5.cz/). Das heißt: md5(TOKENSTRING + ACCESSKEY).

Im nächsten Schritt senden Sie einen POST-Request an http://VTIGER_URL/webservice.php. Der Body (als Form URL Encoded) enthält folgende Felder:

operation=login
username=admin
accessKey=md5(TOKENSTRING + )

Die Antwort könnte folgendermaßen aussehen:

{
"success": true,
"result": {
"sessionName": "5c1ad80d610a7a7aabe2e",
"userId": "19x1",
"version": "0.22",
"vtigerVersion": "7.2.0-202008"
}
}

Mit dem erhaltenen sessionName steht Ihnen nun der API-Zugang zur Verfügung.

────────────────────────────
Typische API-Operationen

Schritt 3 – Abruf der Kontaktliste

Um Kontakte abzurufen, senden Sie einen GET-Request mit einem SQL-ähnlichen Query. Beispiel:

GET
http://VTIGER_URL/webservice.php?query=SELECT%20*%20FROM%20Contacts%3B&operation=query&sessionName=SESSION_KEY

Dabei ersetzt SESSION_KEY den zuvor erhaltenen Sitzungsschlüssel. Sie können den Query erweitern (z. B. um WHERE-Bedingungen wie modifiedtime > '2021-06-01' einzufügen), um gezielt zu filtern.

In der Antwort erhalten Sie ein Array von Kontakten, wobei die Schlüssel den Feldnamen und die Werte den entsprechenden Daten entsprechen.

Schritt 4 – Abruf eines Kontakts per ID

Um einen bestimmten Kontakt zu erhalten, genügt ein einfacher GET-Request. Wichtig ist dabei das spezielle Format der ID im API-Request (z. B. 12x87, wobei „12“ den Modul-Code und „87“ die ID des Kontakts darstellt).

Beispiel:

http://VTIGER_URL/webservice.php?id=12x87&operation=retrieve&sessionName=SESSION_KEY

Mit diesem Request wird der Kontakt mit der ID 87 aus dem Modul (hier Kontakte) abgerufen.

Schritt 5 – Erstellen eines neuen Kontakts

Zum Anlegen eines neuen Kontakts senden Sie einen POST-Request an http://VTIGER_URL/webservice.php. Der Request-Body (Form URL Encoded) enthält folgende Pflichtfelder:

operation=create
sessionName=sessionId
elementType=Contacts

Zusätzlich muss ein Feld „element“ enthalten sein – als JSON-String, der alle Daten des neuen Kontakts enthält. Beispiel:

element =
{
"firstname": "Александр",
"phone": "+7908222448800",
"lastname": "Ivanov",
"otherphone": "+79086789985",
"birthday": "1980-06-08",
"email": "ivanov@sergeyem.ru",
"assigned_user_id": "19x1"
}

Achten Sie darauf, zunächst alle Pflichtfelder zu übermitteln. In der Regel ist „assigned_user_id“ in allen Modulen erforderlich (wenn Sie unsicher sind, geben Sie die Administrator-ID, z. B. 19x1, an).

Schritt 6 – Aktualisieren eines Kontakts

Der Vorgang ähnelt dem Erstellen. Sie senden einen POST-Request mit folgenden Feldern:

operation=update
sessionName=sessionId
element =
{
"firstname": "Александр",
"phone": "+7908222448800",
"lastname": "Ivanov",
"otherphone": "+79086789985",
"birthday": "1980-06-15",
"email": "ivanov@sergeyem.ru",
"assigned_user_id": "19x1",
"id": "12x87"
}

Wichtig: Übergeben Sie die ID im API-Format (mit dem Modul-Präfix, also 12x).

────────────────────────────
Erweiterung der API

Ein großer Vorteil der Vtiger API besteht darin, dass sie beliebig erweitert werden kann. Sie können eigene Methoden hinzufügen, um beispielsweise Übersetzungen von Werten abzurufen. Hier ein Beispiel:

Erstellen Sie eine Funktion zur Übersetzung. Legen Sie in include/Webservices/GetTranslation.php folgenden Code ab:

function vtws_gettranslation($portal_language, $module, $totranslate, $user) {
global $log;
$log->debug('> vtws_gettranslation');
foreach ($totranslate as $key => $str) {
$translated[$str] = Vtiger_Functions::getTranslatedString($str, $module, $portal_language);
}
return $translated;
}

Registrieren Sie diese Funktion, indem Sie in einem Skript (z. B. scripts/register_gettranslation.php) folgenden Code verwenden:

$Vtiger_Utils_Log = true;
chdir('../');

include_once 'include/database/PearDatabase.php';
include_once 'include/Webservices/Utils.php';

global $current_user, $adb;
$db = PearDatabase::getInstance();

$operationName = 'gettranslation';
$handler_path = 'include/Webservices/GetTranslation.php';
$handler_method = 'vtws_gettranslation';
$operation_type = 'POST';

$result = $db->pquery("SELECT 1 FROM vtiger_ws_operation WHERE name = ?", array($operationName));
if (!$db->num_rows($result)) {
    $operationId = vtws_addWebserviceOperation($operationName, $handler_path, $handler_method, $operation_type);
    vtws_addWebserviceOperationParam($operationId, 'totranslate', 'encoded', 0);
    vtws_addWebserviceOperationParam($operationId, 'language', 'string', 0);
    vtws_addWebserviceOperationParam($operationId, 'module', 'string', 0);
}

echo 'DONE!';

Starten Sie dieses Skript im Browser einmalig, um den neuen Handler zu registrieren.

Anschließend können Sie Übersetzungen über einen POST-Request abrufen, z. B.:

operation=gettranslation
sessionName=SESSION_KEY
totranslate=["SINGLE_Contacts", "Contacts"]
language=ru_ru
module=Contacts

Die Antwort liefert dann beispielsweise:

{
"success": true,
"result": {
"SINGLE_Contacts": "Контакт",
"Contacts": "Контакты"
}
}

────────────────────────────
Fazit

Die Arbeit mit der API in Vtiger CRM ist dank des durchdachten Designs und der umfangreichen Dokumentation durchaus überschaubar. Mit wenigen einfachen Schritten – der Anmeldung (Token und Sitzungsschlüssel), gefolgt von der Durchführung von GET- und POST-Requests – können Sie Datensätze abrufen, erstellen oder aktualisieren. Darüber hinaus lassen sich eigene API-Methoden leicht integrieren, um den Funktionsumfang weiter zu erweitern.

Ich hoffe, diese Anleitung hilft Ihnen dabei, den Einstieg in die Vtiger API zu meistern und eigene Integrationen erfolgreich umzusetzen. Sollten Sie weitere Fragen haben oder Unterstützung bei der API-Entwicklung benötigen, stehe ich gern zur Verfügung.

Happy Coding und viel Erfolg mit Ihren Vtiger Integrationen!