Передача документов на языке XML является одним из самых распространенных и универсальных методов передачи данных через Интернет.

Протокол XML подразумевает обмен запросами на языке XML. Обмен информацией происходит через соединение TCP/IP по протоколу HTTP или HTTPS (HTTP over SSL) методом POST.

Для обмена информацией посылается XML-запрос вида: <xml_request name=″”>

Возможные значения поля name:

• name=″sms_send″ – запрос на отправку SMS
• name=″sms_status2″ – запрос на получение статуса ранее отправленных SMS

В ответ приходит отклик вида: <xml_result xml_name=″″ res=″″>

Возможные значения поля name:

• name=″sms_send″ – запрос на отправку SMS
• name=″sms_status2″ – запрос на получение статуса ранее отправленных SMS

Возможные значения поля res:

• res=″0″ – ошибок нет
• res=″-xxxxx″ – обнаружена ошибка с кодом -xxxxx

Авторизация происходит передачей логина и пароля: <xml_user lgn=″″ pwd=″″/>

Преимущества:

• возможности расширения благодаря гибкости языка XML
• безопасность и сохранность данных, передаваемых по протоколу HTTPS методом POST

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

• Адрес обращения :
  http://service.qtelecom.ru/public/http/z.php или https://service.qtelecom.ru/public/http/z.php
• Формат входных данных :

Content-Type: application/x-www-form-urlencoded
Content-Charset: UTF-8

• Тип авторизации : PLAIN (открытым текстом)
• Метод отправки запроса : POST

2. XML-запросы

Отправка SMS сообщения и получение статусов ранее отправленных сообщений производятся отправкой XML-запроса определенной структуры.

В одном XML-запросе может быть отправлено до 250 SMS сообщений.

2.1 XML-запрос для отправки сообщений

Клиент отправляет XML-запрос на отправку сообщения (определить, что идет отправка SMS можно по полю name=″sms_send″)

<?xml version="1.0" encoding="UTF-8" ?>
  <xml_request name="sms_send">
  <xml_user lgn="" pwd=""/>
       <sms sms_id="1" number="XXXXXXXXXXX" source_number="sender" ttl="10">text sms</sms>
       <sms sms_id="2" number="XXXXXXXXXXX" source_number="" ttl="15">text sms</sms>
       <sms sms_id="s_3" number="XXXXXXXXXXX" source_number="">text sms</sms>
</xml_request>

Параметры запроса:

• sms_id – уникальный идентификатор SMS в системе клиента. Строка длиной до 50 символов. На основе уникальности параметра sms_id проверяется дублирование запросов на отправку SMS. Если sms_id использован повторно, система вернет xml_result/push/@res=1, а в push_id будет указан идентификатор первой попытки отправки сообщения с данным sms_id.
• number – телефонный номер получателя в международном формате или короткий номер. Строка длиной до 25 символов. Параметр не может быть пустым.
• source_number – номер отправителя. Строка длиной от 11 до 16 символов в зависимости от nипа (номер или текст). Параметр не может быть пустым.
• ttl – Время жизни сообщения в минутах. Необязательный параметр. Максимальное время, в течение которого сообщение должно быть доставлено на телефон. Если в течение этого времени доставка не возможна (например абонент не в зоне действия сети), сообщение не будет доставлено вовсе. Внимание, данная функция может не работает для некоторых направлений, например для CDMA телефонов.

При успешном разборе XML-запроса в ответ придет сообщение вида:

<xml_result xml_name="sms_send" res="" >
       <push sms_id="1" push_id="XXXX" res="0" number="XXXXXXXXXXX" sms_count=""/>
       <push sms_id="2" push_id="XXXX" res="0" number="XXXXXXXXXXX" sms_count=""/>
       <push sms_id="3" res="" description=""/>
</xml_result>

Параметры ответа:

• push_id – уникальный идентификатор SMS в системе ESME
• sms_id – уникальный внутренний идентификатор SMS в системе клиента
• res=0 – SMS было отправлено успешно
• res – ″-xxxx″ – код ошибки, возникшей при отправке конкретного SMS
• description – описание ошибки, возникшей при отправке конкретного SMS
• number – номер телефона получателя SMS
• sms_count – количество SMS, из которых состоит одно набранное сообщение

Если в результате разбора XML-запроса возникли ошибки, придет сообщение вида:

<xml_result res=″-XXXX″ description=″″/>

Параметры ответа:

• res – код ошибки XML-запроса или его обработки
• description – описание ошибки

2.2 XML-запрос для получения статуса ранее переданных сообщений

Клиент отправляет XML-запрос на получение статуса переданных сообщений (определить, что идет получение статуса SMS можно по полю name=″sms_status2″)

<?xml version="1.0" encoding="UTF-8" ?>
<xml_request name="sms_status2" >
<xml_user lgn="" pwd=""/>
<sms push_id=""/>
<sms push_id=""/>
<sms push_id=""/>
<sms push_id=""/>
</xml_request>

Параметры запроса:

• push_id – идентификатор ранее переданного SMS в системе ESME

При успешном разборе XML-запроса в ответ придет сообщение вида:

< xml_result name="sms_status2" res="" >
< sms push_id="" status="" number="XXXXXXXXXXX" delivery_date="" delivery_time="" description="" />
< sms push_id="" status="" number="XXXXXXXXXXX" delivery_date="" delivery_time="" description="" />
< sms push_id="" status="" number="XXXXXXXXXXX" delivery_date="" delivery_time="" description="" />
</xml_result>

Параметры ответа:

• push_id – идентификатор ранее переданного SMS в системе ESME
• status – код статуса доставки
• number – номер телефона, на который было отправлено сообщение с указанным push_id
• delivery_time – время доставки SMS. Строка вида «hh:mm:ss»
• delivery_date – дата доставки SMS. Строка вида «dd.mm.yyyy»
• description – описание статуса. Строка.

Если в результате разбора XML-запроса возникли ошибки, придет сообщение вида:

<xml_result res="-XXXX" description=""/>

Параметры ответа:

• res – код ошибки XML-запроса или его обработки
• description – описание ошибки

3. Ограничение на передачу специальных символов в тексте SMS

Для предотвращения ошибок при разборе XML-запросов и ответов, символы в тексте сообщения, которые используются как служебные в языке XML, необходимо заменять. Замена производится в запросах по таблице слева направо, а в ответах производится обратная замена справа налево.

Специальный символ	Замена
<	&lt;
>	&gt;
»	&quot;
‘	&apos;
&	&amp;

4. Статусы доставки ранее отправленных SMS

При выполнении запроса на получение статусов доставки ранее переданных сообщений <sms_status2> возвращаются коды, представленные в таблице.

Статус	Описание	Расшифровка статуса
-1004	Push to SMSC failed	SMS не доставлена по одной из следующих причин: – абонент находится вне зоны действия сети; – номер не обслуживается оператором связи; – недостаточно средств на счете; – для абонента заблокирован/не поддерживается прием SMS; – переполнена очередь входящих SMS на телефоне абонента; либо по другим причинам, связанным с невозможностью доставки.
-1	Bad submit_id	Указан не существующий push_id сообщения
1	Push request queued	SMS помещена в очередь на отправку
2	Request redirected to SMSC/MMSC	SMS передана оператору связи и ожидает доставку
4	Content delivery confirmed	SMS доставлена

5. Коды ошибок, возникающих при обработке запросов

При обработке XML-запроса могут возникать ошибки, код которых возвращаются в атрибуте <res>, а описание в атрибуте <description> ответа. Не следует путать эти коды ошибок со статусами доставки SMS!

Система выдает описания ошибок, возникших как при разборе XML-запроса в целом, так и для каждого отдельного переданного сообщения.

5.1 Ошибки, относящиеся к XML-запросу в целом

Код и описание ошибки при разборе XML-запроса передается параметрами res и description в теге <xml_result>. Если возникли ошибки при разборе XML-запроса, она относится ко всем сообщениям данного запроса и ни одно из переданных в этом запросе сообщений не будет доставлено.

5.2 Ошибки, относящиеся к передаче отдельных сообщений запроса

Код и описание ошибки при отправке каждого конкретного SMS передается параметрами res и description в теге <push>. Код и описание ошибки в теге <push> относится только к сообщению с данным <push_id>. Все сообщения запроса при этом будут доставлены или не доставлены независимо друг от друга.