XML API¶
Описание¶
Сервис XML API позволяет отправлять SMS-сообщения через платформу Devino Telecom. Также доступна отправка транзакционных сообщений и получение подробной статистики по рассылкам.
Взаимодействие с сервисом осуществляется при помощи отправки XML-запросов в кодировке UTF-8 на заданный адрес сервиса. Отправка происходит по HTTPS-протоколу типом метода POST, при этом проверка типа контента не осуществляется.
Каждый запрос может состоять из:
- отправляемых сообщений
- запросов для получения статусов
- запросов для получения входящих сообщений
Авторизация пользователя происходит через передачу учетных сведений в теге package и обязательна при выполнении любых запросов.
Внимание
Для использования данного вида интеграции необходимо обратиться к менеджеру компании либо в техническую поддержку для настройки доступа.
Сервис доступен по адресу:
https://xmlapi.devinotele.com
Отправка сообщений¶
https://xmlapi.devinotele.com/Send.ashx
Отправка сообщений осуществляется в соответствии с очередностью по получению сообщений и временем отправки.
Параметры запроса¶
| Параметр | Тип данных | Описание |
|---|---|---|
| Default | Тег, в котором определяются общие атрибуты для всех отправляемых сообщений. Если какой-либо атрибут указан в сообщении, атрибут данного тега игнорируется. | |
| msg обязательный |
Тег сообщения. В качестве параметра указывается текст отправляемого сообщения. | |
| id | integer | Пользовательский числовой ID сообщения |
| recipient обязательный |
varchar(21) | Номер телефона. Пример: 79031234567, +79031234567 |
| sender обязательный |
varchar(11) | Адрес отправителя |
| date_beg | datetime, ISO8601 | Дата отправки сообщения для отложенной отправки сообщений |
| date_end | datetime, ISO8601 | Дата, после которой сообщение теряет актуальность. Если сообщение по истечении срока не было отправлено абоненту, отправка этого сообщения отменяется. |
| url обязательный |
varchar(100) | Ссылка для создания WAP-Push сообщения. Обязательно для отправки WAP-Push сообщений. |
| type обязательный |
integer | Тип сообщения: 0 - обычное сообщение1 - flash сообщение2 - WAP-Push сообщение |
Пример запроса¶
<?xml version="1.0" encoding="utf-8" ?>
<package login="login" password="123456">
<message>
<default sender="SMSINFO"/>
<msg id="1234" recipient="+79021234567" sender="SMSINFO" date_beg="2008-12-27T15:55" date_end="2008-12-28T15:55" type="0">text</msg>
<msg recipient="+79021234568">text</msg>
</message>
</package>
Параметры ответа¶
На полученный запрос сервис возвращает в виде параметра статус сообщения, а в атрибутах идентификаторы, присвоенные сообщениям.
| Параметр | Тип данных | Описание |
|---|---|---|
| msg | integer | Тег сообщения. В качестве параметра возвращается код статуса. |
| id | integer | Пользовательский числовой ID сообщения. Возвращается при указании данного атрибута в запросе |
| sms_id | integer | Числовой ID сообщения, присвоенный шлюзом. |
| sms_count | integer | Реальное количество SMS, готовых к отправке. |
Пример ответа¶
<?xml version="1.0" encoding="utf-8" ?>
<package>
<message>
<msg id="1234" sms_id="0" sms_count="1">201</msg>
<msg sms_id="1234568" sms_count="1">1</msg>
</message>
</package>
Запрос статусов сообщений¶
https://xmlapi.devinotele.com/Statistics.ashx
Статусы сообщений содержат информацию о текущем состоянии сообщения. Статусы регулярно обновляются и могут быть запрошены пользователем в любое время.
Статусы можно запрашивать за последние 3 календарных дня. Максимальное количество ID в запросе 1000.
Параметры запроса¶
| Параметр | Тип данных | Описание |
|---|---|---|
| msg | integer | Тег сообщения, для которого происходит запрос статуса. |
| id | integer | Пользовательский числовой ID сообщения. Возвращается при указании данного атрибута в запросе. |
| sms_id обязательный |
integer | Числовой ID сообщения, присвоенный шлюзом. |
Важно
Можно указать один из параметров: id либо sms_id.
Параметры ответа¶
В ответ на запрос возвращается XML-документ, содержащий статусы для запрошенных сообщений, либо соответствующие коды ошибок.
| Параметр | Тип данных | Описание |
|---|---|---|
| msg | integer | Тег сообщения, для которого происходит запрос статуса. В качестве параметра возвращается код статуса. |
| id | integer | Пользовательский числовой ID сообщения. Возвращается при указании данного атрибута в запросе. |
| sms_id | integer | Числовой ID сообщения, присвоенный шлюзом. |
| sms_count | integer | Реальное количество SMS к отправке |
| date_completed | datetime, ISO8601 | Дата присвоения финального статуса |
Пример ответа¶
<?xml version="1.0" encoding="utf-8" ?>
<package>
<status>
<msg id="1234" sms_id="0" sms_count="1" date_completed="2009-03-14T15:27:03">102</msg>
<msg sms_id="1234568" sms_count="1">1</msg>
</status>
</package>
Коды статусов документа¶
При отправке XML-документа могут возвращаться следующие коды ошибок:
| Код | HTTP Status | Расшифровка |
|---|---|---|
| ERR_UNKNOWN | 200 | Неизвестная ошибка |
| ERR_FORMAT | 201 | Неправильный формат документа |
| ERR_AUTHORIZATION | 202 | Ошибка авторизации |
Пример ответа¶
<?xml version="1.0" encoding="utf-8" ?>
<package>
<error>201</error>
</package>
Коды статусов сообщений¶
Данные коды используются при возврате статусов сообщений.
Статусы сообщений¶
| Код | HTTP Status | Расшифровка |
|---|---|---|
| SCHEDULED | 100 | Запланировано |
| ENROUTE | 101 | В очереди |
| DELIVERED | 102 | Доставлено |
| EXPIRED | 103 | Просрочено |
| DELETED | 104 | Просрочено |
| UNDELIVERABLE | 105 | Не доставлено |
| ACCEPTED | 106 | Принято |
| UNKNOWN | 107 | Ошибка |
| REJECTED | 108 | Отклонено |
| DISCARDED | 109 | Отклонено |
Статусы ошибок¶
| Код | HTTP Status | Расшифровка |
|---|---|---|
| ERR_UNKNOWN | 200 | Неизвестная ошибка |
| ERR_ID | 201 | Неправильный ID сообщения |
| ERR_SENDER | 202 | Неправильный адрес отправителя |
| ERR_RECIPIENT | 203 | Неправильный номер получателя |
| ERR_LENGTH | 204 | Слишком длинное или пустое сообщение |
| ERR_USER_DISABLE | 205 | Пользователь отключен |
| ERR_BILLING | 206 | Ошибка биллинга |
| ERR_OVERLIMIT | 207 | Превышение лимита выделенных сообщений |