- Код: Выделить всё
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.
