SMS API для рассылки СМС-сообщений

Описание SMS HTTP API шлюза

Отправка запросов к шлюзу осуществляется методом GET или POST.

Рекомендуется использовать POST запрос.

Для аутентификации запросов к шлюзу используется уникальный API-ключ. Получить API-ключ.

Для использования защищенного SSL соединения, запросы необходимо отправлять по протоколу HTTPS методом POST.

Все запросы производятся на следующий адрес:

http://smsapi.ru/ru/sms/api/

По умолчанию ответ сервера происходит в формате JSON. Для выбора другого вида формата ответа используется параметр format

Отправка SMS

Для отправки SMS необходимо передать следующие параметры по адресу шлюза:

Параметр=Значение	Описание
action=sendsms	Обязательный параметр, указывающий действие по отправке SMS-сообщения.
apikey=<api-ключ>	Обязательный параметр. API-ключ в системе. Используется для аутентификации запроса к системе.
phones=<+номер_телефона>	Номер телефона получателя SMS в международном формате или список номеров, разделенных пробелом или запятой. Например: +79123456789 или 79123456789, +380123456789 или 380123456789 для списка номеров: 79123456789,79123456780,79123456790
message=<сообщение>	Текс SMS сообщения. Максимальный размер – 800 символов. Сообщение при необходимости будет разбито на несколько SMS, отправленных абоненту и оплаченных по отдельности. Размер одного SMS – 160 символов в латинице или 70 символов в кириллице. При разбивке сообщения на несколько SMS в каждую часть добавляется заголовок для объединения частей в одно сообщение на телефоне получателя, и максимальная длина становится 67 для кириллицы и 153 для латинских букв.
sender=<отправитель>	Имя отправителя, отображаемое в телефоне получателя. Разрешены английские буквы, цифры, пробел и некоторые символы. Длина – 11 символов или 15 цифр. Все имена регистрируются в личном кабинете. Динамическое имя включается по запросу. Для отключения Sender ID по умолчанию необходимо в качестве имени передать пустую строку.
id=<идентификатор>	Идентификатор сообщения. Назначается Клиентом. Служит для дальнейшей идентификации сообщения. Если не указывать, то будет назначен автоматически. Не обязательно уникален. В случае 2-х одинаковых идентификаторов по запросу статуса будет возвращен статус последнего сообщения. Идентификатор представляет собой 32-битное число в диапазоне от 1 до 2147483647.
translit=<0 или 1>	Транслитерация сообщения. Возможные значения: 0 - нет, выключено (по умолчанию) 1 - вкючено
charset=<utf8, cp1251>	Кодировка переданного сообщения, если используется отличная от кодировки по умолчанию utf8 Возможные значения: utf8 - Unicode cp1251 - кодировка Windows

Пример запроса для отправки SMS:

http://smsapi.ru/ru/sms/api/?action=sendsms&apikey=myapikey&phones=79121231234&message=it+is+only+test&sender=brand

Пример успешного ответ сервера:

{"status": "success", "phone": "79121231234, "id": "189"}

Пример ответа сервера с ошибкой:

{"status": "error", "error_code": "15", "error": "Error: Wrong phone"}

Коды статусов сообщения и ошибок

Все коды объединены в общую таблицу. Описание статуса или ошибки доступно на двух языках и зависит от того какая локаль указана в адресе запроса к шлюзу.

Код	Описание	Описание (localized)
0	Waiting for process	Ожидает процесса
1	Waiting for delivery	Ожидает доставку
2	Successfully delivered	Успешно доставлено
3	Unknown status	Неизвестный статус
10	Error: Auth failed	Ошибка: аутентификация не прошла
11	Error: Low balance	Error: Low balance
12	Error: IP blocked	Ошибка: IP заблокирован
13	Error: Repeated request	Error: Repeated request
14	Error: Wrong date format	Error: Wrong date format
15	Error: Wrong phone	Error: Wrong phone
16	Error: Wrong action	Error: Wrong action
17	Error: Can not get price	Error: Can not get price
20	Error: Not found message	Error: Not found message
21	Error: Expired message	Error: Expired message
22	Error: Deny for message or sender	Error: Deny for message or sender
23	Error: Can not be delivered	Error: Can not be delivered
24	Error: No route to phone	Error: No route to phone
30	Error: Gate error low balance	Error: Gate error low balance
31	Error: User is suspended	Ошибка: Работа пользователя приостановлена

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

Параметр=Значение	Описание
action=status	Обязательный параметр, указывающий действие по получению статуса SMS-сообщения.
apikey=<api_ключ>	Обязательный параметр. API-ключ в системе. Используется для аутентификации запроса к системе.
id=<id_сообщения>	Идентификатор сообщения, полученный после отправки SMS-сообщения.

Пример запроса:

http://smsapi.ru/ru/sms/api/?action=status&apikey=myapikey&id=189

Пример ответа в формате JSON:

{"status": "Successfully delivered", "status_code": "2", "id": "189"}

Информация о балансе

action=balance	Обязательный параметр, указывающий действие по получению информации о балансе.
apikey=<api_ключ>	Обязательный параметр. API-ключ в системе. Используется для аутентификации запроса к системе.

Пример запроса:

http://smsapi.ru/ru/sms/api/?action=balance&apikey=myapikey

Пример ответа в формате JSON:

{"balance": {"currency": "RUB", "amount": 29.3}}

Типы валют:

RUB, USD, EUR, UAH

Определение страны, тарифа и стоимости SMS по номеру телефона

Запрос позволяет получить полную информацию о номере телефона, включая страну, стоимость отправки одной SMS и тарифную зону.

Параметр=Значение	Описание
action=country	Текущее действие
apikey=<api_ключ>	API ключ
phones=<+номер_телефона>	Телефон в международном формате

Пример запроса для получения страны, тарифа и стоимости одной SMS:

http://smsapi.ru/ru/sms/api/?action=country&apikey=myapikey&phones=79001234567

Пример успешного ответ сервера:

{"phone": {"national_number": 9001234567, "country_code": 7}, "tariff_price": 0.5, "country": "Россия", "price": 0.5, "tariff_currency": "RUB", "currency": "RUB", "country_code": "RU", "tariff_zone": "Russia", "tariff": "Start"}

Параметр	Описание
phone.national_number	Номер в национальном формате (без префикса страны)
phone.country_code	Телефонный код страны (без +)
phone=<+номер_телефона>
country	Полное название страны на языке, который использовался для формирования запроса к API шлюза (smsapi.ru/ru/... или smsapi.ru/en/...)
country_code	Сокращенный код страны в ISO стандарте
price	Стоимость одной SMS в валюте пользователя, конвертированная из валюты тарифа шлюза
currency	Валюта пользователя
tariff_price	Стоимость одной SMS в валюте тарифа шлюза
tariff_currency	Валюта тарифа шлюза
tariff	Название тарифа пользователя
tariff_zone	Название зоны в тарифе, к которой относится данный номер телефона.

Проверка стоимости SMS рассылки

Для проверки стоимости отправки SMS используйте те же параметры, что и для обычной отправки, но поменяйте значение action=cost

Пример запроса для проверки стоимости SMS (или рассылки):

http://smsapi.ru/ru/sms/api/?action=cost&apikey=myapikey&phones=79121231234&message=it+is+only+test&sender=brand

Пример успешного ответ сервера:

{"cost": {"currency": "RUB", "amount": 0.7}}

HLR- запросы

Данная возможность будет доступна в ближайшее время.

Длина SMS сообщения

Максимальная длина сообщения составляет 480 символов. SMS сообщение может быть составлено в двух форматах: Unicode (в том числе и русский язык) и 7bit (английский текст и большинство символов). Сообщение может состоять из одного или нескольких SMS.

Составные SMS сообщения

Подсчет количества SMS, содержащемся в одном Сообщении на основании введенного текста выполняется по формулам:

Unicode:

если длина <=70, то 1 SMS,

иначе, количество SMS определяется как: кол-во SMS = длина сообщения в символах / 67

(например, текст длиной 135 символов считается как 3 SMS сообщения).

7bit:

если длина <=160, то 1 SMS,

иначе количество SMS определяется как: кол-во SMS = длина сообщения в символах / 153

(например, текст длиной 310 символов считается как 3 SMS сообщения).