Оглавление 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 . '

'; print_r($output); В случае если не передано одно из обязательных полей, поднимается Exception. Обязательные поля: id клиента (contactid) и id контрагента-обидчика (offenderid) В случае если был корректно передан весь объем входных данных, то система возвращает ответ вида. {"success":true,"result":"83839"} Где в result содержится id созданного Проекта.