Краткая инструкция по работе с API в Vtiger CRM

В этой статье я постараюсь дать ответы на самые часто задаваемые вопросы, как осуществлять взаимодействие с Vtiger CRM по API в части получения, изменения или создания записей. Система предоставляет API для взаимодействия сторонних приложений и веб-приложения с системой.

Разработчики постарались предоставить максимальные возможности для интеграции VtigerCRM с другими сервисами и системами, чтобы пользователи могли расширить возможности CRM для себя и других пользователей.

Создание собственных интеграций – это не так сложно, как может показаться на первый взгляд. Чтобы еще больше облегчить жизнь разработчику, кроме инструкций я постараюсь привести примеры использования методов и их описание в других статьях.

Итак, как осуществлять взаимодействие по API?

Для того, чтобы получить к данным в Vtiger CRM, вам нужно представиться и получить специальный код сессии, который вы в дальнейшем будете использовать для обмена данными.

Процесс авторизации проходит в два этапа.

Этап 1 - получаем токен шифрования.

Он нам необходим, чтобы в при следующем запросе зашифровать пароль для получения токена. Чтобы получить токен шифрования, нужно отправить обычный GET-запрос без пароля, указывая только логин пользователя, которому нужно выдать токен.

GET

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

Header

Content-type 

application/x-www-form-urlencoded

{

  "success": true,

  "result": {

    "token": "610a740fbbd66",

    "serverTime": 1628075023,

    "expireTime": 1628075323

  }

}

Обычно я рекомендую для взаимодействия с Vtiger создавать отдельного пользователя или подключаться под пользователями с ограниченными правами.

В ответе мы видим строку token. Она нам понадобится для второго этапа.

Этап 2 - получаем код сессии.

Первым делом нам потребуется зашифровать пароль. Шифрование происходит следующим образом:

• Вам нужно получить Access Key пользователя, который вы можете найти в профиле пользователя (не путайте с паролем).
• Зашифровать ключ, склеив его с токеном и прогнав через MD5.

Получить шифрованный ключ можно на сайте http://www.md5.cz/ , если вы пробуете взаимодействовать через postman или insomnia. В этом случае на сайте вводите склейку: md5(TOKENSTRING + ACCESSKEY)

Где Tokenstring - тот токен, который вы получили при первом запросе, Accesskey - ключ доступа в профиле пользователя.

Теперь когда у нас есть зашифрованный пароль, проходим авторизацю, отправляя запрос в CRM:

POST 

http://VTIGER_URL/webservice.php

Структура тела запроса - Form URL Encoded

operation=login

username=admin

accessKey=md5(TOKENSTRING + <ACCESSKEY>)

Получаем ответ

{

  "success": true,

  "result": {

    "sessionName": "5c1ad80d610a7a7aabe2e",

    "userId": "19x1",

    "version": "0.22",

    "vtigerVersion": "7.2.0-202008"

  }

}

Итак, теперь у нас есть номер сессии и мы его можем использовать при обмене данными с Vtiger.

Давайте попробуем совершить наиболее распространённые операции.

Этап 3 - Получаем список контактов.

GET

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

где SESSION_KEY - это наш полученный от CRM ключ сессии

Здесь стоит отметить, что мы по сути получаем контактов, используя SQL-запрос. Единственное, в нём мы указываем не название таблицы, а название модуля. Его также можно расширить, указав дополнительные условия для фильтра, например можно добавить WHERE modifiedtime > '2021-06-01' и оно будет работать.

В ответе вы получаете массив из контактов, где в ключе будет название поля и в значении - сами данные по этому полю.

Этап 4 - получение контакта по его ID

Это самое простое. Для этого нужно отправить обычный GET-запрос:

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

Здесь мы пытаемся получить контакт с номером 87. Но вы, наверное, заметили специальный префикс, мы передаём не просто цифру 87, а в специальном формате 12x87. Таким образом мы даём CRM понять, что мы получаем данные у модуля с цифрой 12, т.е. контакты.

Получить список всех модулей с их номерами вы можете в таблице CRM: vtiger_ws_entity

Этап 5 - создаём контакт

В этом случае нам потребуется передать POST запрос на http://VTIGER_URL/webservice.php , передав в виде формы следующие поля:

operation=create

sessionName=sessionId     

elementType=Contacts

Вам также потребуется передать специальное поле element, которое в виде строки в формате JSON будет содержать в себе все данные по вновь созданному контакту

element = 

{

    "firstname": "Александр",

    "phone": "+7908222448800",

    "lastname": "Ivanov",

    "otherphone": "+79086789985",

    "birthday": "1980-06-08",

    "email": "ivanov@sergeyem.ru",

    "assigned_user_id": "19x1",

}

Вам нужно передать в певую очередь обязательные поля. Чтобы понять, какие поля обязательные в модуле, попробууйте создать запись в CRM вручную и посмотрите на все поля, отмеченные звёздочкой.

Поле assigned_user_id обязательно во всех модулях. Если не знаете, что туда передавать, подставляйте номер администратора - 19x1

Этап 6 - Обновляем контакт

Аналогичным образом, передаём POST-запрос на http://VTIGER_URL/webservice.php с полями:

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"

}

Как вы могли заметить, мы не передаём название модуля. Мы в обязательном порядке должны передать ID в формате API, т.е. с префиксом 12x.

К счастью, для более простой работы с API Vtiger есть специальная библиотека, которой я активно пользуюсь: https://github.com/salaros/vtwsclib-php

Этап 6 - расширяем API

Удобство API в VtigerCRM в том, что вы можете без особых затруднений расширить его функционал, добавив новый метод.

В качестве примера рассмотрим возможность получать перевод определённого значения из CRM. Например, у вас есть файл переводов модуля Контакты. И вы хотите получить русское значение ключа SINGLE_Contacts. Или нескольких значений, передав массив переводимых параметров.

Сделать это, на удивление, очень просто.

Создадим функцию, которая будет осуществлять перевод. Создаём файл в папке include/Webservices/GetTranslation.php

со следующим содержимым:

function vtws_gettranslation($portal_language, $module, $totranslate, $user)

{

    global $log, $default_language, $current_language;

    $log->debug('> vtws_gettranslation');

    foreach ($totranslate as $key => $str) {

        $translated[$str] = Vtiger_Functions::getTranslatedString($str, $module, $portal_language);

    }

    return $translated;

}

Эта функция будет отвечать за обработку поступающего к ней API-запроса. Теперь нам осталось её только зарегистрировать. Для этого создайте папку scripts и в ней файл register_gettranslation.php

Содержимое этого файла:

$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!';

Запустите его из браузера один раз и обработчик будет успешно зарегистрирован.

Теперь, чтобы получить переводы через API, вам нужно отправить POST запрос по адресу http://VTIGER_URL/webservice.php с параметрами:

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

В ответе мы получим результат перевода двух значений:

{

  "success": true,

  "result": {

    "SINGLE_Contacts": "Контакт",

    "Contacts": "Контакты"

  }

}

Надеюсь, эта инструкция оказалась для вас полезной. Если у вас возникли потребности в доработке API - обращайтесь, с удовольствием вам помогу.