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

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

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

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

Адрес обращения	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-сайт
Максимальная длина сообщений	480 символов

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

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

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

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

SMS сообщение

Для отправки SMS необходимо вызвать методом GET или POST адрес:

https://service.qtelecom.ru/public/http/?action=post_sms&user=<user>&pass=<password>&target=<phones>&message=<message>

Описание обязательных параметров, передаваемых Серверу:

Параметр	Значение
action	post_sms
user	Логин
password	Пароль
target	Список адресатов через запятую. (Пример: «+70010001212, 80009990000»).(Разрешается использование только или «target», или «phl_codename»)
phl_codename	Кодовое имя контакт-листа в системе https://go.qtelecom.ru. (Разрешается использование только или «target» или «phl_codename») Также можно использовать параметр gender — фильтр по полу получателя. Значение: M / F (мужской / женский)
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
sms_type	Тип SMS. Пустое значение: Простое SMS W: Wap push сообщение F: Flash SMS сообщение	Пустое значение
wap_url	HTTP ссылка с текста сообщения (https://…..). Используется только для sms_type = W, то есть Wap push сообщения.	—
wap_expires	Дата и время, когда истекает срок доставки Wap push сообщения. (Формат: dd.mm.yyyy hh:ii:ss (дд.мм.гггг чч:ми:сс))	—

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