Документация по API

Описание API
Виды команд API
Формат команд
Примеры интеграции
Коды ошибок API
Авторизация
Получение изменившихся заказов и клиентов
Пример работы с обсуждениями
Работа с выездами
Работа со статистикой ЛК

Виды команд:

• Команды API без сессии - команды получения общих данных из стандартных справочников, для выполнения которых Не требуется сессия.
  
• Команды API ТОЛЬКО с клиентской сессией - команды получения данных по конкретному клиенту, для выполнения которых Требуется клиентская сессия.
  
• Команды API ТОЛЬКО с пользовательской сессией - команды получения данных, для выполнения которых Требуется пользовательская сессия.
  
• Команды API с пользовательской или клиентской сессией - команды получения данных, для выполнения которых Требуется клиентская или пользовательская сессия.
  
• Коммерческие команды API с пользовательской сессией - команды сохранения/редактирования клиентов, заказов, оплаты и т.п., для выполнения которых Требуется пользовательская сессия.

API позволяет реализовать Личный кабинет клиента, используя клиентскую сессию (авторизованного пользователя SessionID), получая информацию только по этому клиенту.
На основе полученной сессии, команды возвращают информацию Только по одному текущем клиенту.
Время «жизни» клиентской сессии неограниченно.

API позволяет реализовать создание и редактирование заказов, добавление оплаты в заказ, создание и изменение клиентов, получение изменившихся заказов и клиентов и др. через коммерческие команды, используя пользовательскую сессию (авторизованного пользователя SessionID).

Для реализации таких целей, правильно использовать API c пользовательской сессией.
Для этого есть команды загрузки Изменившихся заказов за период (с выводом подробной информации по заказу), изменившихся клиентов, создание и изменение заказов.

1. Команды API без сессии
2. Команды API ТОЛЬКО с клиентской сессией
3. Команды API ТОЛЬКО с пользовательской сессией
4. Команды API с клиентской или пользовательской сессией
5. Коммерческие команды API с пользовательской сессией

Все команды выполняются методом 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:

$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;

Пример запросов на 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);

Пример запросов на jQuery:

Функция encodeURIComponent выполняется для всех значений параметров команды:

'//himinfo.ru/cl/{Path}/api/?command=' + encodeURIComponent('{"param1": "' + param1.val() + '", "param2": "' + param2.val() + '", "param3": "' + param3.val()+ '"}'),

1) в данном случае метод $.ajax сам выполнит encodeURL:

$.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
});

2)

  $.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
  });

¹ - обратиться к разработчикам Агбис.

Для регистрации используется команда ModernRegistration.

Для авторизации (получения клиентской сессии) используется команда ModernLogin и AuthByAddon.

Для восстановления пароля команда ModernRememberPwd.

Для авторизации (получения пользовательской сессии) используется команда Login.

Для обновления сессии используется команда RefreshSession.

Для получения списка изменившихся заказов, правильнее воспользоваться командами - OrderByDateTimeForAll, LastChangeOrder.

Для получения списка изменившихся клиентов, использовать команду ClientsByDateTimeForAll.

В модуле Агбис.Химчистка сообщение отображается в Сервис - Общение с Клиентами в «Журнал Оперативного общения с клиентами» или в «Сообщения из ЛК»

1) TitleMessages - получить список обсуждений происходит по сессии, т.е. только конкретно для  авторизованного клиента. вернет:

GET //himinfo.ru/cl/{Path}/api/?TitleMessages&SessionID=...

Ответ 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"
    }
  ]
}

2) MessageList - вернет сообщения для конкретной темы (если в теме нет сообщений от пользователей или самого клиента то запрос будет пустой) по ее ID полученной с помощью команды TitleMessages.

GET //himinfo.ru/cl/{Path}/api/?MessageList={"id": "10045"}&SessionID=...

Ответ json:

{
  "error": 0, 
  "childNode_comments": [
    {
      "dttm": "16.03.2015+21:09:31", 
      "comment": "test", 
      "user": "0", 
      "status_message": 1
    }
  ]
}

3) SendMessage - добавит сообщение в существующую тему по ее ID полученной с помощью команды 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) CountNewMessages - кол-во новых сообщения в теме по ее ID полученной с помощью команды TitleMessages либо без ID  создаст новую тему.

GET //www.himinfo.ru/cl/{Path}/api/?CountNewMessages={"id": "10045"}&SessionID=...

Ответ json:

{
  "error": 0, 
  "count_new": "3"
}

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

Для резервирование или редактирования времени выезда используется команда TripOrder.

При резервировании выезда, для указания корректного времени начала и окончания выезда, выполняется команда TripsHr (возвращает список свободного времени начала выезда, на которое можно зарезервировать время), далее выполнятся команда TripsHrTo с указанием предполагаемой даты окончания выезда (вернет список времени окончания, на которое можно завершить выезд).

После резервирования выезда, команда Trips вернет обновленный список выездов.

Для работы отчета «Отчёт обращений в «Личный кабинет» клиентами.

Используемые команды:
Entry - статистика входа в ЛК (0 - зарегестрировался, 1 - авторизовался);
EntranceSite - статистика заходов в ЛК;
OpenOrders - статистика открытия заказа в ЛК;
OpenHistory - статистика открытия истории в ЛК.