Общие принципы работы с WebConsult API

Что такое WebConsult API?

WebConsult API дает возможность разработчикам взаимодействовать с нашей системой при помощи внешних программных средств. Это означает, что вы сможете получать и записывать данные в различные модули WebConsult напрямую из собственных скриптов и программ, используя общедоступные методы.

Доступ к WebConsult API осуществляется по протоколу HTTP и представляет собой набор GET и POST методов для работы с нашей системой. Каждый запрос сопровождается уникальной подписью, генерируемой при помощи приватного ключа. Ответ от сервера возвращается в формате JSON.

Ограничения

В данный момент наше API ограничено лишь количеством запросов в минуту и не может превышать 10 штук. Данное значение можно увеличить по индивидуальной договоренности с сервисом WebConsult.

Получение приватного ключа

Для начала работы с API вам нужно получить приватный ключ. Для этого необходимо войти под логином администратора, перейти в панель управления, выбрать раздел «Настройки», пункт «Настройки API» и нажать кнопку «Сгенерировать». В целях безопасности ключ отображается вам всего один раз – далее вы увидите его только частично. Если вы утратили ключ, то восстановить его будет невозможно, но вы сможете сгенерировать новый ключ (старый ключ при этом утратит своё действие).

Генерация подписи

Для повышения безопасности вашего API мы требуем подтверждения каждого запроса с помощью подписи, которая генерируется следующим образом:

  1. Объединяем значения всех передаваемых GET параметров в одну строку ($paramstring) без пробелов и других разделителей.
  2. Далее, для получения уникальной подписи, шифруем с помощью алгоритма MD5 строку “$paramstring<приватный ключ>”.
  3. Помимо основных GET параметров, передаем еще один GET параметр “sign” с подписью, сгенерированной в пункте 2.

Ниже приведен пример генерации подписи, написанный на языке PHP, на примере функции экспорта диалогов:

// Задаем параметры
$uid = <uid>;
$apikey = "<ваш приватный ключ>";
$baseurl = 'http://consultsystems.ru/api/';
$func = 'stats/export/';
$params = array(
    "uid" => $uid,
    "from" => 1386820800,
    "to" => 1386907199,
    "escapechars" => 0
);

// Генерируем подпись
$paramsString = '';
foreach($params as $k=>$v) $paramsString .= $v;
$params['sign'] = md5($paramsString.$apikey);

// Формируем строку запроса
$str = http_build_query($params);
$fullurl = $baseurl.$func.'?'.$str;

// Выполняем запрос с помощью CURL
$opts = array(
    CURLOPT_URL => $fullurl,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HEADER => false
);


$ch = curl_init();
curl_setopt_array($ch, $opts);
$return = curl_exec($ch);
$http_status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $return; // выводим ответ от сервера