ePochta SMS API (v. 2.0) — Инструкции по подключению к удалённому СМС шлюзу
image image

ePochta SMS API (v. 2.0)

Базовые положения

Для активации СМС шлюза необходимо в панели управления сервисом ePochta SMS в «Настройках» активировать использование API. Для этого в пункте «XML интерфейс включен» необходимо выбрать пункт «Да». В пункте «XML интерфейс: режим работы» выбрать либо «Реальная отправка», либо «Тестовый режим».

В случае выбора режима «Реальной отправки» сообщения будет отправлены незамедлительно после поступления запроса на шлюз. В случае выбора «Тестового режима» сообщения отправлены не будут. Но будут созданы задачи со статусом «Не готово». Это свидетельствует о том, что было успешное подключение к шлюзу и данные на сервер были переданы.

Отправка СМС

Отправка СМС происходит путем POST запроса на скрипт.
В передаваемом POST параметре ‘XML’ находится собственно XML документ следующей структуры:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<SMS>
<operations>
<operation>SEND</operation>
</operations>
<authentification>
<username></username>
<password></password>
</authentification>
<message>
<sender></sender>
<text></text>
</message>
<numbers>
<number></number>
<number></number>
<number messageID="msg11"></number>
<number messageID="msg12" variables="var1;var2;var3;"></number>
</numbers>
</SMS>

Список параметров:
<operation> – для данной операции должен быть установлен в SEND.
<username> – логин пользователя в системе SMS Sender.
<password> – пароль пользователя в системе SMS Sender.
<sender> – отправитель СМС. 14 цифровых символов или 11 цифробуквенных (английские буквы и цифры).
<text> – текст SMS.

Специальные параметры для рассылки по России

В разделе <numbers> задаются номера получателей (более одного). Если Вы хотите использовать слежение за статусом SMS, установите для каждого номер атрибут messageID , в дальнейшем он будет использоваться при запросе статуса сообщения. Атрибут variables в теге <number> служит для персонализации рассылки. Выглядит персонализированная рассылка примерно следующим образом (фрагмент XML):

1
2
3
4
5
6
7
8
<message>
<sender>SMSKA</sender>
<text><![CDATA[Hello %1% I’ve bought you %2%]]></text>
</message>
<numbers>
<number messageID="msg11" variables="John; a car;"></number>
<number messageID="msg12" variables="Peter;cookies;"></number>
</numbers>

Первая SMS на телефоне получателя будет иметь вид “Hello John I’ve bought you a car”, вторая как “Hello Peter I’ve bought you cookies”.

В ответ будет получен XML примерно такого содержания:

1
2
3
4
<RESPONSE>
<status>status_code</status>
<credits></credits>
</RESPONSE>

Статус

Значение

Описание

AUTH_FAILED

-1

Неправильный логин и/или пароль

XML_ERROR

-2

Неправильный формат XML

NOT_ENOUGH_CREDITS

-3

Недостаточно кредитов на аккаунте пользователя

NO_RECIPIENTS

-4

Нет верных номеров получателей

INVALID_TEXT

-5

Неверный текст

BAD_SENDER_NAME

-7

Ошибка в имени отправителя

SEND_OK

> 0

Количество отправленных SMS.

Параметр <credits> будет указывать, сколько кредитов было снято за рассылку сообщений.

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

Список параметров аналогичен п. 1, единственным отличием является то, что <operation> – для данной операции должна быть установлена в GETPRICE.

В ответ будет получен XML примерно такого содержания:

1
2
3
4
<RESPONSE>
<status>status_code</status>
<credits></credits>
</RESPONSE>

Статус

Значение

Описание

AUTH_FAILED

-1

Неправильный логин и/или пароль

ОК

0

Запрос верный

XML_ERROR

-2

Неправильный формат XML

В параметре <credits> будет указано количество кредитов, необходимых для отправки рассылки.

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

Получение статуса происходит путем POST запроса на скрипт. В передаваемом POST параметре ‘XML’ находится собственно документ следующей структуры:

1
2
3
4
5
6
7
8
9
10
11
12
13
<SMS>
<operations>
<operation>GETSTATUS</operation>
</operations>
<authentification>
<username></username>
<password></password>
</authentification>
<statistics>
<messageid></messageid>
<messageid></messageid>
</statistics>
</SMS>

Ответом на это будет XML следующего содержания:

1
2
3
4
5
<deliveryreport>
<message id="msgID" sentdate="xxxxx" donedate="xxxxx" status="xxxxxx"/>
<message id="msgID" sentdate="xxxxx" donedate="xxxxx" status="xxxxxx"/>
.....
</deliveryreport>

Статус

Описание

SENT

Отослано

NOT_DELIVERED

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

DELIVERED

Доставлено

NOT_ALLOWED

Оператор не обслуживается

INVALID_DESTINATION_ADDRESS

Неверный адрес для доставки

INVALID_SOURCE_ADDRESS

Неправильное имя «От кого»

NOT_ENOUGH_CREDITS

Недостаточно кредитов

Даты приходят в формате yyyy-mm-dd hh:mm:ss

Получение текущего баланса пользователя

Отправка СМС происходит путем POST запроса на скрипт.
В передаваемом POST параметре ‘XML’ находится собственно документ следующей структуры:

1
2
3
4
5
6
7
8
9
<SMS>
<operations>
<operation>BALANCE</operation>
</operations>
<authentification>
<username></username>
<password></password>
</authentification>
</SMS>

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

1
2
3
4
<operation> <strong> - </strong>
для данной операции должна быть установлена в BALANCE.
<username> - логин пользователя в системе SMS Sender.
<password> - пароль пользователя в системе SMS Sender.

В ответ будет получен XML примерно такого содержания:

1
2
3
4
<RESPONSE>
<status>status_code</status>
<credits></credits>
</RESPONSE>

Статус

Значение

Описание

AUTH_FAILED

-1

Неправильный логин и/или пароль

ОК

0

Запрос верный

XML_ERROR

-2

Неправильный формат XML

В параметре credits будет указано количество кредитов на балансе пользователя

Получение стоимости одного кредита

Отправка СМС происходит путем POST запроса на скрипт. В передаваемом POST параметре ‘XML’ находится собственно документ следующей структуры:

1
2
3
4
5
6
7
8
9
<SMS>
<operations>
<operation>CREDITPRICE</operation>
</operations>
<authentification>
<username></username>
<password></password>
</authentification>
</SMS>

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

1
2
3
4
<operation><strong> - </strong>
для данной операции должна быть установлена в CREDITPRICE.
<username> - логин пользователя в системе SMS Sender.
<password> - пароль пользователя в системе SMS Sender.

В ответ будет получен XML примерно такого содержания:

1
2
3
4
<RESPONSE>
<status>status_code</status>
<price></price>
</RESPONSE>

Статус

Значение

Описание

AUTH_FAILED

-1

Неправильный логин и/или пароль

ОК

0

Запрос верный

XML_ERROR

-2

Неправильный формат XML

В параметре <price> будет установлена цена 1 кредита в долларах США.

Пример использования API на языке программирования PHP. Подробно

vector
image

Нужна помощь?

Задайте вопрос специалисту технической поддержки