IntraVision

Интеграция Intradesk с публичным WEB сайтом.

Цели интеграции

Целью интеграции вашего публичного сайта с Intradesk является поместить на публичном сайте вашей компании две кнопки (или ссылки):

1.       Зарегистрироваться и оставить обращение

2.       Войти на портал поддержки

По первой ссылке открывается попап окно с визардом из двух шагов: форма регистрации вашего клиента в Intradesk и форма создания заявки от него.

По второй ссылке просто переход на портал поддержки интрадеск http://YOUR_COMPAMY.intradesk.ru (посмотреть статусы ранее созданных заявок, дать комментарии).

Предлагаем сразу посмотреть как это работает https://intradesk.ru/apidemo/.

Если вам это интересно – читаем дальше 😊.

Подход к решению

Данное решение не является «готовым модулем с настройкой». Это просто легкий пример с исходным кодом на битрикс. Архив с исходным кодом приложен к данной статье.

Он служит для того, чтобы разработчик на bitrix за пару часов реализовал прототип подобного решения путем copy-paste приложенного кода и небольшим (или большим) тюнингом по требованию бизнеса.


Функциональность решения (CRM функции)

Вся функциональность (логика) реализована внутри API Intradesk. С Bitrix сайта вызывается лишь пара API методов Intradesk. Функциональность нашего API:

·         Шаг 1. Поиск Пользователя клиента в Intradesk по Email, Телефону, которые заполнили в форме регистрации. Если найдено, то заявка будет создана от найденного Пользователя (форма регистрации будет проигнорирована). 

·         Шаг. 2 В Intradesk есть возможность для Клиента (не путать с Пользователем клиента) задать домены. Например, для нашей компании ООО «Интравижн» – это intravision.ru, intradesk.ru, intraservice.ru. Если не удалось найти Пользователя клиента на первом шаге, то по Email система пытается найти Клиента по домену. Если найдено, то система создаст Пользователя клиента в найденном Клиенте. Например, по Email=mb@intravision.ru Пользователь будет создан внутри клиента ООО «Интравижн». И заявка будет создана от этого Пользователя внутри имеющегося Клиента.

Сложности, описанные выше, преследуют цель: не дублировать Клиентов, Пользователей клиентов. Это необходимо, чтобы видеть (фильтровать) все заявки от конкретного Клиента. Кстати, при подключении каналов Telegram, создания заявок по Звонку у вас будет работать та же логика. А именно, попытка системы найти Пользователя клиента (по Telegram, телефону), а не создавать нового. При этом, если такое всё-таки произошло (вы понимаете, что это один и тот же Клиент), то в интерфейсе Intradesk есть функция объединения Клиентов.

На втором шаге визарда простая форма для создания заявки. Для примера мы поместили выпадающий список Сервисов интрадеск с нашей тестовой площадки. Вы можете это скорректировать как считаете нужным.


В помощь разработчику Bitrix

Упрощенная документация: https://intradesk.ru/api/

Полная документация в формате Swagger. Там несколько микро-сервисов. В ссылке выше описание каждого из них. Для данной задачи требуется 2 микросервиса:

https://apigw.intradesk.ru/settings_docs/swagger/index.html?urls.primaryName=V4

https://apigw.intradesk.ru/tasklist_docs/swagger/index.html?urls.primaryName=V3

(На момент написания этой статьи – это версии 4 и 3. Проверяйте в swagger более новые версии)


Проверка Email
Так как API работает с клиентской базой, необходимо предусмотреть механизм проверки принадлежит ли данный Email пользователю который его указывает. В нашем случае мы реализовали механизм отправки проверочного кода на Email клиента (в API данный механизм не предусмотрен, его необходимо реализовать самостоятельно).

Для работы с API в данном примере мы будем работать с CURL.

Для реализации конкретного примера, нам потребуется 2 эндпоинта в API.

1)      Создание или поиск клиента в базе

2)      Создание заявки и назначения заявителя


Получение ApiKey

Для начала работы с API Intradesk необходимо получить ApiKey в разделе
Настройки -> Интеграции -> ApiKey


Создание Клиента, Пользователя клиента
Для создания, нам необходимо выполнить PUT запрос к эндпоинту 4й версии API  api/V4/Clients/InitUsers
Пример эндпоинта:
https://apigw.intradesk.ru/settings/api/v4/Clients/InitUsers?apikey=ВАШ_APIKEY
Метод запроса:
PUT
Заголовки:
Content-Type: application/json

Пример реализации запроса:

#Путь до ендпоинта
$URL = "https://apigw.intradesk.ru/settings/api/v4/Clients/InitUsers?apikey=ВАШ_APIKEY";
#Метод запроса
$TYPE = "PUT";
#Заголовок (эндпоинт готов нам вернуть данные в JSON)
$HEADER = ["Content-Type: application/json"];
#Формируем массив данных клиента, который в дальнейшем преобразуем в JSON
$raw["emailAddress"] = $email;
$raw["password"] = $pass;
$raw["clientType"] = 10; #физ. лицо имеет код 20, юр. лицо 10
$raw["userFirstName"] = "Имя";
$raw["userLastName"] = "Фамилия";
$raw["userMiddleName"] = "Отчество";
$raw["PhoneNumber"] = "Телефон клиента";
#следующие поля нужны для юридического лица
$raw["taxpayerNumber"] = "ИНН Клиента;
$raw["clientName"] = "Название компании";
$raw["web"] = "Web сайт компании";
#Преобразуем данные в JSON
$BODY = json_encode($raw, JSON_UNESCAPED_UNICODE);
  

#Выполняем запрос

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $URL);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $TYPE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $HEADER);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);

$output = curl_exec($ch);

curl_close($ch);

Ответ от сервера в случае успешного создания или поиска клиента в базе (данный метод не обновит данные клиента)

{
"userId": 279993, //id пользователя в системе
"userGroupId": 146623, //id группы клиента (для юр лиц)
"employeeGroupId": null,
"userType": 20,
"userGroupType": 10,
"clientType": 10,
"managerId": null,
"isSuccess": true,
"observerIds": [],
"errorMessages": [],
"warningMessages": [],
"isUserByAdditionalEmail": false
}

Для дальнейшего создания заявки извлекаем из полученного userId и userGroupId .



Создание заявки

Эндпоинт  создания заявки (/v3/Tasks) содержит множество полей, с их описанием лучше ознакомится по ссылке в Swagger. В примере же мы используем лишь базовый минимум для создания заявки и назначение исполнителя.

Пример эндпоинта:

https://apigw.intradesk.ru/changes/tasks?ApiKey=ВАШ_APIKEY
Метод запроса:

POST
Заголовки:

Content-Type: application/json

#Путь до ендпоинта
$URL = "https://apigw.intradesk.ru/changes/tasks?ApiKey=ВАШ_APIKEY";
#Заголовок (эндпоинт готов нам вернуть данные в JSON)
$HEADER = ["Content-Type: application/json"];
#Метод запроса
$TYPE = "POST";
$raw["blocks"]["name"] = quotemeta(
    json_encode(
       
array(
           
"value"=> "ЗАГОЛОВОК ЗАЯВКИ",
            )
        )
    )
;

$raw["blocks"]["description"] = quotemeta(
    json_encode(
       
array(
           
"value"=> "ТЕКСТ ЗАЯВКИ",
            )
        )
    )
;
$raw["blocks"]["initiator"] = quotemeta(
    json_encode(
       
array(
           
"value"=>array(
               
"userid"=>$userid, #ПОЛУЧИЛИ НА ПРОШЛОМ ШАГЕ
               
"groupid"=>$groupid #ПОЛУЧИЛИ НА ПРОШЛОМ ШАГЕ

           
)
        )
    )
)
;
#Преобразуем данные в JSON
$BODY = json_encode($raw, JSON_UNESCAPED_UNICODE);

#Выполняем запрос

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $URL);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $TYPE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $HEADER);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);

$output = curl_exec($ch);

curl_close($ch);

  

Немного подробнее о конструкции quotemeta(json_encode(array("value"=> "ЗНАЧЕНИЕ"))): 

В данном методе API JSON значения, вложен внутрь основного JSON. И что бы их отделить нам необходимо экранировать вложенный JSON.

Дополнительно

Тестовый пример https://intradesk.ru/apidemo/ интегрирован с тестовой площадкой https://demoapi.intradesk.ru/.  Чтобы детально изучить функционал (посмотреть как там создаются клиенты) вам надо зайти на эту площадку под администратором. Если вам это действительно необходимо, то напишите на support@intradesk.ru и мы предоставим вам доступ!

bitrix
интеграция