Структура HTTP POST-запроса

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

[user] => login		зарегистрированное в системе ID пользователя вида XXXXX или ХХХХХ.X
[pass] => password	пароль пользователя
Адрес обращения:	http://web.smsgold.ru/http2/ или https://web.smsgold.ru/http2/
Тип авторизации:	PLAIN (открытым текстом)
Метод отправки запроса:	POST
Кодировка:		UTF-8
Content-Type:		application/x-www-form-urlencoded

Максимальная длина сообщений: 480 символов.

Авторизация

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

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

Параметры передачи смс http-серверу в виде POST-запроса (определить, что идет отправка SMS можно по полю [action] => send):

Пример запроса на PHP:
<?php
header('Content-type: text/xml');
$ch = curl_init();
$data = array(
    'user'   => '10XXX',
    'pass'   => 'PASSWORD',
    'action' => 'send',
    'sender' => 'SmsGold',
    'number' => '79XXXXXXXXX',
    'text'   => 'Текст Вашего смс сообщения'
    );
curl_setopt($ch, CURLOPT_URL, 'http://web.smsgold.ru/http2/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 30);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
$res = curl_exec($ch);
curl_close($ch);
echo $res;
?>

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_send" err="">
	<result sms_group_id="XX-XXXX-XX">
	<sms sms_id="XXXXXXXXXXX" err="" number="7XXXXXXXXXX" parts="количество частей из которых состоит текст смс"><![CDATA[текст отправленной смс...]]></sms>
	</result>
</xml_result>
</output>

*err=""	- номер ошибки, возникшей при отправке, если ошибки нет, то err=null либо err="0"
(может быть как для всего пакета смс - ошибка обработки самого запроса, так и для одного конкретного номера - ошибка номера, направления и т.д.)

Пример запроса на PHP:
<?php
header('Content-type: text/xml');
$ch = curl_init();
$data = array(
    'user'   => '10XXX',
    'pass'   => 'PASSWORD',
    'action' => 'send',
    'sender' => 'SmsGold',
    'number' => '79XXXXXXXXX,79XXXXXXXXX',
    'text'   => 'Текст Вашего смс сообщения'
    );
curl_setopt($ch, CURLOPT_URL, 'http://web.smsgold.ru/http2/');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 30);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
$res = curl_exec($ch);
curl_close($ch);
echo $res;
?>

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_send" err="">
	<result sms_group_id="XX-XXXX-XX">
	<sms sms_id="XXXXXXXXXXX" err="" number="7XXXXXXXXXX" parts="количество частей из которых состоит текст смс"><![CDATA[текст отправленной смс...]]></sms>
	<sms sms_id="XXXXXXXXXXX" err="" number="7XXXXXXXXXX" parts="количество частей из которых состоит текст смс"><![CDATA[текст отправленной смс...]]></sms>
	…
	</result>
</xml_result>
</output>

*err=""	- номер ошибки, возникшей при отправке, если ошибки нет, то err=null либо err="0"
(может быть как для всего пакета смс - ошибка обработки самого запроса, так и для одного конкретного номера - ошибка номера, направления и т.д.)

Получение статусов сообщений

Имеется три варианта получения статусов для сообщений (определить, что идет получение статуса SMS можно по полю [action] => status):

Возможные статусы:

QUEUED  - сообщение находится в обработке на нашей стороне
ENROUTE - сообщение отправлено оператору
DELIVRD - сообщение успешно доставлено
EXPIRED - время жизни сообщения истекло
DELETED - сообщение удалено
UNDELIV - не удалось доставить сообщение
ACCEPTD - сообщение принято и будет отправлено оператору
UNKNOWN - состояние сообщения не определено
REJECTD - сообщение отклонено

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_status" err="">
	<result>
	<sms sms_id="XXXXXXXXXXX" err="" number="7XXXXXXXXXX" sender="" parts="Z" status="" delivery_date="dd.mm.yyyy" delivery_time="hh:mm:ss" description=""></sms>
	</result>
</xml_result>
</output>

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_status" err="">
	<result sms_group_id="XXXX-XXXXXXXXXX-XXXX">
	<sms sms_id="XXXXXXXXXXX" err="" number="7XXXXXXXXXX" sender="NAME" parts="Z" status="DELIVRD" delivery_date="DD.MM.YYYY" delivery_time="HH:MM:SS" description="сообщение успешно доставлено"></sms>
	<sms sms_id="XXXXXXXXXXX" err="" number="7XXXXXXXXXX" sender="NAME" parts="Z" status="UNDELIV" delivery_date="DD.MM.YYYY" delivery_time="HH:MM:SS" description="не удалось доставить сообщение"></sms>
	…
	</result>
</xml_result>
</output>

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_status" err="">
	<result date_from="DD.MM.YYYY HH:MM:SS" date_to="DD.MM.YYYY HH:MM:SS">
	<sms sms_id="XXXXXXXXXXX" err="" number="7XXXXXXXXXX" sender="NAME" parts="Z" status="DELIVRD" delivery_date="DD.MM.YYYY" delivery_time="HH:MM:SS" description="сообщение успешно доставлено"></sms>
	<sms sms_id="XXXXXXXXXXX" err="" number="7XXXXXXXXXX" sender="NAME" parts="Z" status="UNDELIV" delivery_date="DD.MM.YYYY" delivery_time="HH:MM:SS" description="не удалось доставить сообщение"></sms>
	…
	</result>
</xml_result>
</output>

Поле атрибута description тега <sms> в ответе сервера при получении статусов сообщений может принимать следующие значения:

• Некорректный номер телефона
• Недостаточно средств на счету
• Нет денег на счету вышестоящего контрагента
• Отправка заблокирована, номере телефона находится в черном списике
• Запрещено посылать сообщение с тем же текстом тому же адресату
• Ошибка транспорта
• Данное направление не подключено
• Данное направление не подключено у вышестоящего контрагента
• Сообщение не прошло модерацию 1
• Сообщение не прошло модерацию 2
• Данная подпись отпраавтеля не подтверждена
• Отправка в данный период времени запрещена настройками Вашего ЛК
• Статус "не удалось доставить сообщение" получен от оператора

Получение статусов сообщений на свой URL

При получении финального статуса по каждой из отправленных SMS на Ваш URL адрес, указанный в настройках ("Личный кабинет \ Настройки \ URL скрипта для приёма статуса отправленных SMS"), по HTTP протоколу методом POST будет передан запрос, содержащий JSON данные с заголовком Content-Type: application/json;charset=utf-8.
Если Ваш сервер не вернул корректный HTTP-статус, то будет осуществлено несколько попыток отправки финального статуса сообщения по следующей логике:
2 попытка через 5 минут после предыдущей, если она завершилась не корректно;
3 попытка через 10 минут после предыдущей, если она завершилась не корректно;
4 финальная попытка через 15 минут после предыдущей, если она завершилась не корректно;
Ваш скрипт должен вернуть HTTP-статус - 200 OK (успешный запрос).
Содержимое объекта JSON:

Получение текущего баланса

Структура POST-запроса к http-серверу для получения баланса пользователя (определить, что идет запрос на получение текущего баланса можно по полю [action] => balance):

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_balance" err="">
	<result currency="RUB">
	<account>XXX.XX</account>
	<overdraft>XX.XX</overdraft>
	</result>
</xml_result>
</output>

Получение входящих сообщений

Структура POST-запроса к http-серверу для получения входящих сообщений (определить, что идет запрос на получение входящих сообщений можно по полю [action] => inbox):

Получение списка доступных имен отправителей

Структура POST-запроса к http-серверу для получения списка доступных имен отправителей (определить, что идет запрос на получение списка доступных имен отправителей можно по полю [action] => senderlist):

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_senderlist" err="">
	<result any=TRUE/FALSE>
	<sender status="requested/activated/rejected" default=TRUE/FALSE>NAME_1</sender>
	<sender status="requested/activated/rejected" default=TRUE/FALSE>NAME_2</sender>
	…
	</result>
</xml_result>
</output>

Получение списка групп контактов

Структура POST-запроса к http-серверу для получения списка групп контактов (определить, что идет запрос на получение списка групп контактов можно по полю [action] => baselist):

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_baselist" err="">
	<result>
	<base base_id="XXXXX" size="количество номеров в базе">NAME_1</base>
	<base base_id="XXXXX" size="количество номеров в базе">NAME_2</base>
	…
	</result>
</xml_result>
</output>

Получение списка абонентов в группе контактов

Структура POST-запроса к http-серверу для получения списка абонентов в группе контактов (определить, что идет запрос на получение списка абонентов в группе контактов можно по полю [action] => numberlist):

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_numberlist" err="">
	<result page="1" num_pages="количество страниц всего" base="NAME_1" base_id="XXXXX" size="количество номеров в базе">
	<phone number="7XXXXXXXXXX" name="Имя" surname="Фамилия" patronymic="Отчество" show_name="Имя для отображения" gender="Пол" position="Должность" email="Электронная почта"
	date_of_birth="Дата рождения в виде дд.мм.гггг" add_field_1="Дополнительное поле 1" add_field_2="Дополнительное поле 2" comment="Примечание"></phone>
	<phone number="7XXXXXXXXXX" name="Имя" surname="Фамилия" patronymic="Отчество" show_name="Имя для отображения" gender="Пол" position="Должность" email="Электронная почта"
	date_of_birth="Дата рождения в виде дд.мм.гггг" add_field_1="Дополнительное поле 1" add_field_2="Дополнительное поле 2" comment="Примечание"></phone>
	…
	</result>
</xml_result>
</output>

Добавление/Редактирование абонентов в группе контактов

Структура POST-запроса к http-серверу для добавления/редактирования абонентов в группе контактов (определить, что идет запрос на добавление/редактирование абонентов в группе контактов можно по полю [action] => numberedit):

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_numberedit" err="">
	<result base="NAME_1" base_id="XXXXX">
	<phone number="7XXXXXXXXXX" err="">added</phone>
	<phone number="7XXXXXXXXXX" err="">edited</phone>
	…
	</result>
</xml_result>
</output>

Удаление абонентов из группы контактов

Структура POST-запроса к http-серверу для удаления абонентов из группы контактов (определить, что идет запрос на удаление абонентов из группы контактов можно по полю [action] => numberdel):

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_numberdel" err="">
	<result base="NAME_1" base_id="XXXXX">
	<phone number="7XXXXXXXXXX" err="">deleted</phone>
	<phone number="7XXXXXXXXXX" err="">absent</phone>
	…
	</result>
</xml_result>
</output>

Получение списка запрещенных номеров

Структура POST-запроса к http-серверу для получения списка запрещенных номеров (определить, что идет запрос на получение списка запрещенных номеров можно по полю [action] => stoplist):

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_stoplist" err="">
	<result page="1" num_pages="количество страниц всего" size="количество запрещенных номеров всего">
	<phone number="7XXXXXXXXXX"></phone>
	<phone number="7XXXXXXXXXX"></phone>
	…
	</result>
</xml_result>
</output>

Добавление запрещенных номеров

Структура POST-запроса к http-серверу для добавления запрещенных номеров (определить, что идет запрос на добавление запрещенных номеров можно по полю [action] => stopadd):

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_stopadd" err="">
	<result>
	<phone number="7XXXXXXXXXX" err="">added</phone>
	<phone number="7XXXXXXXXXX" err="">present</phone>
	…
	</result>
</xml_result>
</output>

Добавление абонентов в группу контактов (через загрузку файла)

Структура POST-запроса к http-серверу для добавления абонентов в группу контактов через загрузку файла (определить, что идет запрос на добавление абонентов в группу контактов через загрузку файла можно по полю [action] => numberaddfile):

ВАЖНО: номера телефонов в добавляемом файле должны быть представлены в международном формате без символа "+" (например: 7XXXXXXXXXX)

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_numberaddfile" err="">
	<result base="NAME_1" base_id="XXXXX">
	<added>количество добавленных номеров</added>
	<skipped>количество пропущенных номеров</skipped>
	</result>
</xml_result>
</output>

Добавление запрещенных номеров (через загрузку файла)

Структура POST-запроса к http-серверу для добавления запрещенных номеров через загрузку файла (определить, что идет запрос на добавление запрещенных номеров через загрузку файла можно по полю [action] => stopaddfile):

При добавлении запрещенных номеров (через загрузку файла) все дубли пропускаются

ВАЖНО: номера телефонов в добавляемом файле должны быть представлены в международном формате без символа "+" (например: 7XXXXXXXXXX)

<?xml version="1.0" encoding="UTF-8"?>
<output>
<xml_result action="http_post_stopaddfile" err="">
	<result>
	<added>количество добавленных номеров</added>
	<skipped>количество пропущенных номеров</skipped>
	</result>
</xml_result>
</output>

Номера телефонов в любых типах запросов должны быть представлены в международном формате без символа "+" (например: 7XXXXXXXXXX)

Использование протокола НТТP (GET-запросы) для отправки и приема смс сообщений

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

Список параметров:

Пример отправляемого запроса:

https://web.smsgold.ru/http2/?user=LOGIN&pass=PASSWORD&sender=SENDERNAME&number=79XXXXXXXXX&text=ТЕКСТ+ВАШЕЙ+СМС

Корректный ответ сервера при отправке сообщения:

XXXXXXXXXXX

или

XXXXXXXXXXX,XXXXXXXXXXX,XXXXXXXXXXX,...

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

Проверка статуса

Список параметров

Пример отправляемого запроса:

https://web.smsgold.ru/http2/?user=LOGIN&pass=PASSWORD&smsid=XXXXXXXXXXX

При успешной обработке HTTP-запроса сервером в ответ придет статус смс сообщения с запрошенным smsid.

Возможные статусы:

QUEUED  - сообщение находится в обработке на нашей стороне
ENROUTE - сообщение отправлено оператору
DELIVRD - сообщение успешно доставлено
EXPIRED - время жизни сообщения истекло
DELETED - сообщение удалено
UNDELIV - не удалось доставить сообщение
ACCEPTD - сообщение принято и будет отправлено оператору
UNKNOWN - состояние сообщения не определено
REJECTD - сообщение отклонено

Проверка информации о балансе

https://web.smsgold.ru/http2/?user=LOGIN&pass=PASSWORD&action=balance