Наши телефоны
mirsms.rumirsms.ru → API

Протокол XML

Содержание

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

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

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

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

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

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

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

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

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

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

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>

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

При успешном разборе 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>

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

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

<xml_result res=″-XXXX″ 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>

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

При успешном разборе 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>

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

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

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

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

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

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

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


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 передана оператору связи и ожидает доставку

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>. Все сообщения запроса при этом будут доставлены или не доставлены независимо друг от друга.