API / SMPP

Описание HTTPS API
обновлено 11 июля 2013
Подключение по SMPP
обновлено 11 июля 2013
Описание XML API
обновлено 11 июля 2013
Описание API

1. Передача одного sms сообщения

GET или POST запрос на сервер, вида:

https://500sms.ru/api.php?user=test&pass=test&from=test&text=text&to=790012345678

Вы можете сделать тестовую отправку запроса через браузер.

Кириллицу следует передавать в формате ‘url encoded’, например:

UTF-8: тест
url encoded: %D1%82%D0%B5%D1%81%D1%82
Параметр Статус Описание
user Обязательно Логин в системе
pass Обязательно Пароль
to Обязательно Номер телефона получателя, в формате 79123456789
text Обязательно Текст сообщения, в UTF-8 кодировке
from Обязательно Подпись отправителя (латиница до 11 или цифры до 14 символов)
date Не обязательно Дата для отложенной отправки сообщения, Unixtime (количество секунд с 1 января 1970 года) Если не указано, отправляется сразу после запроса

 
 

При успешной отправке, в ответ сервис должен вернуть text/xml ответ вида:

<response>

<status>accepted</status>

<sms id_sms=”604015283″>send</sms>

</response>

При ошибке:

<response>

<status>error</status>

<message>текстошибки</message>

</response>

 
Расшифровка ошибок:

Параметр Описание
accepted Сообщение принято сервисом
empty field. reject Не все обязательные поля заполнены
incorrect user or password. reject Ошибка авторизации
no credits Недостаточно sms на балансе
incorrect destination address. reject Неверно задан номер телефона (формат 71234567890)
incorrect date. reject Неправильный формат даты (только unixtime)
incorrect sender name. reject Неверная (неразрешенная) подпись отправителя

2. Передача множества sms сообщений

Если номеров несколько – они должны быть перечислены через запятую, без пробелов.

https://500sms.ru/api.php?user=test&pass=test&from=test&text=text&to=790012345678,790012345679,790012345680,79001234568

Рекомендуем не делать отправку более 80 сообщений за один запрос.
Это оптимальное значение.

3. Проверка состояния счета

GET/POST запрос на сервер, вида: 

https://500sms.ru/api.php?a=balance&user=test&pass=test
Параметр Статус Описание
user Обязательно Логин в системе
pass Обязательно Пароль

При успешной авторизации, в ответ сервис должен вернуть text/xml, где цифра – это количество SMS, доступных на балансе.

4. Запрос на получение списка баз

GET/POST запрос на сервер, вида:

https://500sms.ru/api.php?a=bases&user=test&pass=test

5. Запрос на получение списка абонентов указанной базы

GET/POST запрос на сервер, вида:

https://500sms.ru/api.php?a=list_phones&user=test&pass=test&baseid=74275&pageid=1

 

Параметр Статус Описание
user Обязательно Логин в системе
pass Обязательно Пароль
baseid Обязательно IDбазы. Посмотреть можно в личном кабинете или через API, запросив список баз.
pageid Обязательно Номер страницы

Весь список номеров базы делится на страницы. Запросить целиком базу нельзя, во избежание перегрузки системы запросом, т.к. базы могут быть достаточно большие, сотни тысяч записей. Можно лишь запросить отдельную страницу.

Нумерация начинается с 1.

6. Запрос на добавление или редактирование абонентов базы.

https://500sms.ru/api.php?a=phones&user=test&pass=test&baseid=999&phone=790012345678
Параметр Статус Описание
user Обязательно Логин в системе
pass Обязательно Пароль
baseid Обязательно Номер базы в системе.
phone Обязательно Номер телефона абонента. Если абонент с таким номером уже существует, то он будет отредактирован.
region Не обязательно Регион. Если не задано, определяется автоматически.
operator Не обязательно Оператор. Если не задано, определяется автоматически.
name Не обязательно Имя абонента
surname Не обязательно Фамилия абонента
patronymic Не обязательно Отчество абонента
date_birth Не обязательно Дата рождения
male Не обязательно Пол. «m» – мужской, «f» – женский.
addition_1 Не обязательно Первое дополнительное поле.
addition_2 Не обязательно Второе дополнительное поле.

7. Запросы для работы со стоп-листом абонентов.

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

7.1 Добавить в стоп-лист

https://500sms.ru/api.php?a=addstop&user=test&pass=test&phones=79001234567

или номера через запятую

7.2 Удалить из стоп-листа

https://500sms.ru/api.php?a=delstop&user=test&pass=test&phones=79001234567

или номера через запятую.

8. Запрос на получения статуса сообщения/сообщений.

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

https://500sms.ru/api.php?checkid=789105669&user=test&pass=test

Если Вы хотите узнать несколько статусов, перечислите ID сообщений через запятую:

https://500sms.ru/api.php?checkid=789105669,23545254&user=test&pass=test

В случае успешной доставки, Вы получите ответ:

sms id_sms="789105669" err="000" deliver sms
err="000" означает отсутствие ошибок.

Ниже приводим список возможных статусов и ошибок:

 

Description Описание
1 send Статус сообщения еще не получен от оператора абонента.
2 not_deliver Сообщение не было доставлено. Конечный статус (не меняется со временем).
3 expired Абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный статус (не меняется со временем).
4 deliver Сообщение доставлено. Конечный статус (не меняется со временем).
5 partly_deliver Сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки.

Если статус сообщения “not_deliver”, то параметр “err” имеет значение отличное от “000″.
Система может отдавать следующие коды ошибок получения сообщения абонентом

 

Description Описание
0 No errors Ошибок нет (или ошибка не может быть определена системой)
1 The subscriber is absent or out of a coverage Абонент недоступен или отключен
2 Call barred service activated У абонента включен запрет на прием сообщений или абонента заблокировал оператор (возможно, в связи с отрицательным балансом)
3 Unknown subscriber Номер телефона не существует или не обслуживается
4 Memory capacity exceeded Память телефона абонента переполнена
5 Equipment protocol error Аппаратная ошибка телефона абонента
6 Teleservice not provisioned Сервис коротких сообщений не предоставляется
7 Facility not supported Аппарат абонента не поддерживает прием коротких сообщений
8 Subscriber is busy Аппарат абонента занят операцией, препятствующей получению короткого сообщения
9 Roaming restrictions Абонент находится в роуминге
10 Timeout Время ожидания ответа от SMSC абонента истекло
11 SS7 routing error Внутренняя ошибка маршрутизации
12 Internal system failure Внутренняя ошибка системы абонента
13 SMSC failure Ошибка коммутатора (внутренняя ошибка передачи данных оператора)