Форумы COMTUBE

Обращение к API происходит по протоколу HTTP(S) (методы POST или GET) по адресу:

Код: Выделить всё

http://api.comtube.com/scripts/api/callback.php

В дополнение к адресу необходимо передавать следующие параметры:

• action - Действие. Возможны следующие варианты:
  
  
  • call – заказать callback-вызов,
  • terminate – отменить callback-вызов (как еще не состоявшийся, так и текущий),
  • state – проверить состояние callback-вызова,
  • statistics – получить статистику по состоявшимся callback-вызовам,
• uid - идентификатор вызова. Используется при проверке статуса, остановке, получении статистики
  
• number1 - номер телефона инициатора callback-вызова (то есть номер того, куда вызов придет первым)
  
• number2 - номер телефона вызываемой стороны
  
• when - Указывает дату/время начала отправки callback-вызова. Формат параметра следующий: YYYY-MM-DD HH:MM:SS. Пример: 2012–12–31 12:00:00. Если параметр не указан, то вызов создается сразу. Для action = send
  
• attempts - Указывает количество попыток установить соединение с номером number1. По умолчанию равен 1, диапазон: от 1 до 10. Для action = send
  
• timeshift - Время в секундах, через которое необходимо начать вызов. Диапазон от 0 до 1800 сек, по умолчанию 0.
  
• maxdur - Максимальная длительность разговора в секундах. Разрешенный диапазон от 0 до 7200 сек, по умолчанию 0. По некоторым направлениям длительность может быть меньше, из-за ограничения операторов связи.
  
• useivr - Указывает, надо ли проигрывать меню в случае, если вызываемый номер занят/не ответил: 1 - да (по умолчанию), 0 - нет (в этом случае при занятости вызываемой стороны вызов на стороне number1 завершится).
  
• who - Для action = statistics указывает номер телефона, для которого нужно получить статистику. В поиске участвуют оба номера телефона.
  
• fromdttm - Для action = statistics указывает дату и время, после которой необходимо получить статистику
  
• untildttm - Для action = statistics указывает дату и время, до которой необходимо получить статистику
  
• incl - Для action = getsmses указывает включать или нет дату и время для параметров fromdttm и untildttm (то есть, использовать “<"/">" или "<="/">=")
  
• count - Для action = statistics указывает количество записей статистики, которые нужно получить
  
• username – логин пользователя. Обязательный параметр.
  
• type – тип возвращаемого результата: xml (по умолчанию), html, csv, json. Необязательный параметр.
  
• signature – подпись запроса. Обязательный параметр. Как создать подпись смотрите раздел "Создание подписи (signature)"
  
  Обработка результата запроса
  
  После обработки запроса API вернет согласно запрашиваемому действию те или иные данные. Ниже приведен пример ответа при заказе соединения (просьба не использовать у себе параметры tariff1 и tariff2, так как для запроса стоимости есть отдельное API, а указанные параметры могут быть удалены и API по callback-вызову):
  
  

  Код: Выделить всё

  <?xml version="1.0" encoding="utf-8"?>
<result>
<uid>97d528a3-2033-40ae-9d41-013beff4200</uid>
<tariff1>0.3900</tariff1>
<tariff2>1.4400</tariff2>
<code>200</code>
<desc>OK</desc>
</result>

  
  
  При запросе статистики ответ будет таким:
  
  

  Код: Выделить всё

  <?xml version="1.0" encoding="utf-8"?>
<result>
<callbacks>
<callback>
<username>ct_rocks2</username>
<id>19875388</id>
<uid>b326e178-e065-403d-b518-544f68f3265f</uid>
<exec_time>2012-09-04 14:49:24</exec_time>
<number1>74951234567</number1>
<number2>79264567891</number2>
<side1>1</side1>
<side2>1</side2>
<total_duration>120</total_duration>
<total_price>1.83</total_price>
<crcy>RUB</crcy>
<crcy_nm>руб</crcy_nm>
</callback>
</callbacks>
<code>200</code>
<desc>OK</desc>
</result>

  
  
  Рекомендуем параметр id не использовать, так как он скоро прекратит свое существование.
  
  Здесь параметры side1 и side2 означают, была ли поднята трубку на номерах number1 и number2 соответственно.
  
  Параметры total_duration и total_price - это общая длительность, то есть сумма длительностей по каждой стороне вызова, и общая стоимость, то есть сумма стоимостей для каждой стороны вызова.
  
  Если необходимо запросить детальную статистику по какому-то вызову, то при запросе нужно указать uid вызова. В этом случае ответ будет следующим:
  
  

  Код: Выделить всё

  <?xml version="1.0" encoding="utf-8"?>
<result>
<callbacks>
<callback>
<side>1</side>
<call>SUCCEEDED</call>
<call_time>2012-09-04 10:49:27</call_time>
<dnis>74951234567</dnis>
<ani>74959568850</ani>
<price>0.39000</price>
<tariff>0.3900</tariff>
<duration>60</duration>
<crcy>RUB</crcy>
<crcy_nm>руб</crcy_nm>
<tplan_name>Старт</tplan_name>
<cause>9</cause>
<cause_desc>Завершение вызова на вызываемой стороне</cause_desc>
</callback>
<callback>
<side>2</side>
<call>SUCCEEDED</call>
<call_time>2012-09-04 10:49:37</call_time>
<dnis>79264567891</dnis>
<ani>74959568850</ani>
<price>1.44000</price>
<tariff>1.44000</tariff>
<duration>60</duration>
<crcy>RUB</crcy>
<crcy_nm>руб</crcy_nm>
<tplan_name>Старт</tplan_name>
<cause>9</cause>
<cause_desc>Завершение вызова на вызываемой стороне</cause_desc>
</callback>
</callbacks>
<code>200</code>
<desc>OK</desc>
</result>

  
  
  Здесь параметр side - указывает на сторону: 1 - сторона с number1, 2 - сторона с number2.
  
  Поле code указывает код выполнения операции:
  
  
  • 200 – OK – Операция прошла успешно. В случаях, когда запрашивается статистика в формате csv, html и операция прошла успешно, код ошибки не возвращается.
  • 204 – No Content – возвращается в случаях, когда запрашиваемая информация не найдена. Например, если при запросе статистики по указанному фильтру ничего не найдено, то вернется именно этот код
  • 400 – Bad Request – указывает, что один или несколько параметров указаны не верно или отсутствуют. В поле desc, как правило, возвращается название параметра, который указан не правильно
  • 401 – Authorization Failed – Неправильно указан логин/пароль или неправильно сформирована подпись signature
  • 402 – Not enough money OR Payment required – Указывает, что для совершения операции недостаточно денег. Требуется пополнить счет
  • 403 – Account Blocked OR User Blocked – Указывает, что учетная запись пользователя заблокирована по тем или иным причинам
  • 409 - Conflict - Указывает, что вызов между номерами number1 и number2 уже активен.
  • 500 – Internal Server Error – Возникла внутренняя ошибка.
  • 501 – Not Implemented – Указывает, что запрашиваемая функциональность еще не реализована.
  • 503 – Service Unavailable – Указывает, что не удалось подключится к серверу приложения для выполнения операции. Однако операция может быть выполнена чуть позже.

Обновлено: 05 Сентября 2012

Внимание: Старое API больше не поддерживается, однако будет продолжать работать еще некоторое время. Поэтому прошу не сильно медлить при переходе на новое API.

Это API больше не поддерживается и до нового года (2013) перестанет работать. Для получения статистики см. описание API callback - предыдущий пост.

Отправка запроса на получение статистики

Для получения статистики необходимо отправить HTTP запрос по адресу:

Код: Выделить всё

http://api.comtube.ru/scripts/webphone_api/stat.php

В дополнение к адресу необходимо передавать следующие параметры:

• username - логин пользователя (обязательный параметр)
• cbk_id - Идентификатор вызова (опционально, по умолчанию =0)
• date - Дата, за которую необходимо получить статистику (опционально, формат ГГГГ-ММ-ДД)
• month - Месяц, за который необходимо получить статистику (опционально, используется только совместно с year)
• year - Год, за который необходимо получить статистику (опционально, используется только совместно с month)
• type - В каком виде вернуть результат: xml or csv (по умолчанию: csv)
• signature - подпись запроса (обязательный параметр). Как создать подпись смотрите раздел "Создание подписи (signature)".

При этом необходимо учитывать приоритет: cbk_id, date, month и year. То есть, если указаны все параметры, то статистика будет возвращаться только по параметру cbk_id. Если его нет, то по date, и так далее.
Обратите внимание, что параметры month и year используются вместе и по отдельности не работают.

Если возникла ошибка при формировании ответа, то ее описание будет возвращено вместо данных. Ниже приводится список ошибок:

• 400 - один из параметров указан неверно
• 401 - не указан логин пользователя
• 403 - учетная запись заблокирована
• 404 - ошибка авторизации. Неправильно сформирована подпись
• 500 - внутренняя ошибка

Пример отправки запроса и обработки ответа

Ниже приведен пример на языке программирования PHP для работы с данным API.

Код: Выделить всё

<?
include_once('common/signature.inc');

$baseurl = "http://api.comtube.ru/scripts/webphone_api/stat.php";

// Создаем массив и заполняем его параметрами
$params = array();
$params["username"] = "mylogin";
$params["month"] = "10";
$params["year"] = "2010";
$params["type"] = "csv";
//$params["cbk_id"] = 505199;

// Создаем подпись к параметрам
$urlparams = BuildUrlParamsWithSignature($params, "mypassword");

// Формируем полный URL для обращения к серверу
$url = $baseurl . "?" . $urlparams;

// Инициализируем curl и отправляем запрос
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$data = curl_exec($ch);
curl_close($ch);

// Анализируем результат
$matches = array();
preg_match("/([0-9]+);([^;]+);<br\/>/", $data, $matches);

if (count($matches) > 0)
{
  $code = $matches[1];
  $desc = $matches[2];
  echo "code: " . $code . ", desc: " . $desc;
}
else
{
  // Получен неправильный ответ от сервера
  echo $data;
}

?>



Изменено описание API для совершения обратного звонка (Веб-телефон). API теперь возвращает тарифы по каждому номеру. Появилась поддержка параметра maxdur. Так же добавились новые значения ошибок.

Хотелось бы иметь API для получения тарифов до заказа звонка, поскольку получение тарифов после того, как звонок уже заказан, в купе с тем, что отменить его программно нельзя не позволяет предотвратить звонок по нежелательному тарифу (хотя уже и появление этой возможности радует), равно как и определить возможную длительность звонка (maxdur). Впрочем, возможно, я чего-то не понимаю, и можно, например, заказать звонок с отрицательной длительностью и в ответ получить просто тарифы, без размещения заказа на звонок?

Ну и разумеется, очень нужна возможность обратного вызова Вашей системой какой-то страницы системы клиента с сообщением туда результатов заказа звонка, когда тот состоялся. Хочется надеяться на появление такой возможности в ближайшее время.

Вопрос создания данного API (стоимость вызова) прорабатывается. Скорее всего, будет API, позволяющее узнать цену на конкретное направление, и, соответственно, в случае веб-телефона нужно будет дважды обратиться к API.

Что касается поддержки обратной связи по факту завершения вызова, то данная возможность будет реализована со временем. Надеемся, что к лету она появится. Что касается API для получения тарифов, то оно скоро будет опубликовано.

Что сегодня с API? если просто открыть http://api.comtube.ru/scripts/webphone_api/stat.php то работает, если запустить скриптом получение статистики то тормозит и ничего не получает, то же с callback

Странно, проверили, все работает. Скрипт и браузер работают под единым внешним IP? Можете указать время. когда запрос не обработался?

sd писал(а):Странно, проверили, все работает. Скрипт и браузер работают под единым внешним IP? Можете указать время. когда запрос не обработался?

сервер на котором скрипт и мой броузер конечно на разных ip, но раньше всё было ок. часа 2 не работало. это было в то время когда я написал в форум об этом.
сейчас проверил - всё шустро обрабатывает, и надеюсь больше такого не будет а то непрятно как-то(

grey писал(а):

sd писал(а):Странно, проверили, все работает. Скрипт и браузер работают под единым внешним IP? Можете указать время. когда запрос не обработался?

сервер на котором скрипт и мой броузер конечно на разных ip, но раньше всё было ок. часа 2 не работало. это было в то время когда я написал в форум об этом.
сейчас проверил - всё шустро обрабатывает, и надеюсь больше такого не будет а то непрятно как-то(

А сколько запросов у вас выполняется в подряд? У нас просто есть ограничение на количество запросов в единицу времени.