255 lines
13 KiB
Plaintext
255 lines
13 KiB
Plaintext
Оглавление
|
||
1 Архитектура веб-сервисов CRM-системы 1
|
||
2 Авторизация и получение токена 1
|
||
3 Открытие сессии 2
|
||
4 Получение списка файлов 2
|
||
4.1 Когда клиент с указанным ИНН и СМС-кодом не найден 3
|
||
4.2 Когда клиент найден 3
|
||
5 Создание/обновление клиента-физлица 4
|
||
6 Создание/обновление контрагента-юрлица 5
|
||
|
||
1 Архитектура веб-сервисов CRM-системы
|
||
Все запросы в CRM-систему передаются на единый endpoint: https://crm.clientright.ru/webservice.php
|
||
Все запросы снабжаются кодом операции, которую предстоит выполнить – по сути, это название функции. Код операции всегда передается в переменной operation, которая для GET-запросов передается в url в качестве параметра, а в POST-запросах – в теле.
|
||
Все запросы снабжаются идентификатором сессии, которая имеет ограниченное время жизни 15 минут. Рекомендует создавать новую сессию для каждого сеанса пользователя.
|
||
Далее мы рассмотрим методику получения идентификатора сессии, а так же вызовы прикладных, не системных operation (т.е. кастомных функций).
|
||
2 Авторизация и получение токена
|
||
Для отправки запросов в кастомные веб-сервисы CRM-системы в первую очередь необходимо авторизоваться и получить токен.
|
||
Сделать это можно следующим образом:
|
||
$endpointUrl = "https://crm.clientright.ru/webservice.php"; // это точка входа во все веб-сервисы CRM-системы, о которой мы писали выше
|
||
|
||
$userName="api"; // Учетка для обмена данными
|
||
|
||
$ch = curl_init();
|
||
$url = $endpointUrl . "?operation=getchallenge&username=" . $userName; // Здесь мы как раз указываем код операции, указывая значение «getchallenge» в параметре operation для GET-запроса
|
||
curl_setopt($ch, CURLOPT_URL, $url);
|
||
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
|
||
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
|
||
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
|
||
//curl_setopt($ch,CURLOPT_SSL_VERIFYPEER, false);
|
||
|
||
$response = curl_exec($ch);
|
||
$jsonResponse = json_decode($response, true);
|
||
|
||
$challengeToken = $jsonResponse['result']['token']; // Вынимаем временный токен из ответа
|
||
3 Открытие сессии
|
||
После того, как токен получен, необходимо получить идентификатор сессии обмена данными, который впоследствии будет предъявляться при каждом вызове той или иной операции.
|
||
Получить идентификатор сессии можно следующим образом:
|
||
$userAccessKey = '4r9ANex8PT2IuRV'; // персональный ключ доступа пользователя api
|
||
$generatedKey = md5($challengeToken.$userAccessKey); //ключ для получения сессии – MD5 от конкатенации полученного токена и персонального ключа.
|
||
|
||
// В данном случае мы используем POST-запрос, поэтому параметры передаем в теле, а не в url-запроса. Обязательный параметр operation так же присутствует
|
||
curl_setopt_array($ch, array(
|
||
CURLOPT_RETURNTRANSFER => 1,
|
||
CURLOPT_URL => $endpointUrl,
|
||
CURLOPT_POST => 1,
|
||
CURLOPT_POSTFIELDS => array(
|
||
'operation'=>'login',
|
||
'username'=>$userName,
|
||
'accessKey'=>$generatedKey
|
||
)
|
||
));
|
||
|
||
$response = curl_exec($ch);
|
||
|
||
$jsonResponse = json_decode($response, true);
|
||
$sessionId = $jsonResponse['result']['sessionName'];
|
||
|
||
Именно этот $sessionId будет использоваться в дальнейшем при обмене данными.
|
||
4 Получение списка файлов
|
||
Прикладной интерфейс, который, принимает в себя ИНН, введенный пользователем на форме, и СМС-код, через который подтверждался номер телефона.
|
||
Возвращает перечень файлов, связанных с карточкой клиента в CRM, у которого зафиксирован переданный снаружи ИНН.
|
||
Этот интерфейс вызывается после отработки штатного capture.php, в результате работы которого клиент регистрируется в базе.
|
||
Еще одно важное замечание: при передаче файлов-PDF-пустышек необходимо передавать действительные имена файлов так, как если бы передавались настоящие рабочие файлы!
|
||
Ниже пример вызова интерфейса, который имеет код operation = «GetFilesList»:
|
||
$params = array(
|
||
'operation'=>'GetFilesList',
|
||
'sessionName'=>$sessionId,
|
||
'inn'=>$inn,
|
||
'sms'=>$smscode
|
||
);
|
||
// В переменные 'inn' и 'sms' подставляем введенные пользователем значения
|
||
// В 'sessionName' передается полученный ранее идентификатор сессии
|
||
// В 'operation' константой код операции - GetFilesList
|
||
|
||
curl_setopt_array($ch, array(
|
||
CURLOPT_RETURNTRANSFER => 1,
|
||
CURLOPT_POST => 1,
|
||
CURLOPT_URL => $endpointUrl,
|
||
CURLOPT_POSTFIELDS => $params
|
||
));
|
||
$response = curl_exec($ch);
|
||
$output = json_decode($response, TRUE);
|
||
|
||
В случае если не передан ИНН или СМС-код – поднимается Exception
|
||
В случае если был корректно передан весь объем входных данных, то система может вернуть два варианта ответа.
|
||
4.1 Когда клиент с указанным ИНН и СМС-кодом не найден
|
||
{
|
||
"success":true,
|
||
"result":{
|
||
"status":" failed",
|
||
"message":" Клиент с указанным СМС-кодом и ИНН не найден"
|
||
}
|
||
}
|
||
Это странная ситуация, которая никогда не должна произойти. Если вдруг такое получилось, то скорее всего метод был вызван ДО создания Контакта через capture.php
|
||
4.2 Когда клиент найден
|
||
{
|
||
"success":true,
|
||
"result":{
|
||
"status":"ok",
|
||
"files":[
|
||
{
|
||
"title":"договор",
|
||
"path":"storage/2023/December/week4/9e84c3f86209302799f46d0136e93ab6.pdf"
|
||
},
|
||
{
|
||
"title":"подтверждение оплаты",
|
||
"path":"storage/2023/December/week4/cf65c58a01e7db0b19c8e1fe119c0e32.pdf"
|
||
},
|
||
{
|
||
"title":"Скриншот прогресса обучения/личного кабинета",
|
||
"path":"storage/2023/December/week4/ef77e0e1baf3a882fba1c24c258504b3.pdf"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
|
||
Обычная штатная ситуация, которую будем получать в большинство случаев.
|
||
Далее рассмотрим логику обработки ответов.
|
||
При обработке ответа НЕ стоит ориентироваться на переменную success – она всегда имеет значение true, если скрипт отработал корректно и не взорвался. Это вовсе НЕ означает, что бизнес-логика не нарушена.
|
||
За статус бизнес-логики отвечает переменная status, находящаяся внутри result – принимает значение ok, если бизнес-логика не разрушена, или failed, если бизнес-логика повреждена.
|
||
В этом же случая рядом будет находиться переменная message, содержащая расшифровку ошибки.
|
||
При успешном выполнении (status=’ok’), рядом будет находиться массив files, состоящий из N элементов – каждый из которых, есть файл. Описание каждого файла состоит из двух элементов:
|
||
* title – суть загруженного файла;
|
||
* path – полный путь к файлу, относительно корня папки CRM-системы – именно этот файл необходимо переписать корректным, «нормальным» файлом от пользователя. Естественно тип файла должен сохраниться и быть так же PDF.
|
||
Протестировать интерфейс можно с заведомо рабочей парой:
|
||
* ИНН – 643922466250
|
||
* СМС – 795372
|
||
5 Создание/обновление Клиента-физлица
|
||
Интерфейс принимает набор из 11 полей. Производит поиск среди имеющихся клиентов по номеру телефона. В случае отсутствия – создает нового клиента. При наличии – обновляет его данные.
|
||
В любом случае наружу возвращается id созданного или найденного клиента.
|
||
Этот id может быть использован в других методах взаимодействия с CRM. Например, при создании Проекта.
|
||
Состав полей в принимаемом массиве:
|
||
Наименование
|
||
Тип данных
|
||
Описание
|
||
operation
|
||
Строка
|
||
Константой код операции - CreateContact
|
||
sessionName
|
||
Строка
|
||
полученный ранее идентификатор сессии
|
||
firstname
|
||
Строка
|
||
Имя
|
||
secondname
|
||
Строка
|
||
Отчество
|
||
lastname
|
||
Строка
|
||
Фамилия
|
||
mobile
|
||
Строка
|
||
Телефон
|
||
email
|
||
Строка
|
||
Емейл
|
||
tgid
|
||
Число
|
||
Telegram ID
|
||
birthday
|
||
Строка
|
||
День рождения в формате ГГГГ-ММ-ДД
|
||
birthplace
|
||
Строка
|
||
Место рождения
|
||
mailingstreet
|
||
Строка
|
||
Адрес проживания
|
||
inn
|
||
Строка
|
||
ИНН
|
||
requisites
|
||
Строка
|
||
Реквизиты для перечисления средств
|
||
code
|
||
Строка
|
||
СМС код
|
||
Ниже пример вызова интерфейса, который имеет код operation = «CreateContact»:
|
||
$params = array(
|
||
'operation'=>'CreateContact',
|
||
'sessionName'=>$sessionId,
|
||
'firstname' => 'Василий',
|
||
'secondname' => 'Алибабаевич',
|
||
'lastname' => 'Пупкинидзе',
|
||
'mobile' => '+7(949) 123-45-11',
|
||
'email' => 'rrrr@mail.ru',
|
||
'tgid' => 111,
|
||
'birthday' => '1986-11-15',
|
||
'birthplace' => 'г. Владивосток',
|
||
'mailingstreet' => 'г. Калининград',
|
||
'inn' => '321654987654',
|
||
'requisites' => 'шлите на карту в тинькофф',
|
||
'code' => '4568'
|
||
);
|
||
|
||
curl_setopt_array($ch, array(
|
||
CURLOPT_RETURNTRANSFER => 1,
|
||
CURLOPT_POST => 1,
|
||
CURLOPT_URL => $endpointUrl,
|
||
CURLOPT_POSTFIELDS => $params
|
||
));
|
||
$response = curl_exec($ch);
|
||
$output = json_decode($response, TRUE);
|
||
|
||
В случае если не передано одно из обязательных полей, поднимается Exception.
|
||
Обязательные поля: имя, фамилия, день рождения, телефон и ИНН.
|
||
В случае если был корректно передан весь объем входных данных, то система возвращает ответ вида.
|
||
{"success":true,"result":"83859"}
|
||
Где в result содержится id созданного или обновленного клиента, найденного по номеру телефона.
|
||
6 Создание/обновление Контрагента-юрлица
|
||
Интерфейс принимает набор из 7 полей. Производит поиск среди имеющихся контрагентов по ИНН. В случае отсутствия – создает нового контрагента. При наличии – обновляет его данные.
|
||
В любом случае наружу возвращается id созданного или найденного контрагента.
|
||
Этот id может быть использован в других методах взаимодействия с CRM. Например, при создании Проекта.
|
||
Состав полей в принимаемом массиве:
|
||
Наименование
|
||
Тип данных
|
||
Описание
|
||
operation
|
||
Строка
|
||
Константой код операции - CreateAccount
|
||
sessionName
|
||
Строка
|
||
полученный ранее идентификатор сессии
|
||
accountname
|
||
Строка
|
||
Наименование юрлица
|
||
address
|
||
Строка
|
||
Его юр.адрес
|
||
email
|
||
Строка
|
||
Емейл
|
||
website
|
||
Строка
|
||
Сайт
|
||
phone
|
||
Строка
|
||
Телефон
|
||
inn
|
||
Строка
|
||
ИНН
|
||
ogrn
|
||
Строка
|
||
ОГРН
|
||
Ниже пример вызова интерфейса, который имеет код operation = «CreateAccount»:
|
||
$params = array(
|
||
'operation'=>'CreateAccount',
|
||
'sessionName'=>$sessionId,
|
||
'accountname' => 'ООО "Три бобра"',
|
||
'address' => 'г. Москва, Кремль',
|
||
'email' => 'qqqqq@ya.ru',
|
||
'website' => 'https://pikabu.ru',
|
||
'phone' => '+7 928 664-66-11',
|
||
'inn' => '1234567899',
|
||
'ogrn' => '32165498711'
|
||
);
|
||
|
||
curl_setopt_array($ch, array(
|
||
CURLOPT_RETURNTRANSFER => 1,
|
||
CURLOPT_POST => 1,
|
||
CURLOPT_URL => $endpointUrl,
|
||
CURLOPT_POSTFIELDS => $params
|
||
));
|
||
$response = curl_exec($ch);
|
||
$output = json_decode($response, TRUE);
|
||
|
||
В случае если не передано одно из обязательных полей, поднимается Exception.
|
||
Обязательные поля: название организации, ИНН и ОГРН.
|
||
В случае если был корректно передан весь объем входных данных, то система возвращает ответ вида.
|
||
{"success":true,"result":"83837"}
|
||
Где в result содержится id созданного или обновленного контрагента, найденного по ИНН.
|
||
7 Создание нового Проекта
|
||
Интерфейс принимает набор из 27 полей и создает с ними Проект.
|
||
Наружу возвращается id созданного или найденного контрагента.
|
||
Этот id может быть использован в других методах взаимодействия с CRM.
|
||
Состав полей в принимаемом массиве:
|
||
Наименование
|
||
Тип данных
|
||
Описание
|
||
operation
|
||
Строка
|
||
Константой код операции - CreateAccount
|
||
sessionName
|
||
Строка
|
||
полученный ранее идентификатор сессии
|
||
contactid
|
||
Число
|
||
id клиента, который вернулся из метода создания/обновления клиента – обязательное поле
|
||
offenderid
|
||
Число
|
||
id контрагента-обидчика, который вернулся из метода создания/обновления контрагента – обязательное поле
|
||
agentid
|
||
Число
|
||
id контрагента-посредника, который вернулся из метода создания/обновления контрагента
|
||
может быть пустым, если клиент обращался к злодею напрямую без посредников
|
||
sms
|
||
Строка
|
||
Код из смс
|
||
ip
|
||
Строка
|
||
ip пользователя
|
||
source
|
||
Строка
|
||
Откуда пришли
|
||
region
|
||
Строка
|
||
Регион пользователя, откуда поступило обращение
|
||
formid
|
||
Число
|
||
id формы
|
||
category
|
||
Строка
|
||
Категория обращения
|
||
direction
|
||
Строка
|
||
Направление обращения
|
||
agrprice
|
||
Число
|
||
Цена договора
|
||
subject
|
||
Строка
|
||
Предмет договора
|
||
agrdate
|
||
Строка
|
||
Дата заключения договора в формате ГГГГ-ММ-ДД
|
||
startdate
|
||
Строка
|
||
Срок начальный в формате ГГГГ-ММ-ДД
|
||
finishdate
|
||
Строка
|
||
Срок конечный в формате ГГГГ-ММ-ДД
|
||
loss
|
||
Число
|
||
Убыток
|
||
servicecost
|
||
Число
|
||
Стоимость полученной услуги
|
||
progress
|
||
Число
|
||
Прогресс чего бы то ни было в %
|
||
country
|
||
Строка
|
||
Страна путешествия
|
||
hotel
|
||
Строка
|
||
Средство размещение (отель)
|
||
transport
|
||
Строка
|
||
Транспортные услуги – передается значение «да» или «нет»
|
||
insurance
|
||
Строка
|
||
Страховка (страховая) – передается значение «да» или «нет»
|
||
other
|
||
Строка
|
||
Прочее
|
||
description
|
||
Строка
|
||
Описание
|
||
independently
|
||
Строка
|
||
Самостоятельно соблюден претензионный порядок – передается значение «да» или «нет»
|
||
claimdate
|
||
Строка
|
||
Дата направления претензии в формате ГГГГ-ММ-ДД
|
||
returned
|
||
Число
|
||
Вернули в претензионном порядке
|
||
Ниже пример вызова интерфейса, который имеет код operation = « CreateProject »:
|
||
$params = array(
|
||
'operation'=>'CreateProject',
|
||
'sessionName'=>$sessionId,
|
||
'contactid' => 83834,
|
||
'offenderid' => 84675,
|
||
'agentid' => 83859,
|
||
'sms' => '1234',
|
||
'ip' => '192.168.0.1',
|
||
'source' => 'с улицы',
|
||
'region' => 'Владивосток',
|
||
'formid' => 1376,
|
||
'category' => 'Абидили!!',
|
||
'direction' => 'Путину',
|
||
'agrprice' => 20000,
|
||
'subject' => 'За мир во всем мире',
|
||
'agrdate' => '2023-07-15',
|
||
'startdate' => '2023-07-20',
|
||
'finishdate' => '2023-08-31',
|
||
'loss' => 5000,
|
||
'servicecost' => 3000,
|
||
'progress' => 25,
|
||
'country' => 'Турция',
|
||
'hotel' => 'Абу Мартышкин Spa',
|
||
'transport' => 'да',
|
||
'insurance' => 'да',
|
||
'other' => 'какое-то дополнение',
|
||
'description' => 'какое-то описание',
|
||
'independently' => 'да',
|
||
'claimdate' => '2023-10-15',
|
||
'returned' => 200
|
||
);
|
||
|
||
curl_setopt_array($ch, array(
|
||
CURLOPT_RETURNTRANSFER => 1,
|
||
CURLOPT_POST => 1,
|
||
CURLOPT_URL => $endpointUrl,
|
||
CURLOPT_POSTFIELDS => $params
|
||
));
|
||
$response = curl_exec($ch);
|
||
$output = json_decode($response, TRUE);
|
||
|
||
echo $response . '<br><br>';
|
||
print_r($output);
|
||
В случае если не передано одно из обязательных полей, поднимается Exception.
|
||
Обязательные поля: id клиента (contactid) и id контрагента-обидчика (offenderid)
|
||
В случае если был корректно передан весь объем входных данных, то система возвращает ответ вида.
|
||
{"success":true,"result":"83839"}
|
||
Где в result содержится id созданного Проекта.
|