Протокол HTTP

Описание отсылки сообщений через протокол HTTP в системе «ISBC Telecom».

Скачать примеры на PHP

Для работы с классом требуется PHP5

Входные параметры

  • Адрес обращения : http://service.qtelecom.ru/public/http/ или https://service.qtelecom.ru/public/http/
  • Тип авторизации : PLAIN (открытым текстом)
  • Формат входных данных: Content-Type: application/x-www-form-urlencoded; charset=UTF-8 (по умолчанию)
  • При использовании другой кодировки, отличной от UTF-8, требуется указать её в заголовке Content-Type запроса.
  • Например: Content-Type: application/x-www-form-urlencoded; charset=windows-1251
  • Результат : Content-Type: text/xml (UTF-8); content-encoding: gzip
  • Login/password : совпадают с login/password на web-сайт http://go.qtelecom.ru
  • Максимальная длина сообщений : 480 символов.

1. Авторизация

Авторизация требуется при каждом подключении к серверу независимо от дальнейших действий.

  • user - Логин для входа в систему на сайте go.qtelecom.ru
  • pass - Пароль для входа в систему на сайте go.qtelecom.ru
  • gzip=none - Не использовать content-encoding: gzip
  • HTTP_ACCEPT_LANGUAGE - переменная клиента, предпочтение относительно языка (необязательный параметр)
  • CLIENTADR - IP адрес клиента (необязательный параметр)
  • comment - описание подключения (необязательный параметр; до 512 символов)

2. Отправка сообщения

SMS сообщение

Параметр Значение По умолчанию
action post_sms -
message текст сообщения -
sender имя отправителя, зарегистрированного для вас, в системе (NULL - имя отправителя по умолчанию) имя по умолчанию
post_id пользовательский ID рассылки, необязательный параметр, возвращается обратно в неизменном виде. -
period Время жизни сообщения в секундах. Необязательный параметр. Максимальное время, в течение которого сообщение должно быть доставлено на телефон. Если в течение этого времени доставка не возможна (например абонент не в зоне действия сети), сообщение не будет доставлено вовсе. Внимание, данная функция может не работает для некоторых направлений, например для CDMA телефонов. -
time_period Период отправки сообщения в формате «HH:mm-HH:mm(час:мин-час:мин)», в течение которого сообщение должно быть доставлено получателям (например 10:00-21:00). Опция позволяет запретить доставку сообщений, например, в ночное время. Для указанного периода времени можно уточнить часовой пояс в time_local 00:00-00:00
time_local Выбор часового пояса для опции time_period. 1 - по местному время получателя, 0 - по часовому поясу, выбранному в личном кабинете отправителя. 0
autotrimtext on - обрезать все пробелы и переводы строк в начале и конце сообщения. off
  • Варианты рассылки по адресатам:
    • target - адресаты. Список через запятую. (Н-р: »+70010001212, 80009990000»)
    • phl_codename - кодовое имя контакт-листа в системе go.qtelecom.ru
      • gender - фильтр по полу получателя. Значение: M / F (мужской / женский)
  • sms_type - Тип SMS (по умолчанию пустое значение):
    • Пустое значение: Простое SMS
    • W: Wap push сообщение
      • wap_url - HTTP ссылка с текста сообщения (http://......) только для sms_type = W.
      • wap_expires - Дата и время когда истекает срок доставки Wap push сообщения. (Формат: dd.mm.yyyy hh:ii:ss (дд.мм.гггг чч:ми:сс))
    • F: Flash SMS сообщение

3. Получение статусов сообщений асинхронно

Данный вариант позволяет получать статусы сообщений в реальном времени. Для настройки укажите в Личном кабинете → Услуги «URL скрипта для приёма статуса отправленных SMS». Как только система получает статус сообщения, она немедленно пересылает вам его по HTTPпротоколу с помощью POST запроса.

Формат данных:

  • ORDID ⇒ номер сообщения (номер соответствует значению атрибута ID тэга SMS, возвращаемого при отправке сообщения)
  • CNRID ⇒ ID контрагента
  • RESCOUNT ⇒ количество для тарификации
  • STATUS ⇒ код статуса (расшифровка кодов ниже)
  • FINALTIME ⇒ время получения финального статуса в UTC

Коды статуса:

  • 2 - сообщение доставлено
  • 3 - время попыток доставить сообщение оператором истекло
  • 5 - сообщение не может быть доставлено (ошибка в номере, номер не существует и т.д.)
  • 8 - сообщение не принято оператором
  • 20 - отправка была отменена пользователей
  • 21 - ошибка при работе по сообщению
  • 22 - оператор не сообщил о состоянии сообщения за отведенное время.

4. Получение данных и статусов сообщений

  • action = status

Три варианта получения статусов для сообщений:

  • sms_id = данные по одному сообщению.
  • sms_group_id = данные по всем сообщениям за одну отсылку.
  • date_from, date_to, smstype = данные по всем сообщениям за период времени от date_from до date_to по типу сообщений smstype. (Формат date_from, date_to: dd.mm.yyyy hh:ii:ss (дд.мм.гггг чч:ми:сс))

Возможные варианты:

  • queued - сообщение в очереди отправки
  • wait - передано оператору на отправку
  • accepted - сообщение принято оператором
  • delivered - сообщение доставлено
  • not_delivered - сообщение не доставлено
  • failed - ошибка при работе по сообщению

5. Получение текущего баланса

  • action = balance

6. Получение входящих сообщений

  • action = inbox
  • sib_num - Номер входящего ящика (Обязательный параметр, соответствует значению «ID ящика» в закладке «Настройки»)
  • new_only - Статус сообщений:
    • 1 - только новые, непрочитанные сообщения
    • 0 - все сообщения
  • date_from, date_to - Данные по всем сообщениям за период времени от date_from до date_to (Формат date_from, date_to: dd.mm.yyyy hh:ii:ss (дд.мм.гггг чч:ми:сс))

Примеры использования протокола

Пример 1. Отправка одного сообщения по адресатам

Запрос

POST= (
    [user] => userX
    [pass] => ***
    [action] => post_sms
    [message] => Привет
    [target] => +79999999991, +79999999992, +7999999999999
    [post_id] => x124127456
    [period] => 600
    [CLIENTADR] => 127.0.0.1
    [HTTP_ACCEPT_LANGUAGE] => ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3
)

Результат XML

<output>
     <result>
     <sms post_id="x124127456" id="99991" smstype="SENDSMS"  phone="+79999999991" sms_res_count="1"><![CDATA[Привет]]></sms>
     <sms post_id="x124127456" id="99992"  smstype="SENDSMS"  phone="+79999999992" sms_res_count="1"><![CDATA[Привет]]></sms>
     </result>
     <errors>
     <error code="-20117" post_id="x124127456">Неправильный номер телефона: +7999999999999</error>
     </errors>
</output>

Использование PHP-класса

<?php
 Include('QTSMS.class.php');
 // Отправка SMS сообщения по списку адресатов
 $sms_text='Привет';
 $target='+79990001212, 80009990000';
 $sender='vasya';
 $period=600;
 
 $sms= new QTSMS('userX.Y','пароль');
 $result=$sms->post_message($sms_text, $target, $sender, 'x124127456',$period);
 // результат XML
 echo $result;  
 // Отправка SMS по кодовому имени контакт листа
 $sms_text='Привет';
 $phl_codename='druzya';
 $result=$sms->post_message_phl($sms_text, $phl_codename, $sender, 'x124127456',$period);
 header("Content-Type: text/xml; charset=UTF-8");
 // результат XML
 echo $result; 
?>

Пример 2. Получение данных сообщения id=6666

Запрос

POST= (    
    [action] => status    
    [sms_id] => 6666    
    [user] => userX    
    [pass] => ***    
    [CLIENTADR] => 127.0.0.1    
    [HTTP_ACCEPT_LANGUAGE] => ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3
)

Результат XML

<output>
     <MESSAGES>
     <MESSAGE SMS_ID="6666" SMSTYPE="SENDSMS">
     <CREATED>24.12.07 15:57:45</CREATED> 
     <AUL_USERNAME>userX.Y</AUL_USERNAME> 
     <AUL_CLIENT_ADR>127.0.0.1</AUL_CLIENT_ADR> 
     <SMS_SENDER>SenderName</SMS_SENDER> 
     <SMS_TARGET>89999991111</SMS_TARGET> 
     <SMS_RES_COUNT>1</SMS_RES_COUNT> 
       <SMS_TEXT>
       <![CDATA[ Привет ]]> 
     </SMS_TEXT>
     <SMSSTC_CODE>wait</SMSSTC_CODE> 
     <SMS_STATUS>Сообщение в процессе доставки</SMS_STATUS> 
     <SMS_CLOSED>0</SMS_CLOSED> 
     <SMS_SENT>0</SMS_SENT> 
     </MESSAGE>
     </MESSAGES>
</output>

Использование PHP-класса

<?php
 // Получение статуса SMS сообщений
 Include('QTSMS.class.php');
 $sms= new QTSMS('userX.Y','пароль');
 // данные о сообщении SMS_ID=6666
 $r_xml1=$sms->status_sms_id(6666);
 // данные о сообщениях отправки SMS_GROUP_ID=110
 $r_xml2=$sms->status_sms_group_id(110);
 // Получить данные сообщений отправленных с 18.12.2007 00:00:00 по 23.12.2007      23:00:00
 $r_xml3=$sms->status_sms_date('18.12.2007 00:00:00','23.12.2007 23:00:00');
 header("Content-Type: text/xml; charset=UTF-8");
 echo $r_xml1; // результат XML
 //echo $r_xml2;
 //echo $r_xml3;
?>

Пример 3. Отправка сообщений и получение статусов

Запрос

 
POST= (
    [data] => Array (
            [0] => Array  (
                    [action] => post_sms
                    [message] => Привет!
                    [sender] => 
                    [target] => +79999999999, +79999999992
                )
            [1] => Array  (
                    [action] => post_sms
                    [message] => С днём рождения!
                    [sender] => 
                    [target] => +79999999991
                    [post_id] => x425256
                )
            [2] => Array  (
                    [action] => status
                    [sms_id] => 6666
                )
        )

    [user] => userX
    [pass] => ***
    [CLIENTADR] => 127.0.0.1
    [HTTP_ACCEPT_LANGUAGE] => ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3
)

Результат XML

<output>
     <result sms_group_id="996">
        <sms id="99991" smstype="SENDSMS" phone="+79999999991" sms_res_count="1"><![CDATA[Привет]]></sms>
        <sms id="99992" smstype="SENDSMS" phone="+79999999992" sms_res_count="38"><![CDATA[С днём рождения!]]></sms>
     </result>
     <errors>
        <error code="-20117" post_id="x425256">Неправильный номер телефона: +7999999999999</error>
     </errors>
     <MESSAGES>
        <MESSAGE SMS_ID="6666" SMSTYPE="SENDSMS">
           <CREATED>24.12.07 15:57:45</CREATED> 
           <AUL_USERNAME>userX.Y</AUL_USERNAME> 
           <AUL_CLIENT_ADR>127.0.0.1</AUL_CLIENT_ADR> 
           <SMS_SENDER>SenderName</SMS_SENDER> 
           <SMS_TARGET>89999991111</SMS_TARGET> 
           <SMS_RES_COUNT>1</SMS_RES_COUNT> 
                   <SMS_TEXT>
                      <![CDATA[ Привет ]]> 
                 </SMS_TEXT>
           <SMSSTC_CODE>wait</SMSSTC_CODE> 
           <SMS_STATUS>Сообщение в процессе доставки</SMS_STATUS> 
           <SMS_CLOSED>0</SMS_CLOSED> 
           <SMS_SENT>0</SMS_SENT> 
        </MESSAGE>
     </MESSAGES>
</output>

Данные по сообщению:

  • SMS_ID - ID сообщения
  • SMS_GROUP_ID - ID рассылки сообщений
  • SMSTYPE - тип сообщения
  • CREATED - дата и время создания сообщения
  • AUL_USERNAME - Имя пользователя, создавшего сообщение
  • AUL_CLIENT_ADR - IP адрес пользователя, создавшего сообщение
  • SMS_SENDER - Имя отправителя сообщения
  • SMS_TARGET - Телефон адресата
  • SMS_RES_COUNT - Кол-во единиц ресурсов на данное сообщение
  • SMS_TEXT - Текст сообщения
  • SMSSTC_CODE - Код статуса доставки сообщения
  • SMS_STATUS - Текстовое описание статуса доставки сообщения
  • SMS_CLOSED - [0,1] 0 - сообщения находится в процессинге, 1 = работа по отправке сообщения завершена
  • SMS_SENT - [0,1] 0 - сообщение не отослано, 1 = сообщение отослано успешно
  • SMS_CALL_DURATION - Время, в течение которого было установлено соединение для отправки сообщения.
  • SMS_DTMF_DIGITS - Что пользователь нажимал в сеансе разговора (для SENDVOICE (в разработке))
  • SMS_CLOSE_TIME - Время завершения работы по сообщению.

Использование PHP-класса

<?php
 // Единый запрос 
 Include('QTSMS.class.php');
 $sms= new QTSMS('userX.Y','пароль');
 // !!! Команда на кеширование запросов
 $sms->start_multipost();    
 // Отправка смс 
 $sms->post_message('Привет', '+79999999991,+79999999992', 'Vasya');    
 // Отправка смс 
 $sms->post_message_phl('С днём рождения!', 'druzya', 'Petya', 'x425256');                           
 // данные о сообщении SMS_ID=6666
 $sms->status_sms_id(6666);
 // данные о сообщениях с SMS_GROUP_ID=110
 $sms->status_sms_group_id(110) ; 
 // !!! отправить всё одним запросом и получить результат в XML
 $r_xml=$sms->process();   
 header("Content-Type: text/xml; charset=UTF-8");
 echo $r_xml; // результат XML
?>

Пример 4. Получение баланса

Запрос

POST= (
    [user] => userX
    [pass] => ***    
    [action] => balance    
    [CLIENTADR] => 127.0.0.1    
    [HTTP_ACCEPT_LANGUAGE] => ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3
)

Результат XML

<output>
     <BALANCE>
     <AGT_BALANCE>1000</AGT_BALANCE>    [текущее состояние счёта]
     <OVERDRAFT>100</OVERDRAFT>         [максимальных уход в минус]
     </BALANCE>
</output>

Использование PHP-класса

<?php
 Include('QTSMS.class.php');
 $sms= new QTSMS('XXXXX','пароль');
 
 // получение баланса
 $r_xml=$sms->get_balance();
 // результат в XML
 header("Content-Type: text/xml; charset=UTF-8");
 echo $r_xml; // результат XML
?>

Пример 5. Получение входящих сообщений.

Запрос

POST= (
    [user] => userX
    [pass] => ***    
    [action] => inbox
    [sib_num] => 123
    [date_from] => 12.01.2010 00:00:00
    [date_to] => 15.01.2010 12:00:00
)

Результат XML

<output>
  <RECEIVER AGT_ID="10XXX" DATE_REPORT="08.02.2010 14:10:42"/>
  <inbox>
    <MESSAGE SMS_ID="10001234235782138" SMSTYPE="RECVSMS">
      <CREATED>13.01.2010 18:08:29</CREATED>
      <SMS_SENDER>79670413211</SMS_SENDER>
      <SMS_TARGET>79037672810</SMS_TARGET>
      <SMS_RES_COUNT>1</SMS_RES_COUNT>
      <SMS_TEXT>test 1111</SMS_TEXT>
      <SMS_STATUS>N</SMS_STATUS>
    </MESSAGE>
    <MESSAGE SMS_ID="1000123312382134" SMSTYPE="RECVSMS">
      <CREATED>14.01.2010 18:03:03</CREATED>
      <SMS_SENDER>79670413211</SMS_SENDER>
      <SMS_TARGET>79037672810</SMS_TARGET>
      <SMS_RES_COUNT>1</SMS_RES_COUNT>
      <SMS_TEXT>qwerty 22</SMS_TEXT>
      <SMS_STATUS>N</SMS_STATUS>
    </MESSAGE>
  </inbox>
</output>

Использование PHP-класса

<?php
 Include('QTSMS.class.php');
 $sms= new QTSMS('XXXXX','пароль');
 
 // получение только новых входящих смс для ящика 134 
 $r_xml=$sms->inbox_sms(1, 134);
 // получение только новых входящих смс 
 // для ящика 134 c 10.01.2010 00:00:00  до 15.01.2010 00:00:00 
 // $r_xml=$sms->inbox_sms(0,134,'10.01.2010 00:00:00','15.01.2010 00:00:00'); 
 
 // результат в XML
 header("Content-Type: text/xml; charset=UTF-8");
 echo $r_xml; // результат XML
?>

Обработка ошибок

Коды ошибок тэга error:

  • -20117 Неправильный номер телефона.
  • -20170 Слишком большой текст сообщения. Максимальная длина не должна превышать 160 байт.
  • -20171 Не пройдена проверка текста сообщения на наличие недопустимых слов и/или фраз.
  • -20158 Отправитель или получатель в черном списке.
  • -20167 Сработало ограничение по отправке одинакового текста на один и тот же номер в течение небольшого промежутка времени. Обратитесь в поддержку, если хотите отключить или уменьшить период.
  • -20144 Нет доступного тарифа для запрашиваемого направления.
  • -20147 Нет подходящего тарифа у вышестоящего контрагента.
  • -20174 Политика маршрутизации не найдена.
  • -20154 Ошибка транспорта. При возникновении этой ошибки обратитесь в службу поддержки.
  • -20148 Не поддерживаемое направление.

qtsms.class.zip

Для работы с классом требуется PHP5