8 (800) 500-80-16
  • Межгород 8 (800) 500-80-16
  • Санкт-Петербург 7 (812) 426-13-66
  • Москва 7 (495) 374-80-34
  • Новосибирск 7 (383) 207-54-38
  • Екатеринбург 7 (343) 351-75-20
  • Челябинск 7 (351) 799-57-70
  • Воронеж 7 (473) 300-30-34
  • Нижний Новгород 7 (831) 280-98-15
  • Казань 7 (843) 212-20-24
  • Самара 7 (846) 212-98-95
  • Краснодар 7 (861) 201-83-82
  • Ростов-на-Дону 7 (863) 322-03-92

Протокол XML

Протокол XML (POST-запрос)

XML (eXtensible Markup Language)

Расширяемый язык разметки. Спецификация XML описывает XML-документы и частично описывает поведение XML-обработчиков. Язык называется расширяемым, поскольку он не фиксирует разметку, используемую в документах: разработчик волен создать разметку в соответствии с потребностями к конкретной области, будучи ограниченным лишь синтаксическими правилами языка.

Протокол XML

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

POST

один из многих методов запроса, поддерживаемых HTTP протоколом, используемым во Всемирной паутине. Метод запроса POST предназначен для запроса, при котором веб-сервер принимает данные, заключенные в тело сообщения, для хранения.

Для обмена информацией посылается XML-запрос вида:

<xml_request name=""> 

поле name описывает тип запроса к серверу:

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

В ответ на данный запрос приходит следующий XML-результат:

<xml_result xml_name="" res="">

поле xml_name показывает тип запроса, который был отправлен к серверу:

xml_name="sms_send"		- запрос на отправку SMS
xml_name="sms_status2" - запрос на получение статуса ранее отправленных SMS

поле res указывает на возможные ошибки при отправке:

res=null				- ошибок нет
res="?" - номер возникшей ошибки

Структура XML-запроса

Основные параметры:

lgn = "login" 				- зарегистрированное в системе ID пользователя вида XXXXX.X
pwd = "password" 			- пароль пользователя
host = http://web.smsgold.ru:8090 или https://web.smsgold.ru:8090 - адрес http сервера для xml-запроса
encoding = "UTF-8" 			- кодировка xml-запроса
Тип авторизации: PLAIN (открытым текстом)
Метод отправки запроса: POST

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

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

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

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

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

sms_id		- уникальный идентификатор SMS в системе клиента

строка длиной до 50 символов. На основе уникальности параметра sms_id проверяется дублирование запросов на отправку SMS. Если sms_id использован повторно, система вернет xml_result/push_id/@res=1, а в push_id будет указан идентификатор первой попытки отправки сообщения с данным sms_id.

number		- телефонный номер получателя SMS в международном формате

строка длиной до 25 символов. Параметр не может быть пустым.

source_number	- подпись отправителя

строка длиной до 11 символов (текст) или до 16 символов (номер) в зависимости от типа. Параметр не может быть пустым.

ttl		- время жизни сообщения в минутах

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

text sms	- текст, передаваемый в SMS

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

<xml_result xml_name="sms_send" res="">
	<push sms_id="1"   push_id="YYYYYYYY" res=null number="XXXXXXXXXXX" sms_count="Z"/>
	<push sms_id="2"   push_id="YYYYYYYY" res=null number="XXXXXXXXXXX" sms_count="Z"/>
	<push sms_id="s_3"                    res="?"  description=""/>
</xml_result>

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

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

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

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

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

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

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

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

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

push_id		- уникальный идентификатор, ранее переданного SMS, в системе ESME

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

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

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

push_id		- уникальный идентификатор, ранее переданного SMS, в системе ESME
status		- код статуса доставки
number		- телефонный номер на который было отправлено SMS, с указанным push_id, в международном формате
delivery_date	- дата доставки SMS (dd.mm.yyyy)
delivery_time	- время доставки SMS (hh:mm:ss)
description	- описание статуса (string)

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

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

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

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

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

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

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

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

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

При обработке XML-запроса могут возникать ошибки, код которых возвращаются в атрибуте

<res>, а описание в атрибуте <description> ответа.

Внимание: Не следует путать эти коды ошибок со статусами доставки SMS.

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

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

Код и описание ошибки при разборе XML-запроса передается параметрами res и description в теге

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

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

Код и описание ошибки при отправке каждого конкретного SMS передается параметрами

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

Приложение

Внимание:

Если Вы, для отправки XML-запроса, используете web-сервер и php-скрипт, то необходимо иметь установленную библиотеку cURL, которая даёт возможность соединяться с серверами различных типов и по разным протоколам.

пример PHP-скрипта отправки SMS сообщения через XML-запрос

<?php
$login = '';				// зарегистрированное в системе ID пользователя вида XXXXX.X
$password = '';				// пароль пользователя
$sms_id = '';				// уникальный идентификатор SMS в системе клиента
$dst_number = '';			// телефонный номер получателя SMS в международном формате
$src_number = '';			// подпись отправителя
$sms_text = '';				// текст, передаваемый в SMS

$src = '<?xml version="1.0" encoding="UTF-8"?>
	<xml_request name="sms_send">
	<xml_user lgn="" pwd=""/>
	<sms sms_id=""
	     number=""
	     source_number="">
	     <?php $sms_text ?>
	</sms>
	</xml_request>';		// тело XML-запроса
$href = 'http://web.smsgold.ru:8090';	// адрес сервера для XML-запроса
$res = '';

$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-type: text/xml; charset=utf-8'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CRLF, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $src);
curl_setopt($ch, CURLOPT_URL, $href);
$result = curl_exec($ch);
$res = $result;
curl_close($ch);

echo $res;
?>

пример PHP-скрипта получения статуса ранее переданного SMS сообщения через XML-запрос

<?php
$login = '';				// зарегистрированное в системе ID пользователя вида XXXXX.X
$password = '';				// пароль пользователя
$push_id = '';				// уникальный идентификатор SMS в системе ESME

$src = '<?xml version="1.0" encoding="UTF-8"?>
	<xml_request name="sms_status2">
	<xml_user lgn="" pwd=""/>
	<sms push_id=""/>
	</xml_request>';		// тело XML-запроса
$href = 'http://web.smsgold.ru:8090';	// адрес сервера для XML-запроса
$res = '';

$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-type: text/xml; charset=utf-8'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CRLF, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $src);
curl_setopt($ch, CURLOPT_URL, $href);
$result = curl_exec($ch);
$res = $result;
curl_close($ch);

echo $res;
?>