SMSfeedback Расширенный API

Интерфейс прикладного программирования - Application programming interface (API) для интеграции с SMSfeedback.

Расширенный API, в отличие от Стандартного sms API использует POST запрос для отправки сообщений, что позволяет за один запрос отправить до 200 смс сообщений. Это основное функциональное отличие двух API SMSfeedback.

Сообщения для запроса формируются на основе JSON формата. JSON (англ. JavaScript Object Notation) - текстовый формат обмена данными, основанный на JavaScript и обычно используемый именно с этим языком. Как и многие другие текстовые форматы, JSON прост для чтения и восприятия.

Расширенный API используется для обеспечения массовых смс рассылок с вашего сайта или из информационной системы. Данный способ отправки удобен тем, что база данных для рассылки никуда не выгружается для последующей отправки через программу или WEB кабинет SMSfeedback. Данный интерфейс взаимодействия позволяет достичь максимальной интеграции с нашим смс сервисом.

Проверку статуса отправленных сообщений можно реализовать двумя способами:

  1. использовать JSON запрос на проверку состояния отправленных сообщений. Данный способ позволяет проверять до 200 смс сообщений, которые вы выбираете сами.
  2. второй вариант - это проверка очереди отправленных сообщений (очередь назначается при отправке сообщений параметром statusQueueName). Данный способ позволяет проверить одним запросом до 1000 статусов последних смс в данной очереди.

Передача сообщений (до 200 сообщений в запросе)

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

http://api.smsfeedback.ru/messages/v2/send.json

{
    "login": "login",
    "password": "password",
    "statusQueueName": "myQueue",
	"showBillingDetails": false,
    "scheduleTime": "2009-01-01T12:30:01+00:00",
    "messages":[
            {
                "clientId" : "1",
                "phone": "79031234567",
                "text": "Message text",
                "sender": "MySignature" 
            },
            {
                "clientId" : "2",
                "phone": "71234567892",
                "text": "2 sms Message text here Message text here Message text here Message text here Message text here Message text here Message text here Message text here Message text here 2 sms",
                "sender": "NotMySignature"
            }
        ]
}

Параметр Статус Описание
login Обязательно Логин
password Обязательно Пароль
scheduleTime Дата для отложенной отправки сообщения, в UTC (2009-01-01T12:30:01+00:00). Для смены часового пояса необходимо изменять само время, "+00:00" - неизменно.
statusQueueName Название очереди статусов отправленных сообщений, в случае, если вы хотите использовать очередь статусов отправленных сообщений. От 3 до 16 символов, буквы и цифры (например myQueue1)
showBillingDetails Включение в ответ биллинговых данных: баланса, количества SMS в сообщении, стоимость сообщения
clientId Обязательно Id сообщения на стороне клиента
phone Обязательно Номер телефона, в формате 79031234567 (функция проверки номера телефона на PHP)
text Обязательно Текст сообщения, в UTF-8 кодировке (функция смены кодировки с windows-1251 на UTF-8)
wapurl Wap-push ссылка, в случае, если вы хотите передать wap-push сообщение (например wap.yousite.ru)
sender Подпись отправителя (например TEST)

При успешной авторизации сервер должен вернуть json ответ вида:


//при "showBillingDetails": false

{
    "status": "ok",
    "messages":[
            {
                "clientId" : "1",
                "smscId": "12345",
                "status": "accepted",
            },
            {
                "clientId" : "2",
                "smscId": "12346",
                "status": "sender address invalid"
            }
     ]
}

//при "showBillingDetails": true

{
    "status": "ok",
	"balance": [{"credit": 0.00, "balance": 18.70, "type": "RUB"}]
    "messages":[
            {
                "clientId" : "1",
                "smscId": "12345",
                "status": "accepted",
				"smsCount": 1, 
                "msgCost": 0.79				
            },
            {
                "clientId" : "2",
                "smscId": "12346",
                "status": "sender address invalid",
				"smsCount": 2, 
                "msgCost": 1.58	
            }
     ]
}

где сервис выдает результаты обработки сообщений:

Параметр Описание
status Статус приема пакета (ok – ошибок не обнаружено)
clientId Id сообщения на стороне клиента
smscId Id сообщения на стороне сервера
status (в messages) Статус отправки сообщения (подробнее о статусах)
smsCount Количество SMS в сообщении
msgCost Стоимость сообщения (тариф умноженный на количество SMS). Отображается, если клиент использует рублевый баланс
balance Остатки средств на балансе, после отправки сообщений

Проверка состояния отправленных сообщений (до 200 сообщений в запросе)

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

http://api.smsfeedback.ru/messages/v2/status.json

{
    "login": "login",
    "password": "password",
    "messages": [
            {
                "clientId": "1",
                "smscId": "12345" 
            },
            {
                "clientId": "2",
                "smscId": "12346" 
            }
    ]
}

Параметр Статус Описание
login Обязательно Логин
password Обязательно Пароль
clientId Обязательно Id сообщения на стороне клиента
smscId Обязательно Id сообщения на стороне сервера

При успешной авторизации сервер должен вернуть json ответ вида:

{
    "status": "ok/error",
    "messages":[
            {
                "clientId" : "1",
                "smscId": "12345",
                "status": "delivered" 
            },
            {
                "clientId" : "2",
                "smscId": "12346",
                "status": "smsc reject" 
            }
     ]
}

где сервис выдает статусы сообщений:

Параметр Описание
status Статус приема пакета (ok – ошибок не обнаружено)
clientId Id сообщения на стороне клиента
smscId Id сообщения на стороне сервера
status (в messages) Статус отправленного сообщения (подробнее о статусах)

Проверка очереди статусов сообщений

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

http://api.smsfeedback.ru/messages/v2/statusQueue.json

{
    "login": "login",
    "password": "password",
    "statusQueueName" : "myQueue",
    "statusQueueLimit" : "100" 
}

Параметр Статус Описание
login Обязательно Логин
password Обязательно Пароль
statusQueueName Обязательно Название очереди статусов сообщений. Название очереди устанавливается при передаче сообщения
statusQueueLimit Количество запрашиваемых статусов из очереди (по умолчанию 1, макс. 1000)

При успешной авторизации сервер должен вернуть json ответ вида:

{
    "status": "ok/error",
    "messages":[
            {
                "smscId": "12345",
                "status": "delivered" 
            },
            {
                "smscId": "12346",
                "status": "smsc reject" 
            }
     ]
}

где сервис выдает статусы сообщений:

Параметр Описание
status Статус приема пакета (ok – ошибок не обнаружено)
smscId Id сообщения на стороне сервера
status (в messages) Статус отправленного сообщения (подробнее о статусах)

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

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

http://api.smsfeedback.ru/messages/v2/balance.json

{
    "login": "login",
    "password": "password"
}

Параметр Статус Описание
login Обязательно Логин
password Обязательно Пароль

При успешной авторизации сервер должен вернуть json ответ вида:

  {
    "status": "ok/error", 
    "balance": [
        {
            "credit": 0.0, 
            "balance": 25.73, 
            "type": "RUB"
        }, 
        {
            "credit": 1000000, 
            "balance": -3754, 
            "type": "SMS"
        }
    ]
}

где сервис выдает информацию о балансах клиента: типе баланса, количестве и возможном кредите (возможности использовать сервис при отрицательном балансе):

Параметр Описание
status Статус приема пакета (ok – ошибок не обнаружено)
type Тип баланса: RUB, SMS
balance Количество средств на балансе
credit Кредит (возможность использовать сервис при отрицательном балансе)

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

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

http://api.smsfeedback.ru/messages/v2/senders.json

{
    "login": "login",
    "password": "password"
}

Параметр Статус Описание
login Обязательно Логин
password Обязательно Пароль

При успешной авторизации сервер должен вернуть json ответ вида:

{
    "status": "ok/error",
    "senders":[ "Sender_one", "Sender_two", "Sender_three" ]
}

где сервис выдает информацию о балансе:

Параметр Описание
status Статус приема пакета (ok – ошибок не обнаружено)
senders Список доступных подписей
active Подпись активирована и готова к использованию
new Новая подпись
pending Подпись в процессе активации
blocked Подпись заблокирована
default Подпись по умолчанию, готова к использованию