Различия

Здесь показаны различия между двумя версиями данной страницы.

--- api [25.04.2024 07:38]
Anatoly
+++ api [16.05.2024 12:58]
Anatoly [Работа с выездами]
@@ Строка 1: / Строка 1: @@
 ====== Документация по API ======
+----
+===== Оглавление =====
+[[#Описание API|Описание API]]\\
+[[#Виды команд API|Виды команд API]]\\
+[[#Формат команд|Формат команд]]\\
+[[#Примеры интеграции|Примеры интеграции]]\\
+[[#Коды ошибок API|Коды ошибок API]]\\
+[[#Авторизация|Авторизация]]\\
+[[#Получение изменившихся заказов и клиентов]]\\
+[[#Пример работы с обсуждениями|Пример работы с обсуждениями]]\\
+[[#Работа с выездами|Работа с выездами]]\\
+[[#Работа со статистикой ЛК|Работа со статистикой ЛК]]\\
+----
 ===== Описание API =====
-%%API%% позволяет реализовать Личный кабинет клиента, используя клиентскую сессию(авторизованного пользователя SessionID), получая информацию только по этому клиенту.\\
+%%API%% позволяет реализовать Личный кабинет клиента, используя __клиентскую сессию__ (авторизованного пользователя SessionID), получая информацию только по этому клиенту.\\
 На основе полученной сессии, команды возвращают информацию **Только по одному текущем клиенту**.\\
 **Время "жизни" клиентской сессии неограниченно.**\\
-%%API%% позволяет реализовать создание и редактирование заказов, добавление оплаты в заказ, создание и изменение клиентов, получение изменившихся заказов и клиентов и др. через коммерческие команды, используя пользовательскую сессию (авторизованного пользователя SessionID).
+%%API%% позволяет реализовать создание и редактирование заказов, добавление оплаты в заказ, создание и изменение клиентов, получение изменившихся заказов и клиентов и др. через __коммерческие команды__, используя __пользовательскую сессию__ (авторизованного пользователя SessionID).
 <WRAP important round>API с клиентской сессией **Не позволяет реализовать синхронизацию всех заказов/клиентов и др. со сторонними сервисами**.\\
 Т.к. это может привести к избыточной нагрузке и большому количеству запросов.</WRAP>
-Для реализации таких целей, правильно использовать API c пользовательской сессией.\\
+Для реализации таких целей, правильно использовать %%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 =====
@@ Строка 27: / Строка 46: @@
 ----
 ===== Формат команд =====
-Все значения параметров команд должны быть преобразованы, **через js encodeURIComponent, через php urlencode или подобные функции**.
+Все команды выполняются методом **GET** или **POST**. Ответ на запрос приходит в **json** формате.
+Все значения параметров команд должны быть преобразованы, __через js encodeURIComponent, через php urlencode или подобные функции__.
 **Пример:**
-<code>//himinfo.ru/cl/{Path}/api/?command={"key":"value"}&SessionID=...&callback=...</code>
+  GET /himinfo.ru/cl/{Path}/api/?command={"key":"value"}&SessionID=...&callback=...
 **Преобразованный пример:**
-<code>//himinfo.ru/cl/{Path}/api/?command=%7B%22key%22%3A%22value%22%7D&SessionID=...&callback=...</code>
+  GET /himinfo.ru/cl/{Path}/api/?command=%7B%22key%22%3A%22value%22%7D&SessionID=...&callback=...
 где:\\
@@ Строка 42: / Строка 64: @@
 //**В ответе на запрос могут присутствовать поля, не описанные в настоящей документации. Приложению следует их игнорировать.**//
+----
+===== Примеры интеграции =====
+**Пример запросов на 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>
+) в данном случае метод $.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>
+)
+<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 =====
@@ Строка 58: / Строка 160: @@
 <sup>1</sup> - обратиться к разработчикам Агбис.
 ----
-===== Виды команд API =====
+===== Авторизация =====
- [[api_v2.0#no_session|1.1. Команды без сессии]]\\
- [[api_v2.0#client_session|1.2. Команды ТОЛЬКО с клиентской сессией]]\\
+Для регистрации используется команда **[[api:no_session#ModernRegistration|ModernRegistration]]**.
- [[api_v2.0#user_session|1.3. Команды ТОЛЬКО с пользовательской сессией]]\\
- [[api_v2.0#double_session|1.4. Команды с пользовательской или клиентской сессией]]\\
+Для авторизации используется команда **[[api:no_session#ModernLogin|ModernLogin]]**.
- [[api_v2.0#commercial_session|1.5. Коммерческие команды с пользовательской сессией]]\\
+Для восстановления пароля команда **[[api:no_session#ModernRememberPwd|ModernRememberPwd]]**.
 ----
-===== no_session =====
+===== Получение изменившихся заказов и клиентов =====
-==== 1.1. Команды без сессии ====
+Для получения списка изменившихся заказов, правильнее воспользоваться командами - **[[api:user_session#OrderByDateTimeForAll|OrderByDateTimeForAll]]**, **[[api:double_session#LastChangeOrder|LastChangeOrder]]**.
-[[#Версия API. api_version|Версия API. api_version]]\\
-[[#Авторизация. ModernLogin|Авторизация. ModernLogin]]\\
-[[#Регистрация. ModernRegistration|Регистрация. ModernRegistration]]\\
-[[#Восстановление пароля. ModernRememberPwd|Восстановление пароля. ModernRememberPwd]]\\
-[[#Выход из Личного кабинета. Logout|Выход из Личного кабинета. Logout]]\\
-[[#Проверка валидности сессии. ValidSessionID|Проверка валидности сессии. ValidSessionID]]\\
+Для получения списка изменившихся клиентов, использовать команду **[[api:user_session#ClientsByDateTimeForAll|ClientsByDateTimeForAll]]**.
+----
+===== Пример работы с обсуждениями =====
+__В модуле Агбис.Химчистка сообщение отображается в Сервис - Общение с Клиентами в "Журнал Оперативного общения с клиентами" или в "Сообщения из ЛК"__
+) **[[api:client_session#TitleMessages|TitleMessages]]** - получить список обсуждений происходит по сессии, т.е. только конкретно для  авторизованного клиента. вернет:
+  GET //himinfo.ru/cl/{Path}/api/?TitleMessages&SessionID=...
-[[#Дополнительные реквизиты. AddonTypes|Дополнительные реквизиты. AddonTypes]]\\
+Ответ **json**:
-[[#Комплекты доп. реквизитов. AddonPacks|Комплекты доп. реквизитов. AddonPacks]]\\
-[[#Прайс-лист. PriceList|Прайс-лист. PriceList]]\\
-[[#Группы прайс-листа. PriceTree|Группы прайс-листа. PriceTree]]\\
-[[#Склады. ReceptionCenters|Склады. ReceptionCenters]]\\
-[[#Регионы (районы). Regions|Регионы (районы). Regions]]\\
-[[#Список выездов. Trips|Список выездов. Trips]]\\
-[[#Информация по выезду. Trip|Информация по выезду. Trip]]\\
-[[#Свободное время начала выезда на дату. TripsHr|Свободное время начала выезда на дату. TripsHr]]\\
-[[#Свободное время окончания выезда на дату. TripsHrTo|Свободное время окончания выезда на дату. TripsHrTo]]\\
-[[#Список выездных машин. Cars|Список выездных машин. Cars]]\\
-[[#Создание выезда. TripOrder|Создание выезда. TripOrder]]\\
-[[#Промо-код. PromoCode|Промо-код. PromoCode]]\\
-[[#Используемый промо-код. PromoCodeUse|Используемый промо-код. PromoCodeUse]]\\
-[[#Активация промо-кода. PromoCodeActivate|Активация промо-кода. PromoCodeActivate]]\\
-[[#Список изменившихся ID заказов. LastChangeOrder|Список изменившихся ID заказов. LastChangeOrder]]\\
-[[#Подтверждение заказа. OrderConfirm|Подтверждение заказа. OrderConfirm]]\\
-[[#Подтверждение заказа. OrderAppConfirm|Подтверждение заказа. OrderAppConfirm]]\\
-[[#Отмена подтверждения заказа. CancelOrderApp|Отмена подтверждения заказа. CancelOrderApp]]\\
-[[#Статус заказа. GetStatusOrder|Статус заказа. GetStatusOrder]]\\
-[[#Отмена заказа. CancelOrder|Отмена заказа. CancelOrder]]\\
-[[#Темы обсуждений клиента. TitleMessages|Темы обсуждений клиента. TitleMessages]]\\
-[[#Список сообщений темы. MessageList|Список сообщений темы. MessageList]]\\
-[[#Количество новых сообщений в теме. CountNewMessages|Количество новых сообщений в теме. CountNewMessages]]\\
-[[#Отправка сообщения темы. SendMessage|Отправка сообщения темы. SendMessage]]\\
-[[#Список акций. GetActionList|Список акций. GetActionList]]\\
-[[#Список сертификатов. Certificate|Список сертификатов. Certificate]]\\
-[[#Список строк сертификатов. CertificateLines|Список строк сертификатов. CertificateLines]]\\
-[[#Список активных сертификатов. ActiveCertificates|Список активных сертификатов. ActiveCertificates]]\\
-[[#Создание оплаты сертификата. CreatePayCertificate|Создание оплаты сертификата. CreatePayCertificate]]\\
-[[#Рекламные объявления. Advertisment|Рекламные объявления. Advertisment]]\\
-[[#Картинки рекламных объявлений. AdvertismentImg|Картинки рекламных объявлений. AdvertismentImg]]\\
-----
-===== client_session =====
-=== 1.2. Команды ТОЛЬКО с клиентской сессией ===
-[[#Информация по клиенту. ContrInfo|Информация по клиенту. ContrInfo]]\\
-[[#Сохранение информации по клиенту. SaveInfo|Сохранение информации по клиенту. SaveInfo]]\\
-[[#Сохранение пароля. SavePass|Сохранение пароля. SavePass]]\\
-[[#Подтверждение номера телефона. ConfirmCellPhone|Подтверждение номера телефона. ConfirmCellPhone]]\\
-[[#Остаток бонусов клиента. Bonus|Остаток бонусов клиента. Bonus]]\\
-[[#Остаток депозита клиента. Deposit|Остаток депозита клиента. Deposit]]\\
-[[#Список заказов клиента. Orders|Список заказов клиента. Orders]]\\
-[[#История заказов клиента. OrdersHistory|История заказов клиента. OrdersHistory]]\\
-[[#Полная информация по заказу. FullOrderInfo|Полная информация по заказу. FullOrderInfo]]\\
-[[#Краткая информация по услугам заказа. Services|Краткая информация по услугам заказа. Services]]\\
-[[#Полная информация по услугам заказа. FullService|Полная информация по услугам заказа. FullService]]\\
-[[#Квитанция. ReceiptOnline|Квитанция. ReceiptOnline]]\\
-[[#Квитанция. Receipt|Квитанция. Receipt]]\\
-[[#Подписанная квитанция. SingReceipt|Подписанная квитанция. SingReceipt]]\\
-[[#Список фотографий по заказу. OrderImagesModern|Список фотографий по заказу. OrderImagesModern]]\\
-[[#Фотографии по заказу. PhotoOnline|Фотографии по заказу. PhotoOnline]]\\
-[[#Оплата депозитом. DepositPay|Оплата депозитом. DepositPay]]\\
-[[#Оплата бонусом. BonusPay|Оплата бонусом. BonusPay]]\\
-[[#Статистика входа в ЛК. Entry|Статистика входа в ЛК. Entry]]\\
-[[#Статистика заходов в ЛК. EntranceSite|Статистика заходов в ЛК. EntranceSite]]\\
-[[#Статистика открытия заказа в ЛК. OpenOrders|Статистика открытия заказа в ЛК. OpenOrders]]\\
-[[#Статистика открытия истории в ЛК. OpenHistory|Статистика открытия истории в ЛК. OpenHistory]]\\
+<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>
+) **[[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>
+) **[[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=...
+) **[[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]]__ - статистика открытия истории в ЛК.
+----

Инструменты

меню и быстрый поиск

быстрый поиск

статус сайта

«хлебные крошки»

Инструменты страницы

мета-данные страницы

Различия