PromoSMS - сервис рассылки смс, e-mail, прием входящих смс

HTTP/HTTPS API

Инструкции по подключению

к SMS- шлюзу PromoSMS

HTTP протокол


Описание отсылки сообщений через протокол HTTP.

Адрес обращения: http://sms.promosms.ru:26676/smw/aisms или https://sms.promosms.ru/smw/aisms (корневой сертификат можно получить по ссылке).

Тип авторизации: PLAIN (открытым текстом).

Формат входных данных: Content-Type: application/x-www-form-urlencoded; charset=windows-1251 (по умолчанию).

При использовании другой кодировки, отличной от windows-1251, требуется указать её в заголовке Content-Type запроса.

Например: Content-Type: application/x-www-form-urlencoded; charset=UTF-8

Результат: Content-Type: text/xml, кодировка: UTF-8; content-encoding: gzip (опционально)

Login/password: уникальные login/password выданные Вам при регистрации

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

Резервные адреса:

http://109.248.231.254:26676

http://92.50.156.138:26676

Входные данные

Авторизация

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

user - Уникальный логин, переданный Вам при регистрации

pass - Пароль, переданный Вам при регистрации

gzip=none - Не использовать content-encoding: gzip


Отправка SMS

action = post_sms

message - текст сообщения

target - адресаты. Список через запятую. Например: +79171234567, 79057654321

sender - имя отправителя зарегистрированного для вас в системе. NULL = подставить имя отправителя по умолчанию.


Получение данных и статусов сообщений:

action = status

sms_id = уникальный идентификатор SMS, назначенный при отправке.

Получение баланса

action = balance


Примеры запросов/ ответов

Пример 1. Отправка сообщения адресатам

POST= (

[user] => userX

[pass] => blabla

[action] => post_sms

[message] => test message

[target] => +79171234567,79057654321, 1 ,zz

)

Примерный вид сгенерированного запроса:

action=post_sms&user=userX&pass=blabla&sender=NULL&target=%2B79171234567%2C79057654321%2C1%2Czz&message=test+message

Результат XML

<output>

<result>

<sms id="8535020" phone="79171234567"/>

<sms id="8535021" phone="79057654321"/>

</result>

<errors>

<error phone="1">Неправильный номер телефона: 1</error>

<error phone="zz">Неправильный номер телефона: zz</error>

</errors>

</output>


Атрибут id - это уникальный идентификатор сообщения, назначенный при отправке.

Номера телефонов очищаются от мусорных символов (+, -, скобки, пробелы)


Пример 2. Получение данных сообщения id=8535020

POST= ( [action] => status [sms_id] => 8535020 [user] => userX [pass] => blabla )


Примерный вид сгенерированного запроса:

user=userX&pass=blabla&sms_id=8535020&action=status


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

a) В процессе доставки

<output>

<MESSAGES>

<MESSAGE SMS_ID="8535020">

<SMS_STATUS>1000000</SMS_STATUS>

<SMSSTC_CODE>queued</SMSSTC_CODE>

<SMS_SENT>0</SMS_SENT>

</MESSAGE>

</MESSAGES>

</output>


b) Доставлено

<output>

<MESSAGES>

<MESSAGE SMS_ID="8535020">

<SMS_STATUS>2000000</SMS_STATUS>

<SMS_CLOSE_TIME>30.04.10 00:01:07</SMS_CLOSE_TIME>

<sent_dt>100430000050916+</sent_dt>

<SMSSTC_CODE>delivered</SMSSTC_CODE>

<SMS_SENT>1</SMS_SENT>

</MESSAGE>

</MESSAGES>

</output>


Данные по сообщению:

SMS_ID - ID сообщения

SMS_STATUS - hex значения полей message_state (согласно SMPP API v5 раздел 4.7.15) и network_error_code

SMSSTC_CODE - Код статуса доставки сообщения

SMS_SENT - 0 - сообщение в процессе доставки/не доставлено, 1 = сообщение доставлено абоненту

SMS_CLOSE_TIME - дата и время прихода отчета о доставке - окончание работ по данному сообщению.

sent_dt - первая попытка доставки SMS абоненту


SMSSTC_CODE - Код статуса доставки сообщения

Код

Описание

queued

сообщение в очереди отправки

wait

передано в SMSC на отправку - в очереди отправки SMSC

accepted

(редко) был получен промежуточный отчет от SMSC -

сообщение в очереди отправки SMSC

delivered

сообщение доставлено на телефон

failed

ошибка при работе по сообщению

expired

время на попытку доставки смс истекло

Статусы SMS-сообщений

Информация о статусе SMS-сообщений поступает от SMS-центров, через которые происходит отправка сообщений абоненту. При получении информации от находящихся за рубежом SMS-центров статус SMS-сообщения иногда может быть некорретным.


Для проверки статуса отправленного сообщения вызывается команда:

gsmstat <Уникальный референс отправленного сообщения>


В ответ сервис выдает строку вида:

250 <код статуса> <дата доставки и краткая расшифровка статуса>\r\n


При запросе статуса командой gsmstat

Значение кода статуса

2

Доставлено до абонента.

7

Доставлено до абонента после его недоступности.

3

Не доставлено за установленное оператором время.

5

Не может быть доставлено, номер не существует.

8

Не может быть доставлено, номер в черных списках оператора.

-1

Не доставлено до абонента.


Любое SMS-сообщение достигает окончательного статуса не более чем, через 24 часа после отправки.

Формат номера телефона

Номер телефона абонента должен соответствовать рекомендации E.164 от ITU-T, определяющей общий международный телекоммуникационный план нумерации. Номера по E.164 могут иметь максимум 15 цифр и обычно записываются с префиксом «+». При отправке SMS-сообщений префикс можно «+» можно не указывать, сразу указывая код страны.


7

916

1112233

Код страны

Код оператора

Номер телефона


Например, 79161112233 (здесь 7 – код России и Казахстана, 916 – код оператора, 1112233 – номер телефона). В том случае, если у абонента прямой городской номер, телефон абонента пишется также в международном формате, с указанием кода города. Например, для прямых Московских номеров: 70951112233. Исключение составляют абоненты Билайн Москва (и только они). Все телефоны абонентов Билайн передаются как 7903xxxxxxx (даже, если телефон прямой московский).

Пример сотового номера Армении:

374

9

1112233

Код страны

Код оператора

Номер телефона

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

972

54

1112233

Код страны

Код оператора

Номер телефона