мета-данные страницы
Различия
Здесь показаны различия между двумя версиями данной страницы.
Предыдущая версия справа и слева Предыдущая версия | Предыдущая версия Следующая версия Следующая версия справа и слева | ||
api [20.02.2024 15:03] |
api [16.05.2024 12:58] Anatoly [Работа с выездами] |
||
---|---|---|---|
Строка 1: | Строка 1: | ||
+ | ====== Документация по API ====== | ||
+ | ---- | ||
+ | ===== Оглавление ===== | ||
+ | [[#Описание API|Описание API]]\\ | ||
+ | [[#Виды команд API|Виды команд API]]\\ | ||
+ | [[#Формат команд|Формат команд]]\\ | ||
+ | [[#Примеры интеграции|Примеры интеграции]]\\ | ||
+ | [[#Коды ошибок API|Коды ошибок API]]\\ | ||
+ | [[#Авторизация|Авторизация]]\\ | ||
+ | [[#Получение изменившихся заказов и клиентов]]\\ | ||
+ | [[#Пример работы с обсуждениями|Пример работы с обсуждениями]]\\ | ||
+ | [[#Работа с выездами|Работа с выездами]]\\ | ||
+ | [[#Работа со статистикой ЛК|Работа со статистикой ЛК]]\\ | ||
+ | ---- | ||
+ | ===== Описание API ===== | ||
+ | %%API%% позволяет реализовать Личный кабинет клиента, используя __клиентскую сессию__ (авторизованного пользователя SessionID), получая информацию только по этому клиенту.\\ | ||
+ | На основе полученной сессии, команды возвращают информацию **Только по одному текущем клиенту**.\\ | ||
+ | **Время "жизни" клиентской сессии неограниченно.**\\ | ||
+ | |||
+ | %%API%% позволяет реализовать создание и редактирование заказов, добавление оплаты в заказ, создание и изменение клиентов, получение изменившихся заказов и клиентов и др. через __коммерческие команды__, используя __пользовательскую сессию__ (авторизованного пользователя SessionID). | ||
+ | |||
+ | <WRAP important round>API с клиентской сессией **Не позволяет реализовать синхронизацию всех заказов/клиентов и др. со сторонними сервисами**.\\ | ||
+ | Т.к. это может привести к избыточной нагрузке и большому количеству запросов.</WRAP> | ||
+ | |||
+ | Для реализации таких целей, правильно использовать %%API%% c __пользовательской сессией__.\\ | ||
+ | Для этого есть команды загрузки Изменившихся заказов за период (с выводом подробной информации по заказу), изменившихся клиентов, создание и изменение заказов. | ||
+ | |||
+ | Виды команд:\\ | ||
+ | * //__Команды %%API%% без сессии__// - команды получения общих данных из стандартных справочников, **для выполнения которых Не требуется сессия**.\\ | ||
+ | * //__Команды %%API%% ТОЛЬКО с клиентской сессией__// - команды получения данных по конкретному клиенту, **для выполнения которых Требуется клиентская сессия**.\\ | ||
+ | * //__Команды %%API%% ТОЛЬКО с пользовательской сессией__// - команды получения данных, **для выполнения которых Требуется пользовательская сессия**.\\ | ||
+ | * //__Команды %%API%% с пользовательской или клиентской сессией__// - команды получения данных, **для выполнения которых Требуется клиентская или пользовательская сессия**.\\ | ||
+ | * //__Коммерческие команды %%API%% с пользовательской сессией__// - команды сохранения/редактирования клиентов, заказов, оплаты и т.п., **для выполнения которых Требуется пользовательская сессия**.\\ | ||
+ | |||
+ | ---- | ||
+ | ===== Виды команд API ===== | ||
+ | [[api:no_session|1. Команды API без сессии]]\\ | ||
+ | [[api:client_session|2. Команды API ТОЛЬКО с клиентской сессией]]\\ | ||
+ | [[api:user_session|3. Команды API ТОЛЬКО с пользовательской сессией]]\\ | ||
+ | [[api:double_session|4. Команды API с клиентской или пользовательской сессией]]\\ | ||
+ | [[api:commercial_session|5. Коммерческие команды API с пользовательской сессией]]\\ | ||
+ | ---- | ||
+ | ===== Схема работы API ===== | ||
+ | {{:работа_api.drawio.png?direct&600 |}}\\ | ||
+ | ---- | ||
+ | ===== Формат команд ===== | ||
+ | |||
+ | Все команды выполняются методом **GET** или **POST**. Ответ на запрос приходит в **json** формате. | ||
+ | |||
+ | Все значения параметров команд должны быть преобразованы, __через js encodeURIComponent, через php urlencode или подобные функции__. | ||
+ | |||
+ | **Пример:** | ||
+ | GET /himinfo.ru/cl/{Path}/api/?command={"key":"value"}&SessionID=...&callback=... | ||
+ | **Преобразованный пример:** | ||
+ | GET /himinfo.ru/cl/{Path}/api/?command=%7B%22key%22%3A%22value%22%7D&SessionID=...&callback=... | ||
+ | |||
+ | где:\\ | ||
+ | * //{Path}// - имя для Химчистки. Для получения этого параметра обратитесь в Клиентский сервис; | ||
+ | * //command// - название выполняемой команды; | ||
+ | * //%%{"key": "value"}%%// - параметры команды (значение=ключ). Представляет собой текстовую аналогию записи объекта на JS; | ||
+ | * //SessionID// - __в зависимости от команды **обязательный** параметр__. Указывает ID сессии для выполнения команды. Выдается при выполнении команды авторизации; | ||
+ | * //callback// - необязательный параметр. Указывает на имя процедуры для jsonP, которое вернется в ответе с json строкой. | ||
+ | |||
+ | //**В ответе на запрос могут присутствовать поля, не описанные в настоящей документации. Приложению следует их игнорировать.**// | ||
+ | ---- | ||
+ | ===== Примеры интеграции ===== | ||
+ | |||
+ | **Пример запросов на php:** | ||
+ | |||
+ | <sxh php> | ||
+ | $curl = curl_init(); | ||
+ | |||
+ | curl_setopt_array($curl, [ | ||
+ | CURLOPT_URL => "//himinfo.ru/cl/{Path}/api/?command=".urlencode('{"param1": "{$param1}", "param2": "{$param2}", "param3": "{$param3}"}'), | ||
+ | CURLOPT_RETURNTRANSFER => true, | ||
+ | CURLOPT_ENCODING => "", | ||
+ | CURLOPT_MAXREDIRS => 10, | ||
+ | CURLOPT_TIMEOUT => 30, | ||
+ | CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, | ||
+ | CURLOPT_CUSTOMREQUEST => "GET", | ||
+ | CURLOPT_POSTFIELDS => "", | ||
+ | ]); | ||
+ | |||
+ | $response = curl_exec($curl); | ||
+ | $err = curl_error($curl); | ||
+ | |||
+ | curl_close($curl); | ||
+ | |||
+ | if ($err) | ||
+ | echo "cURL Error #:" . $err; | ||
+ | else | ||
+ | echo $response; | ||
+ | </sxh> | ||
+ | |||
+ | **Пример запросов на JavaScript:** | ||
+ | |||
+ | <sxh javascript> | ||
+ | const data = null; | ||
+ | |||
+ | const xhr = new XMLHttpRequest(); | ||
+ | xhr.withCredentials = true; | ||
+ | |||
+ | xhr.addEventListener("readystatechange", function () { | ||
+ | if (this.readyState === this.DONE) | ||
+ | console.log(this.responseText); | ||
+ | }); | ||
+ | |||
+ | xhr.open("GET", '//himinfo.ru/cl/{Path}/api/?command=' + encodeURIComponent('{"param1": "' + param1.val() + '", "param2": "' + param2.val() + '", "param3": "' + param3.val()+ '"}'); | ||
+ | |||
+ | xhr.send(data); | ||
+ | </sxh> | ||
+ | |||
+ | **Пример запросов на jQuery:** | ||
+ | |||
+ | Функция __encodeURIComponent__ выполняется для всех значений параметров команды: | ||
+ | |||
+ | <sxh javascript> | ||
+ | '//himinfo.ru/cl/{Path}/api/?command=' + encodeURIComponent('{"param1": "' + param1.val() + '", "param2": "' + param2.val() + '", "param3": "' + param3.val()+ '"}'), | ||
+ | </sxh> | ||
+ | |||
+ | 1) в данном случае метод $.ajax сам выполнит encodeURL: | ||
+ | <sxh javascript> | ||
+ | $.ajax({ | ||
+ | 'url': '//himinfo.ru/cl/{Path}/api/', | ||
+ | 'data': {'command': '{"param1": "' + param1.val() + '", "param2": "' + param2.val() + '", "param3": "' + param3.val() + '"}'}, | ||
+ | 'dataType': 'jsonp', | ||
+ | 'success': function(response, ioArgs){}, | ||
+ | 'error': function(XMLHttpRequest, textStatus, errorThrown){}, | ||
+ | 'josnpCallback': 'callback', | ||
+ | 'timeout': 30000 | ||
+ | }); | ||
+ | </sxh> | ||
+ | |||
+ | 2) | ||
+ | <sxh javascript> | ||
+ | $.ajax({ | ||
+ | 'url': '//himinfo.ru/cl/{Path}/api/?command=' + encodeURIComponent('{"param1": "' + param1.val() + '", "param2": "' + email.val() + '", "param1": "' + name.val()+ '"}'), | ||
+ | 'dataType': 'jsonp', | ||
+ | 'success': function(response, ioArgs){}, | ||
+ | 'error': function(XMLHttpRequest, textStatus, errorThrown){}, | ||
+ | 'josnpCallback': 'callback', | ||
+ | 'timeout': 30000 | ||
+ | }); | ||
+ | </sxh> | ||
+ | ---- | ||
+ | ===== Коды ошибок API ===== | ||
+ | |||
+ | |**Код ошибки**|**Текст ошибки** |**Описание** | | ||
+ | |100 |Ошибка подключения к БД<sup>1</sup> | | | ||
+ | |101 |Ошибка выполнения запроса<sup>1</sup> | | | ||
+ | |102 |Слишком частые запросы | | | ||
+ | |103 |Отсутствуют команды на выполнение. |Не правильно была сформирована API команда или такой не существует.| | ||
+ | |104 |Отсутствуют параметры команды |Не правильно указаны параметры в команде API. | | ||
+ | |105 |Некорректные данные |Не правильный формат данных в параметрах команды API. | | ||
+ | |106 |Недействительный SessionID | | | ||
+ | |107 |Не завершилась предыдущая команда |Не завершилась предыдущая команда. **Устаревший код ошибки** | | ||
+ | |108 |Сервер недоступен! Попробуйте подключиться позже |БД химчистки не доступна | | ||
+ | |109 |Ошибка выполнения команды<sup>1</sup> |Ошибка выполнения команды на Himinfo | | ||
+ | <sup>1</sup> - обратиться к разработчикам Агбис. | ||
+ | ---- | ||
+ | ===== Авторизация ===== | ||
+ | |||
+ | Для регистрации используется команда **[[api:no_session#ModernRegistration|ModernRegistration]]**. | ||
+ | |||
+ | Для авторизации используется команда **[[api:no_session#ModernLogin|ModernLogin]]**. | ||
+ | |||
+ | Для восстановления пароля команда **[[api:no_session#ModernRememberPwd|ModernRememberPwd]]**. | ||
+ | ---- | ||
+ | ===== Получение изменившихся заказов и клиентов ===== | ||
+ | Для получения списка изменившихся заказов, правильнее воспользоваться командами - **[[api:user_session#OrderByDateTimeForAll|OrderByDateTimeForAll]]**, **[[api:double_session#LastChangeOrder|LastChangeOrder]]**. | ||
+ | |||
+ | Для получения списка изменившихся клиентов, использовать команду **[[api:user_session#ClientsByDateTimeForAll|ClientsByDateTimeForAll]]**. | ||
+ | ---- | ||
+ | ===== Пример работы с обсуждениями ===== | ||
+ | |||
+ | __В модуле Агбис.Химчистка сообщение отображается в Сервис - Общение с Клиентами в "Журнал Оперативного общения с клиентами" или в "Сообщения из ЛК"__ | ||
+ | |||
+ | 1) **[[api:client_session#TitleMessages|TitleMessages]]** - получить список обсуждений происходит по сессии, т.е. только конкретно для авторизованного клиента. вернет: | ||
+ | GET //himinfo.ru/cl/{Path}/api/?TitleMessages&SessionID=... | ||
+ | |||
+ | Ответ **json**: | ||
+ | |||
+ | <sxh json> | ||
+ | { | ||
+ | "error": 0, | ||
+ | "Messages": [ | ||
+ | { | ||
+ | "id": "10045", | ||
+ | "doc_num": "", | ||
+ | "dttm": "16.03.2015 5:48:19", | ||
+ | "comment": "test", | ||
+ | "user": "1", | ||
+ | "star": "0", | ||
+ | "message_type": "5", | ||
+ | "new_mes_count": "0", | ||
+ | "status_message": "0" | ||
+ | } | ||
+ | ] | ||
+ | } | ||
+ | </sxh> | ||
+ | |||
+ | 2) **[[api:client_session#MessageList|MessageList]]** - вернет сообщения для конкретной темы (если в теме нет сообщений от пользователей или самого клиента то запрос будет пустой) по ее ID полученной с помощью команды **[[api:client_session#TitleMessages|TitleMessages]]**. | ||
+ | GET //himinfo.ru/cl/{Path}/api/?MessageList={"id": "10045"}&SessionID=... | ||
+ | |||
+ | Ответ **json**: | ||
+ | |||
+ | <sxh json> | ||
+ | { | ||
+ | "error": 0, | ||
+ | "childNode_comments": [ | ||
+ | { | ||
+ | "dttm": "16.03.2015+21:09:31", | ||
+ | "comment": "test", | ||
+ | "user": "0", | ||
+ | "status_message": 1 | ||
+ | } | ||
+ | ] | ||
+ | } | ||
+ | </sxh> | ||
+ | |||
+ | 3) **[[api:client_session#SendMessage|SendMessage]]** - добавит сообщение в существующую тему по ее ID полученной с помощью команды **[[api:client_session#TitleMessages|TitleMessages]]**, либо без ID создаст новую тему.\\ | ||
+ | |||
+ | Отправка сообщения в существующее обсуждение: | ||
+ | GET //himinfo.ru/cl/{Path}/api/?SendMessage={"id": "10045", "dttm": "25.03.2015 12:52", "mes_type": "3", "comment": "%D1%82%D0%B5%D1%81%D1%82"}&SessionID=... | ||
+ | |||
+ | Создание нового обсуждения на примере отзыва о заказе | ||
+ | GET //himinfo.ru/cl/{Path}/api/?SendMessage={"dor_id": "102577", "dttm": "25.03.2015 12:52", "mes_type": "1", "star": "5", "comment": "%D1%82%D0%B5%D1%81%D1%82"}&SessionID=... | ||
+ | |||
+ | 4) **[[api:client_session#CountNewMessages|CountNewMessages]]** - кол-во новых сообщения в теме по ее ID полученной с помощью команды **[[api:client_session#TitleMessages|TitleMessages]]** либо без ID создаст новую тему. | ||
+ | GET //www.himinfo.ru/cl/{Path}/api/?CountNewMessages={"id": "10045"}&SessionID=... | ||
+ | |||
+ | Ответ **json**: | ||
+ | |||
+ | <sxh json> | ||
+ | { | ||
+ | "error": 0, | ||
+ | "count_new": "3" | ||
+ | } | ||
+ | </sxh> | ||
+ | ---- | ||
+ | ===== Работа с выездами ===== | ||
+ | Получение списка журнала выездов используется команда **[[api:double_session#Trips|Trips]]**. | ||
+ | |||
+ | Для резервирование или редактирования времени выезда используется команда **[[api:double_session:TripOrder|TripOrder]]**. | ||
+ | |||
+ | При резервировании выезда, для указания корректного времени начала и окончания выезда, выполняется команда **[[api:client_session#TripsHr|TripsHr]]** (возвращает список свободного времени начала выезда, на которое можно зарезервировать время), далее выполнятся команда **[[api:client_session#TripsHrTo|TripsHrTo]]** с указанием предполагаемой даты окончания выезда (вернет список времени окончания, на которое можно завершить выезд). | ||
+ | |||
+ | После резервирования выезда, команда **[[api:double_session#Trips|Trips]]** вернет обновленный список выездов. | ||
+ | ---- | ||
+ | ===== Работа со статистикой ЛК ===== | ||
+ | |||
+ | Для работы отчета "Отчёт обращений в "Личный кабинет" клиентами. | ||
+ | |||
+ | Используемые команды:\\ | ||
+ | __[[api:client_session#Entry|Entry]]__ - статистика входа в ЛК (0 - зарегестрировался, 1 - авторизовался);\\ | ||
+ | __[[api:client_session#EntranceSite|EntranceSite]]__ - статистика заходов в ЛК;\\ | ||
+ | __[[api:client_session#OpenOrders|OpenOrders]]__ - статистика открытия заказа в ЛК;\\ | ||
+ | __[[api:client_session#OpenHistory|OpenHistory]]__ - статистика открытия истории в ЛК. | ||
+ | ---- |