Различия

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

--- api [26.03.2024 06:03]
+++ api [17.05.2024 05:47] (текущий)
Anatoly [Описание API]
@@ Строка 1: / Строка 1: @@
+====== Документация по API ======
+----
+===== Оглавление =====
+[[#Описание API|Описание API]]\\
+[[#Виды команд API|Виды команд API]]\\
+[[#Формат команд|Формат команд]]\\
+[[#Примеры интеграции|Примеры интеграции]]\\
+[[#Коды ошибок API|Коды ошибок API]]\\
+[[#Авторизация|Авторизация]]\\
+[[#Получение изменившихся заказов и клиентов]]\\
+[[#Пример работы с обсуждениями|Пример работы с обсуждениями]]\\
+[[#Работа с выездами|Работа с выездами]]\\
+[[#Работа со статистикой ЛК|Работа со статистикой ЛК]]\\
+----
+===== Описание API =====
+Виды команд:\\
+  * //__Команды %%API%% без сессии__// - команды получения общих данных из стандартных справочников, **для выполнения которых Не требуется сессия**.\\
+  * //__Команды %%API%% ТОЛЬКО с клиентской сессией__// - команды получения данных по конкретному клиенту, **для выполнения которых Требуется клиентская сессия**.\\
+  * //__Команды %%API%% ТОЛЬКО с пользовательской сессией__// - команды получения данных, **для выполнения которых Требуется пользовательская сессия**.\\
+  * //__Команды %%API%% с пользовательской или клиентской сессией__// - команды получения данных, **для выполнения которых Требуется клиентская или пользовательская сессия**.\\
+  * //__Коммерческие команды %%API%% с пользовательской сессией__// - команды сохранения/редактирования клиентов, заказов, оплаты и т.п., **для выполнения которых Требуется пользовательская сессия**.
+%%API%% позволяет реализовать Личный кабинет клиента, используя __клиентскую сессию__ (авторизованного пользователя SessionID), получая информацию только по этому клиенту.\\
+На основе полученной сессии, команды возвращают информацию **Только по одному текущем клиенту**.\\
+**Время "жизни" клиентской сессии неограниченно.**\\
+%%API%% позволяет реализовать создание и редактирование заказов, добавление оплаты в заказ, создание и изменение клиентов, получение изменившихся заказов и клиентов и др. через __коммерческие команды__, используя __пользовательскую сессию__ (авторизованного пользователя SessionID).
+<WRAP important round>API с клиентской сессией **Не позволяет реализовать синхронизацию всех заказов/клиентов и др. со сторонними сервисами**.\\
+Т.к. это может привести к избыточной нагрузке и большому количеству запросов.</WRAP>
+Для реализации таких целей, правильно использовать %%API%% c __пользовательской сессией__.\\
+Для этого есть команды загрузки Изменившихся заказов за период (с выводом подробной информации по заказу), изменившихся клиентов, создание и изменение заказов.
+----
+===== Виды команд 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>
+) в данном случае метод $.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 =====
+|**Код ошибки**|**Текст ошибки**                                 |**Описание**                                                       |
+|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]]**.
+----
+===== Пример работы с обсуждениями =====
+__В модуле Агбис.Химчистка сообщение отображается в Сервис - Общение с Клиентами в "Журнал Оперативного общения с клиентами" или в "Сообщения из ЛК"__
+) **[[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>
+) **[[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:no_session#TripsHr|TripsHr]]** (возвращает список свободного времени начала выезда, на которое можно зарезервировать время), далее выполнятся команда **[[api:no_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]]__ - статистика открытия истории в ЛК.
+----

Инструменты

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

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

статус сайта

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

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

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

Различия