Мы в социальных сетях:
 
8 800 200 56 57 Звонок по России бесплатный

XML-протокол


Введение

Данный протокол основан на передаче POST-запросом сформированной определенным образом XML (вместо привычных var1=value1&var2=value2) на наш сервер.

К примеру, на PHP такой запрос можно выполнить подобным образом:

$xml = "<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<login>LOGIN</login>
		<password>PASSWORD</password>
		<action>send</action>
		<text>TEXT</text>
		<to number='89010003333'></to>
	</data>";
	
$address = "http://lcab.sms-sending.ru/API/XML/send.php";
$ch = curl_init($address);
curl_setopt($ch, CURLOPT_URL, $address);
curl_setopt($ch, CURLOPT_FAILONERROR, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $xml);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
$result = curl_exec($ch);
echo $result;
curl_close($ch);

А вот так можно отправлять запросы, используя C# в качестве языка программирования:

/*
	action = send|balance|report|cancel
	xml - строка, содержащая сформированную должным образом XML
*/
public String request(string action, string xml)
{
	WebResponse result = null;
	WebRequest req = null;
	Stream newStream = null;
	Stream ReceiveStream = null;
	StreamReader sr = null;
	string strOut = "";
	try
	{
		// Url запрашиваемого методом POST скрипта
		req = WebRequest.Create("http://lcab.sms-sending.ru/API/XML/" + action + ".php");
		req.Method = "POST";
		req.Timeout = 120000;
		req.ContentType = "application/x-www-form-urlencoded";
		byte[] SomeBytes = null;
		SomeBytes = UTF8Encoding.UTF8.GetBytes(xml);
		req.ContentLength = SomeBytes.Length;
		newStream = req.GetRequestStream();
		newStream.Write(SomeBytes, 0, SomeBytes.Length);
		newStream.Close();
		// считываем результат работы
		result = req.GetResponse();
		ReceiveStream = result.GetResponseStream();
		Encoding encode = Encoding.UTF8;
		sr = new StreamReader(ReceiveStream, encode);
		Char[] read = new Char[256];
		int count = sr.Read(read, 0, 256);
		while (count > 0)
		{
			String str = new String(read, 0, count);
			strOut += str;
			count = sr.Read(read, 0, 256);
		}
	}
	catch (Exception ex)
	{
		//MessageBox.Show("Ошибка: " + ex.Message);
	}
	finally
	{
		if (newStream != null)
			newStream.Close();
		if (ReceiveStream != null)
			ReceiveStream.Close();
		if (sr != null)
			sr.Close();
		if (result != null)
			result.Close();
	}
	return strOut;
}

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

Отправка СМС

Для отправки СМС, необходимо передать методом POST на адрес http://lcab.sms-sending.ru/API/XML/send.php следующую XML:

<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<login>LOGIN</login>
		<password>PASSWORD</password>
		<action>ACTION</action>
		<text>TEXT</text>
		<to number='NUMBER'></to>
	</data>
Описание параметров
ПараметрОписаниеОбязательный параметр
<login>LOGIN</login> Вместо LOGIN необходимо подставить Ваш логин Да
<password>PASSWORD</password> Вместо PASSWORD необходимо подставить Ваш пароль Да
<action>ACTION</action> Действие ACTION может иметь только 2 значения:
  1. check – проверка перед отправкой (делать не обязательно)
  2. send – отправка СМС
Нет, по-умолчанию send
<to number='NUMBER'></to> NUMBER – номер получателя.
Формат номера может любым, и содержать вспомогательные символы, например:
  • 79011234567
  • +7(901) 123-45 67
  • 8-901-123-4567
  • 9011234567
Все эти примеры пройдут проверку на формат
Да
<to number='NUMBER'>
ALTERTEXT
</to>
ALTERTEXT – альтернативный текст, который будет отправлен на номер NUMBER Нет, по умолчанию на номер NUMBER отправляется TEXT
<to number='NUM1'></to>
<to number='NUM2'>T1</to>
<to number='NUM3'>T2</to>
Возможно использование нескольких параметров <to>. СМС будет отправлена на NUM1, NUM2 и NUM3. Причем на NUM2 и NUM3 будет отправлен текст T1 и T2 соответственно. На номер NUM1 будет отправлен текст TEXT Нет, достаточно одного тега <to>
<smsid>SMSID</smsid> SMSID – идентификатор СМС (группы СМС). Данный параметр необходим для идентификации отправляемой СМС (группы СМС). Длина идентификатора должна быть не более 21 символа. Нет, если этот параметр не передается, SMSID присваивается автоматически и отдается в ответе сервера.
<datetime>DATETIME</datetime> DATETIME – дата/время отправки. Время местное (согласно указанной информации о местоположении вашей компании при регистрации). DATETIME должен быть в формате MySQL.
yyyy-mm-dd HH:MM:SS
Нет, если этот параметр не задан – СМС ставится в очередь немедленно
<regionalTime>1</regionalTime> Включение опции - отправка по местному времени абонента. Нет. По-умолчанию опция выключена
<source>SOURCE</source> SOURCE – имя отправителя. Нет, если не задано значение, то выбирается 1ое имя отправителя вашего логина
<onlydelivery>1</onlydelivery> Включение опции – оплата только за доставленные. Нет. По умолчанию опция выключена
<vp>VALIDATION_PERIOD</vp> VALIDATION_PERIOD – время жизни СМС (указывается в секундах).
Например, 2 часа = 2 * 3600 = 7200
Нет. По умолчанию 24 часа.
<flash>1 или 0</flash> Если 1, то отправляется flash-смс, если 0 - то обычная. Нет. Если не задано значение, то по-умолчанию 0
Ответ сервера
<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<code>CODE</code>
		<descr>DESCR</descr>
		<smsid>SMSID</smsid>
		<datetime>DATETIME</datetime>
		<action>ACTION</action>
		<allRecivers>ALL_RECIEVERS</allRecivers>
		<colSendAbonent>COL_SEND_ABONENT</colSendAbonent>
		<colNonSendAbonent> COL_NON_SEND_ABONENT </colNonSendAbonent>
		<priceOfSending>PRICE_OF_SENDING</priceOfSending>
		<colsmsOfSending>COL_SMS_OF_SENDING</colsmsOfSending>
		<price>PRICE</price>
	</data>
ПараметрОписание
code Результат обработки (см. раздел «Результат обработки»)
descr Описание результата обработки
smsid Идентификатор СМС (группы СМС). Данный параметр необходим для идентификации отправляемой СМС (группы СМС), в том числе, для получения по SMSID результатов отправки
datetime Дата/время отправки СМС (группы СМС)
action Выполненное действие (проверка или отправка: check или send)
allRecivers Всего получателей (абонентов). В эту цифру не входят номера, которые были отклонены из-за несоответствия формату, например, 74957271122 – не является мобильным телефоном, поэтому не попадет в ALL_RECIEVERS
colSendAbonent Кол-во получателей, которым СМС отправлены (могут быть отправлены).
colNonSendAbonent Кол-во получателей, которым СМС не отправлены (не могут быть отправлены). Причинами могут быть – нехватка средств на счету, пользователь расположен в глобальном Черном Списке, и тп.
priceOfSending Цена рассылки.
colsmsOfSending Общее кол-во смс к отправке. Соответственно двойная СМС, отправленная 3 абонентам даст значение COL_SMS_OF_SENDING=6.
price Стоимость одной СМС.
Примеры использования

Задача 1. Требуется отправить следующий текст: «Добрый день, приглашаем Вас в наш салон», с подписью «Magazin» на 3 номера: +79019011234, +79029021234, +79039031234. Отправка должна произойти немедленно.

Решение:

На адрес http://lcab.sms-sending.ru/API/XML/send.php необходимо методом POST отправить следующую XML:

<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<login>test</login>
		<password>123456</password>
		<action>send</action>
		<text>Добрый день, приглашаем Вас в наш салон</text>
		<source>Magazin</source>
		<to number='+79019011234'></to>
		<to number='7-902-902-12 34'></to>
		<to number='89039031234'></to>
	</data>

Обратите внимание, что поле номер может быть в любом формате, наша система сама приведет его в надлежащий вид.

Задача 2. Требуется отправить следующий текст: «Добрый день, приглашаем Вас в наш салон», с подписью «Magazin» на 3 номера: +79019011234, +79029021234, +79039031234. Отправка должна произойти 1 мая 2010 года в 12:00:00 (время Ваше местное – рассчитывается из информации, указанной при регистрации – Ваш город). На номер +79029021234 необходимо отправить уникальный текст: «Добрый день, приглашаем Вас в наш салон. Скидка по Вашей дисконтной карте – 5%»

Решение:

На адрес http://lcab.sms-sending.ru/API/XML/send.php необходимо методом POST отправить следующую XML:

<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<login>test</login>
		<password>123456</password>
		<action>send</action>
		<text>Добрый день, приглашаем Вас в наш салон</text>
		<source>Magazin</source>
		<datetime>2010-05-01 12:00:00</datetime>
		<to number='+79019011234'></to>
		<to number='7-902-902-12 34'> Добрый день, приглашаем Вас в наш салон. Скидка по Вашей дисконтной карте – 5%</to>
		<to number='89039031234'></to>
	</data>

Обратите внимание, на формат даты/времени: указывать необходимо в формате MySQL.

Задача 3. Требуется отправить следующий текст: «Добрый день, приглашаем Вас в наш салон», с подписью «Magazin» на 3 номера: +79019011234, +79029021234, +79039031234. СМС необходимо отправить 1 февраля 2010 в 12:00:00 и повторить на те же номера с тем же текстом в 18:00:00. Отчет о доставленных СМС должен быть сгруппирован в один (для этих целей и существует параметр SMSID). По сути, SMSID – идентификатор рассылки, чтобы получить более удобный отчет. Если Вы будете отправлять 1000 СМС по одной, каждый раз отправляя POST запрос, то у Вас будет 1000 отчетов о доставке, что не совсем удобно в обработке.

Решение:

На адрес http://lcab.sms-sending.ru/API/XML/send.php необходимо методом POST отправить следующие XML (по очереди):

<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<login>test</login>
		<password>123456</password>
		<smsid>abcde123</smsid>
		<action>send</action>
		<datetime>2010-02-01 12:00:00</datetime>
		<text>Добрый день, приглашаем Вас в наш салон</text>
		<source>Magazin</source>
		<to number='+79019011234'></to>
		<to number='7-902-902-12 34'></to>
		<to number='89039031234'></to>
	</data>
<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<login>test</login>
		<password>123456</password>
		<smsid>abcde123</smsid>
		<action>send</action>
		<datetime>2010-02-01 18:00:00</datetime>
		<text>Добрый день, приглашаем Вас в наш салон</text>
		<source>Magazin</source>
		<to number='+79019011234'></to>
		<to number='7-902-902-12 34'></to>
		<to number='89039031234'></to>
	</data>

Обратите внимание, чтобы сгруппировать 2 рассылки в 1, для более удобного отчета (в данном примере для решения задачи), мы использовали параметр smsid=abcde123.

Отмена СМС

Для отмены рассылки необходимо передать методом POST на адрес http://lcab.sms-sending.ru/API/XML/cancel.php следующую XML.

<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<login>LOGIN</login>
		<password>PASSWORD</password>
		<smsid>SMSID</smsid>
	</data>
Описание параметров
ПараметрОписаниеОбязательный параметр
<login>LOGIN</login> Вместо LOGIN необходимо подставить Ваш логин. Да
<password>PASSWORD</password> Вместо PASSWORD необходимо подставить Ваш пароль. Да
<smsid>SMSID</smsid> SMSID – идентификатор СМС (группы СМС). Данный параметр необходим для идентификации отправляемой СМС (группы СМС). Да
Ответ сервера
<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<code>CODE</code>
		<descr>DESCR</descr>
		<cancelCol>CANCELCOL</ cancelCol >
	</data>
ПараметрОписание
code Результат обработки (см. раздел «Результат обработки»)
descr Описание результата обработки
cancelCol Кол-во отмененных СМС

Важное примечание: вы можете отменить только те СМС, которые не ушли в сеть оператора!

Список СМС

Чтобы получить список рассылок за определенный период, необходимо передать методом POST на адрес: http://lcab.sms-sending.ru/API/XML/report.php следующую XML:

<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<login>LOGIN</login>
		<password>PASSWORD</password>
		<start>START</start>
		<stop>STOP</stop>
	</data>
Описание параметров
ПараметрОписаниеОбязательный параметр
<login>LOGIN</login> Вместо LOGIN необходимо подставить Ваш логин Да
<password>PASSWORD</password> Вместо PASSWORD необходимо подставить Ваш пароль Да
<start>START</start> Вместо START необходимо подставить дату начала отчета Нет, по умолчанию ставится дата регистрации компании в системе
<stop>STOP</stop> Вместо STOP необходимо подставить дату окончания отчета Нет, по умолчанию ставится сегодняшняя дата
Ответ сервера
<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<code>CODE</code>
		<descr>DESCR</descr>
		<sms>
			<smsid>SMSID1</smsid>
			<datetime>DATETIME1</datetime>
			<text>TEXT1</text>
			<source>SOURCE1</source>
			<allCol>ALLCOL1</allCol>
			<deliveredCol>DELIVEREDCOL1</deliveredCol>
			<notDeliveredCol>NOTDELIVEREDCOL1</notDeliveredCol>
			<waitingCol>WAITING1</waitingCol>
			<enqueuedCol>ENQUEUEDCOL1</enqueuedCol>
			<payment>PAYMENT1</payment>
		</sms>
		<sms>
			<smsid>SMSID2</smsid>
			<datetime>DATETIME2</datetime>
			<text>TEXT2</text>
			<source>SOURCE2</source>
			<allCol>ALLCOL2</allCol>
			<deliveredCol>DELIVEREDCOL2</deliveredCol>
			<notDeliveredCol>NOTDELIVEREDCOL2</notDeliveredCol>
			<waitingCol>WAITING2</waitingCol>
			<enqueuedCol>ENQUEUEDCOL2</enqueuedCol>
			<payment>PAYMENT2</payment>
		</sms>
	</data>
ПараметрОписание
code Результат обработки (см. раздел «Результат обработки»)
descr Описание результата обработки
smsid Идентификатор СМС (группы СМС). Данный параметр необходим для идентификации отправляемой СМС (группы СМС), в том числе, для получения по SMSID результатов отправки. Обратите внимание, что в данном отображении, идентификатор выдан системой (отличается от SMSID, указанного при отправке СМС)
datetime Дата/время отправки СМС (группы СМС)
text Текст отправленной СМС.
source Адрес отправителя отправленной СМС.
allCol Общее количество абонентов, которым было отправлено СМС.
deliveredCol Количество доставленных сообщений
notDeliveredCol Количество не доставленных сообщений.
waitingCol Количество сообщений в статусе ОЖИДАНИЕ.
enqueuedCol Количество отправленных сообщений, отчет по которым еще не был получен.
payment Стоимость рассылки.
 

Отчет

Чтобы получить детализацию рассылки, необходимо передать методом POST на адрес: http://lcab.sms-sending.ru/API/XML/report.php следующую XML:

<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<login>LOGIN</login>
		<password>PASSWORD</password>
		<smsid >SMSID</smsid>
	</data>
Описание параметров
ПараметрОписаниеОбязательный параметр
<login>LOGIN</login> Вместо LOGIN необходимо подставить Ваш логин Да
<password>PASSWORD</password> Вместо PASSWORD необходимо подставить Ваш пароль Да
<smsid>SMSID</smsid> SMSID - идентификатор СМС (группы СМС). Обратите внимание, что можно указать идентификатор, выданный системой в разделе «Список СМС». Также можно указать идентификатор, указанный (выданный) при отправке СМС. Да
Ответ сервера в случае передачи SMSID, присвоенного при отправке СМС
<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<code>1</code>
		<descr>Операция успешно завершена</descr>
		<detail>
			<delivered>
				<number>79010000000</number>
			</delivered>
			<notDelivered>
				<number>79020000000</number>
			</notDelivered>
			<waiting>
				<number>79030000000</number>
			</waiting>
			<enqueued>
				<number>79040000000</number>
			</enqueued>
			<cancel>
				<number>79050000000</number>
			</cancel>
			<onModer>
				<number>79060000000</number>
			</onModer>
		</detail>
	</data>
ПараметрОписание
code Результат обработки (см. раздел «Результат обработки»)
descr Описание результата обработки
delivered Список абонентов, получивших СМС
notDelivered Список абонентов, не получивших СМС
waiting Список абонентов, СМС для которых находится в статусе "В ожидании"
enqueued Список абонентов, отчет о доставке по которым еще не сформирован
cancel Список отмененных номеров
onModer Список номеров, сообщения для которых находятся на модерации
Ответ сервера в случае передачи SMSID, полученного в списке СМС-рассылок за период (предыдущий раздел руководства)
<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<code>CODE</code>
		<descr>DESCR</descr>
		<sms>
			<smsid>SMSID</smsid>
			<datetime>DATETIME</datetime>
			<text>TEXT</text>
			<source>SOURCE</source>
			<allCol>ALLCOL</allCol>
			<deliveredCol>DELIVEREDCOL</deliveredCol>
			<notDeliveredCol>NOTDELIVEREDCOL</notDeliveredCol>
			<waitingCol>WAITING</waitingCol>
			<enqueuedCol>ENQUEUEDCOL</enqueuedCol>
			<payment>PAYMENT</payment>
		</sms>
		<detail>
			<delivered>
				<number>NUMBER1</number>
				<number>NUMBER2</number>
			</delivered>
			<notDelivered>
				<number>NUMBER3</number>
				<number>NUMBER4</number>
			</notDelivered>
			<waiting>
				<number>NUMBER5</number>
			</waiting>
			<enqueued>
				<number>NUMBER6</number>
			</enqueued>
			<cancel>
				<number>NUMBER7</number>
			</cancel>
			<onModer>
				<number>NUMBER8</number>
			</onModer>
		</detail>
	</data>
ПараметрОписание
code Результат обработки (см. раздел «Результат обработки»)
descr Описание результата обработки
<sms>…</sms> В этом блоке находится информация о рассылке.
smsid Идентификатор СМС (группы СМС). Данный параметр необходим для идентификации отправляемой СМС (группы СМС).
datetime Дата/время отправки СМС (группы СМС).
text Текст отправленной СМС, как он виден в отчетах (отличается от реального).
source Адрес отправителя отправленной СМС.
allCol Общее количество абонентов, которым было отправлено СМС.
deliveredCol Количество доставленных СМС.
notDeliveredCol Количество не доставленных СМС.
waitingCol Количество СМС в статусе ОЖИДАНИЕ.
enqueuedCol Количество СМС без отчета.
payment Стоимость рассылки.
<detail>…</detail> В этом блоке находится детальная информация о рассылке.
delivered Список абонентов, получивших СМС
notDelivered Список абонентов, не получивших СМС
waiting Список абонентов, СМС для которых находится в статусе "В ожидании"
enqueued Список абонентов, отчет о доставке по которым еще не сформирован
cancel Список отмененных номеров
onModer Список номеров, сообщения для которых находятся на модерации
 

Проверка кодов

Чтобы проверить уникальный код, отправленный из раздела Акций необходимо передать методом POST на адресhttp://lcab.sms-sending.ru/API/XML/checkcode.php следующую XML.

<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<login>LOGIN</login>
		<password>PASSWORD</password>
		<code>CODE</code>
		<markAsUsed>1 или 0</markAsUsed>
		<phone>PHONE</phone>
	</data>
Описание параметров
ПараметрОписаниеОбязательный параметр
<login>LOGIN</login> Вместо LOGIN необходимо подставить логин менеджера из раздела акций. Да
<password>PASSWORD</password> Вместо PASSWORD необходимо подставить пароль менеджера из раздела акций. Да
<code>CODE</code> CODE – уникальный код, который называет клиент. Да
<markAsUsed>1</markAsUsed> Помечать код использованным (1) или нет (0) Нет, по-умолчанию стоит "1" (помечать использованным)
<phone>PHONE</phone> Если указан, то проверить еще и номер телефона Нет
Ответ сервера
<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<code>CODE</code>
		<descr>DESCR</descr>
		<managerText>MANAGERTEXT</managerText>
		<phone>PHONE</phone>
	</data>
ПараметрОписание
code Результат обработки
descr Описание результата обработки
managerText В случае, если code = 1 (т.е. проверка кода завершена успешно) в этом тэге будет содержаться текст с инструкцией для менеджера - что необходимо выдать клиенту.
phone В случае, если code = 1 (т.е. проверка кода завершена успешно) в этом тэге будет содержаться номер телефона клиента.
 

Баланс

Для проверки баланса, необходимо передать методом POST на адрес http://lcab.sms-sending.ru/API/XML/balance.php следующую XML

<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<login>LOGIN</login>
		<password>PASSWORD</password>
	</data>
Описание параметров
ПараметрОписаниеОбязательный параметр
<login>LOGIN</login> Вместо LOGIN необходимо подставить Ваш логин Да
<password>PASSWORD</password> Вместо PASSWORD необходимо подставить Ваш пароль Да
Ответ сервера
<?xml version='1.0' encoding='UTF-8'?>
	<data>
		<code>CODE</code>
		<descr>DESCR</descr>
		<account>ACCOUNT</account>
	</data>
ПараметрОписание
code Результат обработки (см. раздел «Результат обработки»)
descr Описание результата обработки
account Значение баланса, тип FLOAT
 

Описание кодов

Описание кодов обработки XML запроса
КодЗначение
1 Успешно завершенная операция
500 Недостаточно переданных параметров
501 Неверная пара логин/пароль
502 Превышен размер smsid. Максимальный размер 21 символ
503 Неверный формат datetime. Верный: yyyy-mm-dd HH:MM:SS
504 Недопустимое значение Адреса отправителя
70х – 70хх Ошибка парсера XML документа (х – цифры 0..9)