IntraVision

Все возможности системы
< Список статей

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

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

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

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

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

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

Вторая кнопка -  переход на портал поддержки 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 есть функция объединения Клиентов.

На втором шаге визарда простая форма для создания заявки. Для примера мы поместили выпадающий список Сервисов 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
                        

                        

                            интеграция