HTTP API Без SessionID¶
Обзор API¶
Предоставляемый API Сервиса отправки SMS сообщений позволяет осуществить:
- Отправку SMS-сообщения на один номер без учета часового пояса получателя
- Отправку SMS-сообщения на один номер с учетом часового пояса получателя
- Отправку SMS-сообщения на несколько номеров без учета часового пояса получателя
- Получение статуса отправленного SMS-сообщения
- Получение SMS-сообщений за период
- Получение статистики по SMS-рассылкам
- Получение баланса
API Сервиса отправки SMS сообщений организовано в соответствии с принципами REST, что позволяет обмениваться HTTPS URL–encoded запросами. HTTPS - это обычный HTTP, работающий через шифрованные транспортные механизмы SSL и TLS. Это позволяет обеспечить защиту от атак, основанных на прослушивании сетевого соединения: снифферских атак и атак типа man-in-the-middle при условии, что будут использоваться шифрующие средства и сертификат сервера проверен и ему доверяют.
Запрос к API состоит из следующих элементов:
- Основного URL запроса: https://integrationapi.net/rest/v2
- Ресурса, например: /Sms/SendByTimeZone
- Параметров GET или POST-запроса (в кодировке UTF-8)
Получение баланса авторизованного пользователя¶
Протокол HTTP не имеет состояний. Это означает, что веб-сервер обрабатывает каждый HTTP-запрос со стороны внешнего приложения или сайта независимо, а сервер не сохраняет данные о значениях переменных, использованных в предшествующих запросах. Поэтому данные, полученные при авторизации пользователя, должны быть переданы и при осуществлении запроса получения баланса авторизованного пользователя. Сервис возвращает значение баланса авторизованного пользователя в соответствии со значениями параметров, передаваемых сервису в GET-запросе следующего формата:
Ниже приведен пример запроса:
В Табл. 2 приводится полный список параметров запроса.
Табл. 2. Параметры GET-запроса баланса
| Параметр | Тип данных | Описание |
|---|---|---|
| Обязательные параметры | ||
| Login | String | Логин,полученный при регистрации |
| Password | String | Пароль, соответствующий логину |
Сервис проверяет валидность Логина/Пароля и в случае успеха авторизует пользователя и в ответе присылает баланс пользователя со следующими параметрами:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
<Баланс пользователя>
Ниже приведен пример ответа:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8 20015.3
В случае возникновения исключительной ситуации во время обработки запроса или ошибки аутентификации, сервис возвращает код ошибки (см. Табл. 10) в виде JSON следующего формата:
{
Code: <Код ошибки>,
Desc: <”Текст ошибки”>
}
Например, при ошибке авторизации:
{
Code: 4,
Desc: "Invalid user login or password"
}
Отправка SMS-сообщений¶
Отправка SMS-сообщения на один номер без учета часового пояса получателя¶
Сервис инициирует отправку SMS-сообщения в соответствии со значениями параметров, передаваемых сервису в POST-запросе следующего формата:
https://integrationapi.net/rest/v2/Sms/Send?Login=<Логин>&Password=<Пароль>&SourceAddress=<Адрес отправителя>&DestinationAddress=<Номер получателя>&Data=<Текст сообщения>&Validity=<Время жизни сообщения>
Ниже приведен пример запроса:
В Табл. 3 приводится полный список параметров запроса.
Табл. 3. Параметры запроса на отправку SMS-сообщения
| Параметр | Тип данных | Описание |
|---|---|---|
| Обязательные параметры | ||
| Login | String | Логин, полученный при регистрации |
| Password | String | Пароль, соответствующий логину |
| DestinationAddres | String | Номер получателя сообщения, в международном формате: код страны код сети + номер телефона. Пример: 79031234567; +79031234567; |
| Data | String | Текст сообщения, сообщение не должно быть длиннее 2000 символов |
| SourceAddress | String | Адрес отправителя сообщения. До 11 латинских символов или до 15 цифровых. |
| Необязательные параметры | ||
| SendDate | DateTime | Дата и время отправки (пример 2011-01-28T16:00:00). Если в запросе передается этот параметр, то сообщение будет отправлено только при наступлении полученных даты и времени без учета текущего часового пояса получателя. Сообщение отправится при наступлении переданного времени в часовом поясе: GMT+04:00. Если не требуется отложенная отправка, то передавать данный параметр не нужно. |
| Validity | Int | Время жизни сообщения (в минутах) |
Перед отправкой SMS сервис проверяет запрос на: * Наличие обязательных параметров; * Валидность Логина/пароля; * Достаточно ли Баланса Пользователя на отправку SMS. (Достаточность определяется на основании тарифа пользователя на отправку SMS для мобильного оператора указанного в запросе номера); * Валидность указанного в запросе номера; * Валидность адреса отправителя; * Длину сообщения.
Если все проверки пройдены успешно, то сервис отправит сообщение в SMS-центр и вернет идентификатор отправленного сообщения со следующими параметрами: Формат ответа:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
<Идентификатор сообщения>
Например:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
["GW0261BBD6B3"]
В случаях, когда длина отправляемого сообщения превышает 70 символов на кириллице или 160 символов на латинице, ответ от сервиса будет в виде последовательности идентификаторов сообщений, например:
["SAR-GW01+79160000000-5f3b1972-2-1","SAR-GW01+79160000000-5f3b1972-2-2"]
Если какая-нибудь проверка не проходит успешно, то сервис возвращает код ошибки (см. Табл. 10) в виде JSON следующего формата:
{
Code: <Код ошибки>,
Desc: <”Текст ошибки”>
}
Например:
{
Code: 6,
Desc: "Invalid source address"
}
Отправка SMS-сообщения на один номер с учетом часового пояса получателя:¶
Сервис инициирует отправку SMS-сообщения в соответствии со значениями параметров, передаваемых сервису в POST-запросе следующего формата:
https://integrationapi.net/rest/v2/Sms/SendByTimeZone?Login=<Логин>&Password=<Пароль>&SourceAddress=<Адрес отправителя>&DestinationAddress=<Номер получателя>&Data=<Текст сообщения>&Validity=<Время жизни сообщения>&SendDate=<Дата отправки сообщения>
Ниже приведен пример запроса:
https://integrationapi.net/rest/v2/Sms/SendByTimeZoneLogin=test_login&Password=test123&SourceAddress=TESTSMS&DestinationAddress=79001234567& Data=testdata&Validity=10&sendDate=2011-01-28T16:00:00
В Табл. 4 приводится полный список параметров запроса.
Табл. 4. Параметры POST-запроса на отправку SMS-сообщения c учетом часового пояса
| Параметр | Тип данных | Описание |
|---|---|---|
| Обязательные параметры | ||
| Login | String | Логин, полученный при регистрации |
| Password | String | Пароль, соответствующий логину |
| DestinationAddress | String | Номер получателя сообщения, в международном формате: код страны и код сети плюс номер телефона. Пример:
|
| Data | String | Текст сообщения, сообщение не должно быть длиннее 2000 символов |
| SourceAddress | String | Адрес отправителя сообщения. До 11 латинских символов или до 15 цифровых. |
| SendDate | DateTime | Дата и время отправки (пример 2011-01-28T16:00:00). Если в запросе передается этот параметр, то сообщение будет отправлено только при наступлении полученных даты и времени с учетом текущего часового пояса получателя. Если не требуется отложенная отправка, то передавать данный параметр не нужно. |
| Необязательные параметры | ||
| Validity | Int | Время жизни сообщения (в минутах) |
Перед отправкой SMS сервис проверяет запрос на: * Наличие обязательных параметров; * Валидность Логина/пароля; * Достаточно ли баланса пользователя на отправку SMS. (Достаточность определяется на основании тарифа пользователя на отправку SMS для мобильного оператора указанного в запросе номера); * Валидность указанного в запросе номера; * Валидность адреса отправителя; * Длину сообщения.
Если все проверки пройдены успешно, то сервис отправит сообщение в SMS-центр и вернет идентификатор отправленного сообщения со следующими параметрами: Формат ответа:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
<Идентификатор сообщения>
Например:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
["GW0261BBD6B3"]
В случаях, когда длина отправляемого сообщения превышает 70 символов на кириллице или 160 символов на латинице, ответ от сервиса будет в виде последовательности идентификаторов сообщений:
["SAR-GW01+79160000000-5f3b1972-2-1","SAR-GW01+79160000000-5f3b1972-2-2"]
Например:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
["SAR-GW01+79160000000-5f3b1972-2-1","SAR-GW01+79160000000-5f3b1972-2-2"]
Если какая-нибудь проверка не проходит успешно, то сервис возвращает код ошибки (см. Табл. 10) в виде JSON следующего формата:
{
Code: <Код ошибки>,
Desc: <”Текст ошибки”>
}
Например:
{
Code: 6,
Desc: "Invalid source address"
}
Отправка SMS-сообщения на несколько номеров без учета часового пояса получателя: Сервис инициирует отправку SMS-сообщения на несколько номеров в соответствии со значениями параметров, передаваемых сервису в POST-запросе следующего формата:
https://integrationapi.net/rest/v2/Sms/SendBulk?Login=<Логин>&Password=<Пароль>&SourceAddress=<Адрес отправителя>&DestinationAddresses=<Номер(а) получателя(ей)>&Data=<Текст сообщения>&Validity=<Время жизни сообщения>
Ниже приведен пример запроса:
https://integrationapi.net/rest/v2/Sms/SendBulk?Login=test_login&Password=test123&SourceAddress=TESTSMS&&DestinationAddresses=79001234567&DestinationAddresses= 79059999999&Data=testdata&Validity=10
В Табл. 5 приводится полный список параметров запроса.
Табл. 5. Параметры POST-запроса на отправку SMS-сообщения на несколько номеров
| Параметр | Тип данных | Описание |
|---|---|---|
| Обязательные параметры | ||
| Login | String | Логин, полученный при регистрации |
| Password | String | Пароль, соответствующий логину |
| DestinationAddress | String | Номер получателя сообщения, в международном формате: код страны и код сети плюс номер телефона. Максимальное количество получателей
|
| Data | String | Текст сообщения, сообщение не должно быть длиннее 2000 символов |
| SourceAddress | String | Адрес отправителя сообщения. До 11 латинских символов или до 15 цифровых. |
| Необязательные параметры | ||
| Validity | Int | Время жизни сообщения (в минутах) |
| SendDate | DateTime | Дата и время отправки (пример 2010-0601T19:14:00). Если не требуется отложенная отправка, то передавать данный параметр не нужно. |
Перед отправкой SMS Сервис проверяет запрос на: * Наличие обязательных параметров; * Валидность Логина/пароля; * Достаточно ли Баланса Пользователя на отправку SMS. (Достаточность определяется на основании тарифа пользователя на отправку SMS для мобильного оператора указанного в запросе номера); * Валидность указанных в запросе номеров (если хоть один номер не проходит валидацию, то сообщения не отправляются); * Валидность адреса отправителя; * Длину сообщения.
Если все проверки пройдены успешно, то сервис отправит сообщение в SMS-центр и вернет идентификатор отправленного сообщения со следующими параметрами: Формат ответа:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
<Идентификатор сообщения>
Например:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
["GW0261BBD6B3"]
В случаях, когда длина отправляемого сообщения превышает 70 символов на кириллице или 160 символов на латинице, ответ от сервиса будет в виде последовательно расположенных идентификаторов сегментов сообщения. Для нескольких сообщений идентификаторы сегментов будут расположены последовательно – сначала последовательно все сегменты одного сообщения, затем – все сегменты другого, например:
- [“SAR-GW01+79160000000-5f3b1972-2-1”,”SAR-GW01+79160000000-5f3b1972-2-2”,
- [“SAR-GW01+79053500000-5d3b1972-2-1”,”SAR-GW01+79053500000-5d3b1972-2-2]
Например:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
["SAR-GW01+79160000000-5f3b1972-2-1","SAR-GW01+79160000000-5f3b1972-2-2",
["SAR-GW01+79053500000-5f3d1972-2-1","SAR-GW01+79053500000-5f3d1972-2-2]
Если какая-нибудь проверка не проходит успешно, то сервис возвращает код ошибки (см. Табл. 10) в виде JSON следующего формата:
{
Code: <Код ошибки>,
Desc: <”Текст ошибки”>
}
Например:
{
Code: 6,
Desc: "Invalid source address"
}
**Внимание! Возможность отправки sms на несколько номеров с учетом часового пояса получателя пока недоступна. **
Получение статуса отправленного SMS-сообщения¶
Сервис возвращает статус отправленного sms-сообщения в соответствии со значениями параметров, передаваемых сервису в GET-запросе следующего формата:
https://integrationapi.net/rest/v2/Sms/State?
Login=<Логин>&
Password=<Пароль>&
messageId=<Идентификатор сообщения>
Ниже приведен пример запроса для односегментного сообщения (длина которого не превышает 70 символов на кириллице или 160 символов на латинице):
https://integrationapi.net/rest/v2/Sms/State?Login=test_login&Password=test123&messageId=GW0261BA732
Для сообщений, длина которых превышает 70 символов на кириллице и 160 на латинице, запрос должен формироваться для каждого сегмента сообщений, например:
https://integrationapi.net/rest/v2/Sms/State?Login=test_login&Password=test123&messageID=SAR-W+84333
Табл. 6. Параметры GET-запроса статуса отправленного сообщения (сегмента сообщения)
| Параметр | Тип данных | Описание |
|---|---|---|
| Login | String | Логин, полученный при регистрации |
| Password | String | Пароль, соответствующий логину |
| DestinationAddress | String | Идентификатор сообщения (сегмента сообщения). Для одного запроса будет выполнен возврат статуса только одного сообщения (сегмента сообщения). |
После получения запроса сервис проверит валидность логина/пароля и наличие отправленного сообщения (сегмента сообщения) с присланным идентификатором. Если все проверки пройдены успешно, то сервис вернет статус отправленного sms-сообщения в json формате со следующими параметрами:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
{"State":{Код статуса сообщения},
"CreationDateUtc":{Дата создания},
"SubmittedDateUtc":{Дата отправки сообщения},
"ReportedDateUtc":{Дата доставки сообщения},
"TimeStampUtc":"{Дата и время получения отчета}",
"StateDescription":"{Описание статуса}",
"Price":{Стоимость}
Например:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
{"State":255,"CreationDateUtc":null,"SubmittedDateUtc":null,"ReportedDateU tc":null,"TimeStampUtc":"\/Date(-
62135596800000)\/","StateDescription":"Неизвестный","Price":null}
Если какая-нибудь проверка не проходит успешно, то сервис возвращает код ошибки (см. Табл. 10) в виде JSON следующего формата:
{
Code: <Код ошибки>,
Desc: <”Текст ошибки”>
}
Например:
{
Code: 1,
Desc: "MessageID can not be null or empty Parameter name: messageId"
}
Табл. 7. Параметры ответа на запрос статуса сообщения
| Наименование поля | Описание |
|---|---|
| State | Статус сообщения (см. Табл. 11) |
| TimeStampUtc | Дата и время получения отчета (Гринвич GMT00:00) |
| StateDescription | Описание статуса |
| CreationDateUtc | Дата создания |
| SubmittedDateUtc | Дата отправки |
| ReportedDateUtc | Дата доставки |
| Price | Цена за сообщение |
Получение SMS-сообщений за период¶
Сервис возвращает входящие sms-сообщения за период в соответствии со значениями параметров, передаваемых сервису в GET-запросе следующего формата:
https://integrationapi.net/rest/v2/Sms/In?
Login=<Логин>&
Password=<Пароль>&
minDateUTC=<Дата и время начала периода>&
maxDateUTC=<Дата и время окончания периода>
Ниже приведен пример запроса:
https://integrationapi.net/rest/Sms/In?sessionId=Z5CYSZEKDL1DPICU37WEHQVOYKP0T1GSLHX1&minDateUTC=2011-01-01T00:00:00&maxDateUTC=2011-01-11T00:00:00
Табл. 8. Параметры GET-запроса на получение сообщений за период
| Параметр | Тип данных | Описание |
|---|---|---|
| Login | String | Логин, полученный при регистрации |
| Password | String | Пароль, соответствующий логину |
| maxDateUTC | DateTime | Дата и время окончания периода, за который происходит выборка входящих сообщений (например, 2010-06-02T19:14:00). |
| Необязательные параметры | ||
| minDateUTC | DateTime | Дата и время начала периода, за который происходит выборка входящих сообщений (например, 2010-06-01T19:14:00). |
После получения запроса сервис проверит валидность логина/пароля и даты-времени начала и окончания периода присланным идентификатором. Если все проверки пройдены успешно, то сервис вернет перечень сообщений и их параметров за период в json-файла следующего формата:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
[{"Data":{Текст сообщения},
"SourceAddress":{Адрес отправителя},
"DestinationAddress":{Номер получателя},
"ID":{Идентификатор сообщения},
"CreatedDateUtc":{Дата создания}]
Например:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
[{"Data":"test1",
"SourceAddress":"79260000000",
"DestinationAddress":"79160000000",
"ID":539187174,
"CreatedDateUtc":"\/Date(1294045911213)\/"},
{"Data":"test2",
"SourceAddress":"79260000001",
"DestinationAddress":"79160000000",
"ID":539187214,
"CreatedDateUtc":"\/Date(1294045911353)\/"}]
Если какая-нибудь проверка не проходит успешно, то сервис возвращает код ошибки (см. Табл. 10) в виде JSON следующего формата:
{
Code: <Код ошибки>,
Desc: <”Текст ошибки”>
}
Например:
{
Code: 9,
Desc: "The parameters dictionary contains a null entry for parameter
'maxDateUtc' of non-nullable type 'DateTime' for method
'System.Web.Mvc.ActionResult In(System.String, DateTime, DateTime)' in
'RestService.Controllers.SmsController'. An optional parameter must be a reference type, a nullable type, or be declared as an optional parameter. Parameter name: parameters"
}
Получение статистики по SMS-рассылкам¶
Сервис возвращает статистику по SMS-рассылкам за период в соответствии со значениями параметров, передаваемых сервису в GET-запросе следующего формата:
https://integrationapi.net/rest/v2/Sms/Statistics?
Login=<Логин>&
Password=<Пароль>&
startDateTime=<Дата и время начала периода>&
endDateTime=<Дата и время конца периода>
Ниже приведен пример запроса:
https://integrationapi.net/rest/Sms/Statistics?sessionId=FBHKZT9TBBTUWYUR1PYUTYRAGRLUUG0R8A8Z&startDateTime=2012-01-18%2000:00:00&endDateTime=2012-0118%2023:59:00
Табл. 9. Параметры GET-запроса на формирование статистики за период
| Параметр | Тип данных | Описание |
|---|---|---|
| Обязательные параметры | ||
| Login | String | Логин, полученный при регистрации |
| Password | String | Пароль, соответствующий логину |
| startDateTime | DateTime | Дата и время конца периода, за который необходимо получить статистику, например 2012-01-18%2023:59:00. |
| endDateTime | DateTime | Дата и время конца периода, за который необходимо получить статистику, например 2012-01-18%2023:59:00. |
После получения запроса сервис проверит валидность логина/пароля и дат начала/окончания формирования статистики (включая ограничение на то, что охватываемый диапазон должен не превышать 3 месяцев). Если все проверки пройдены успешно, то сервис вернет статистику по sms-сообщениям в json формате со следующими параметрами:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
{"Sent":{Отправлено},
"Delivered":{Доставлено},
"Errors":{С ошибками},
"InProcess":{В процессе},
"Expired":{С истекшим сроком доставки},
"Rejected":{Отмененные},
"Total":{Всего},
"TotalWithErrors":{Всего с ошибками},
"DeliveryRatio":{Успешно доставлено}
Например:
HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
{"Sent":9,
"Delivered":0,
"Errors":0,
"InProcess":7780,
"Expired":0,
"Rejected":56876,
"Total":64665,
"TotalWithErrors":64665,
"DeliveryRatio":0}
Если какая-нибудь проверка не проходит успешно, то сервис возвращает код ошибки (см. Табл. 10) в виде JSON следующего формата:
{
Code: <Код ошибки>,
Desc: <”Текст ошибки”>
}
Например:
{
Code: 2,
Desc: "Нельзя указывать диапазон дат более 90 дней."
}
Коды ошибок и статусы сообщений¶
Табл. 10. Коды ошибок
| REST error code | HTTP status code | Описание |
|---|---|---|
| 200 | Operation complete | |
| 1 | 400 | Argument cannot be null or empty |
| 2 | 400 | Invalid argument |
| 4 | 401 | Unauthorized access |
| 5 | 403 | Not enough credits |
| 6 | 400 | Invalid operation |
| 7 | 403 | Forbidden |
| 8 | 500 | Gateway error |
| 9 | 500 | Internal server error |
Табл. 11. Статусы сообщений
| State | Описание |
|---|---|
| -1 | Отправлено (передано в мобильную сеть) |
| -2 | В очереди |
| 47 | Удалено |
| -98 | Остановлено |
| 0 | Доставлено абоненту |
| 10 | Неверно введен адрес отправителя |
| 11 | Неверно введен адрес получателя |
| 41 | Недопустимый адрес получателя |
| 42 | Отклонено смс центром |
| 46 | Просрочено (истек срок жизни сообщения) |
| 48 | Отклонено Платформой |
| 69 | Отклонено |
| 99 | Неизвестный |
| 255 | По запросу возвращается этот статус, если сообщения еще не успело попасть в БД, либо сообщение старше 48 часов. |