Структура 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 символов.
Авторизация
Авторизация требуется при каждом подключении к серверу независимо от дальнейших действий.
| Параметр | Значение |
|---|---|
| [user] | зарегистрированное в системе ID пользователя вида XXXXX или ХХХХХ.X |
| [pass] | пароль пользователя |
Отправка сообщения
Параметры передачи смс http-серверу в виде POST-запроса (определить, что идет отправка SMS можно по полю [action] => send):
| Параметр | Значение |
|---|---|
| [action] | send |
| [text] | текст сообщения |
| [number] | номер или список телефонных номеров получателей SMS в международном формате через запятую
(Разрешается использование как [number], так и [base_id]) |
| [base_id] | кодовое имя Группы контактов из Адресной книги в Личном кабинете
(Разрешается использование как [number], так и [base_id]) |
| [sender] | имя отправителя (если оставить пустым или параметр отсутствует - будет использовано имя отправителя, зарегистрированное по умолчанию в Личном кабинете) |
| [validity_period] | время жизни смс в минутах - максимальное время, в течение которого сообщение должно быть доставлено на телефон. Если в течение этого времени доставка не возможна (например абонент не в зоне действия сети или телефонный аппарат абонента выключен), то сообщение доставлено не будет и получит статус "просрочено". Внимание, данная функция может не работает для некоторых направлений, например для CDMA телефонов. (необязательный параметр, значение по умолчанию: 1440 минут (24 часа)) |
| [time_period] | период отправки сообщения в формате "H:i-H:i" (час:мин-час:мин), в течение которого сообщение должно быть доставлено получателям (например 10:00-21:00). Опция позволяет запретить доставку сообщений, например, в ночное время. Для указанного периода времени можно уточнить часовой пояс в [time_local] |
| [time_local] | выбор часового пояса для опции [time_period]:
1 - по местному время получателя 0 - по часовому поясу, выбранному в личном кабинете отправителя (значение по умолчанию) |
| [autotrimtext] | on - обрезать все пробелы и переводы строк в начале и конце сообщения (значение по умолчанию - off) |
| [sms_type] | тип SMS:
пустое значение или параметр отсутствует - простое SMS (значение по умолчанию) W - wap push сообщение F - flash SMS сообщение |
| [wap_url] | HTTP ссылка из текста сообщения (http://some.address.url) используется только для [sms_type] => W, то есть для wap push сообщения |
Пример запроса к серверу для отправки текста на один номер (развернуть)...
Пример запроса на 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):
| Параметр | Значение |
|---|---|
| [action] | status |
| Три варианта получения статусов для сообщений: | |
| [sms_id] | номер сообщения (соответствует значению атрибута sms_id тэга <sms>, возвращаемого при отправке сообщения) |
| [sms_group_id] | номер рассылки (соответствует значению атрибута sms_group_id тэга <result>, возвращаемого при отправке сообщений) |
| [date_from] [date_to] |
данные по всем сообщениям за период времени от [date_from] до [date_to]
формат date_from, date_to: "d.m.Y H:i:s" (дд.мм.гггг час:мин:сек) период не должен быть больше 4 дней до текущей даты |
Возможные статусы:
QUEUED - сообщение находится в обработке на нашей стороне ENROUTE - сообщение отправлено оператору DELIVRD - сообщение успешно доставлено EXPIRED - время жизни сообщения истекло DELETED - сообщение удалено UNDELIV - не удалось доставить сообщение ACCEPTD - сообщение принято и будет отправлено оператору UNKNOWN - состояние сообщения не определено REJECTD - сообщение отклонено
Пример ответа сервера на запрос статуса смс по [sms_id] (развернуть)...
<?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>
Пример ответа сервера на запрос статуса смс по [sms_group_id] (развернуть)...
<?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>
Пример ответа сервера на запрос статуса смс по [date_from] и [date_to] (развернуть)...
<?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:
| Параметр | Значение |
|---|---|
| [user] | зарегистрированное в системе ID пользователя вида XXXXX или ХХХХХ.X |
| [sms_id] | номер сообщения (соответствует значению атрибута sms_id тэга <sms>, возвращаемого при отправке сообщения) |
| [number] | номер телефонного номера получателя SMS в международном формате |
| [sender] | имя отправителя |
| [parts] | количество частей SMS |
| [err] | номер ошибки, возникшей при отправке, если ошибки нет, то err=null либо err="0" |
| [status] | финальный статус SMS |
| [description] | описание статуса |
| [delivery_date] | дата доставки в формате "d.m.Y" (дд.мм.гггг) |
| [delivery_time] | время доставки в формате "H:i:s" (час:мин:сек) |
Получение текущего баланса
Структура POST-запроса к http-серверу для получения баланса пользователя (определить, что идет запрос на получение текущего баланса можно по полю [action] => balance):
| Параметр | Значение |
|---|---|
| [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):
| Параметр | Значение |
|---|---|
| [action] | inbox |
| [inbox_num] | номер входящего ящика (обязательный параметр) (соответствует значению "ID ящика" в закладке "Настройки") |
| [inbox_new] | статус сообщений:
1 - только новые непрочитанные сообщения 0 - все сообщения |
| [date_from] [date_to] |
данные по всем сообщениям за период времени от [date_from] до [date_to]
формат date_from, date_to: "d.m.Y H:i:s" (дд.мм.гггг час:мин:сек) период не должен быть больше 4 дней до текущей даты |
Получение списка доступных имен отправителей
Структура POST-запроса к http-серверу для получения списка доступных имен отправителей (определить, что идет запрос на получение списка доступных имен отправителей можно по полю [action] => senderlist):
| Параметр | Значение |
|---|---|
| [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):
| Параметр | Значение |
|---|---|
| [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):
| Параметр | Значение |
|---|---|
| [action] | numberlist |
| [base_id] | кодовое имя группы (задается в настройках базы в личном кабинете) |
| [base_page] | номер страницы, весь список номеров базы делится на страницы (на одной странице выводится 1000 записей), запросить целиком базу нельзя, можно лишь запросить отдельную страницу, нумерация начинается с единицы. |
Пример ответа сервера на запрос (развернуть)...
<?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):
| Параметр | Значение |
|---|---|
| [action] | numberedit |
| [base_id] | кодовое имя группы (задается в настройках базы в личном кабинете) |
| [number] | номер телефона абонента в международном формате (обязательное поле), если абонент с таким номером уже существует, то он будет отредактирован с учетом указанных необязательных полей |
| [name] | имя (необязательное поле) |
| [surname] | фамилия (необязательное поле) |
| [patronymic] | отчество (необязательное поле) |
| [show_name] | имя для отображения (необязательное поле) |
| [gender] | пол (необязательное поле) |
| [position] | должность (необязательное поле) |
| [email] | электронная почта (необязательное поле) |
| [date_of_birth] | дата рождения в виде дд.мм.гггг (необязательное поле) |
| [add_field_1] | дополнительное поле 1 (необязательное поле) |
| [add_field_2] | дополнительное поле 2 (необязательное поле) |
| [comment] | примечание (необязательное поле) |
Пример ответа сервера на запрос (развернуть)...
<?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):
| Параметр | Значение |
|---|---|
| [action] | numberdel |
| [base_id] | кодовое имя группы (задается в настройках базы в личном кабинете) |
| [number] | номер телефона абонента в международном формате (обязательное поле) |
Пример ответа сервера на запрос (развернуть)...
<?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):
| Параметр | Значение |
|---|---|
| [action] | stoplist |
| [base_page] | номер страницы, весь список запрещенных номеров делится на страницы (на одной странице выводится 1000 записей), запросить целиком список нельзя, можно лишь запросить отдельную страницу, нумерация начинается с единицы. |
Пример ответа сервера на запрос (развернуть)...
<?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):
| Параметр | Значение |
|---|---|
| [action] | stopadd |
| [number] | номер телефона абонента в международном формате (обязательное поле) |
Пример ответа сервера на запрос (развернуть)...
<?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):
| Параметр | Значение |
|---|---|
| [action] | numberaddfile |
| [base_id] | кодовое имя группы (задается в настройках базы в личном кабинете) |
| [file] | путь к файлу |
| [file_type] | тип файла (csv / txt / xls / xlsx / auto) (значение auto - по умолчанию) |
| [delimiter] | разделитель полей (, / ; / auto) (значение auto - по умолчанию) |
| [encoding] | кодировка файла (utf8 / cp1251 / koi8r / auto) (значение auto - по умолчанию) |
| [remove_doubles] | поведение при обнаружении дублей в файле и в базе:
true - не добавлять дублирующиеся номера, попадающиеся в файле и в базе (значение по умолчанию) false - добавлять дублирующиеся номера, попадающиеся в файле и добавлять номер если он уже присутствует в базе |
| [headers] | перечисление через запятую заголовков колонок в порядке их очередности в файле:
"number,name,surname,patronymic,show_name,gender, position,email,date_of_birth,add_field_1,add_field_2,comment" если поле отсутствует - указывать не нужно |
| Список допустимых колонок данных: | |
| [number] | номер телефона абонента в международном формате (обязательное поле) |
| [name] | имя (необязательное поле) |
| [surname] | фамилия (необязательное поле) |
| [patronymic] | отчество (необязательное поле) |
| [show_name] | имя для отображения (необязательное поле) |
| [gender] | пол (необязательное поле) |
| [position] | должность (необязательное поле) |
| [email] | электронная почта (необязательное поле) |
| [date_of_birth] | дата рождения в виде дд.мм.гггг (необязательное поле) |
| [add_field_1] | дополнительное поле 1 (необязательное поле) |
| [add_field_2] | дополнительное поле 2 (необязательное поле) |
| [comment] | примечание (необязательное поле) |
ВАЖНО: номера телефонов в добавляемом файле должны быть представлены в международном формате без символа "+" (например: 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):
| Параметр | Значение |
|---|---|
| [action] | stopaddfile |
| [file] | путь к файлу |
| [file_type] | тип файла (csv / txt / xls / xlsx / auto) (значение auto - по умолчанию) |
| [delimiter] | разделитель полей (, / ; / auto) (значение auto - по умолчанию) |
| [encoding] | кодировка файла (utf8 / cp1251 / koi8r / auto) (значение auto - по умолчанию) |
При добавлении запрещенных номеров (через загрузку файла) все дубли пропускаются
ВАЖНО: номера телефонов в добавляемом файле должны быть представлены в международном формате без символа "+" (например: 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)