XML API¶
Обзор¶
Документация включает описание API для отправки SMS-сообщений через платформу Devino Telecom с примерами запросов. API включает в себя возможность как транзакционных, так и массовых рассылок, получение подробной статистики по рассылкам. Документ предназначен для разработчиков, которые хотят добавить возможность взаимодействия с Сервисом отправки SMS-сообщений на страницы своих сайтов или в свои приложения. Общение с сервисом осуществляется при помощи отправки XML запросов в кодировке UTF-8 на заданный адрес сервиса по протоколу HTTPS методом POST, проверка типа контента не осуществляется. Каждый запрос может состоять из отправляемых сообщений и (или) запросов для получения статусов и (или) запросов для получения входящих сообщений. Авторизация пользователя происходит путем передачи учетных сведений в теге package, обязательна при выполнении любых запросов.
Сервис доступен по адресу:
https://xmlapi.devinotele.com
Отправка сообщений¶
Отправка сообщений осуществляется в соответствии с очередностью по получению сообщений и временем отправки.
Пример запроса:
<?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>
| Параметр | Тип данных | Обязательный | Описание |
|---|---|---|---|
| Default | Нет | Тег, в котором определяются общие атрибуты, указываемые для всех отправляемых сообщений. Если какой-либо атрибут указан в сообщении, то атрибут данного тега игнорируется | |
| msg | да | Тег сообщения, в качестве параметра указывается текст отправляемого сообщения | |
| id | integer | Нет | Пользовательский числовой идентификатор сообщения |
| recipient | varchar(21) | Да | Номер телефона. Пример: 79031234567, +79031234567 |
| sender | varchar(11) | Да | Адрес отправителя |
| date_beg | datetime, ISO8601 | Нет | Дата отправки сообщения, указывается для отложенной отправки сообщений. |
| date_end | datetime, ISO8601 | Нет | Дата, после которой сообщение теряет актуальность и если оно еще не было отправлено абоненту, отправляться не будет. |
| url | varchar(100) | Да * | Ссылка для создания wap-push сообщения |
| type | integer | Да | Тип сообщения: 0-обычное сообщение 1-flash сообщение 2-wap-push сообщение |
*Поле обязательное для отправки wap-push сообщений
На полученный запрос сервис возвращает в виде параметра статус сообщения, а в атрибутах идентификаторы, присвоенные сообщениям.
Пример ответа:
<?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>
| Параметр | Тип данных | Описание |
|---|---|---|
| msg | Тег сообщения, в качестве параметра возвращается код статуса | |
| id | integer | Пользовательский числовой идентификатор сообщения, необязательный атрибут, возвращается при указании данного атрибута в запросе |
| sms_id | integer | Числовой идентификатор сообщения, присвоенный шлюзом |
| sms_count | integer | Реальное количество SMS к отправке |
Запрос статусов сообщений¶
Статусы сообщений содержат информацию о текущем состоянии сообщения, регулярно обновляются и могут быть запрошены пользователем в любое время.
Пример запроса:
<?xml version="1.0" encoding="utf-8" ?>
<package login="login" password="123456">
<status>
<msg id="1234"/>
<msg sms_id="1234568"/>
</status>
</package>
| Параметр | Тип данных | Обязательный | Описание |
|---|---|---|---|
| msg | Нет | Тег сообщения, для которого происходит запрос статуса | |
| id | integer | Нет * | Пользовательский числовой идентификатор сообщения, возвращается при указании данного атрибута в запросе |
| sms_id | integer | Да * | Числовой идентификатор сообщения, присвоенный шлюзом |
*Можно указать любой из этих параметров
В ответ на запрос возвращается XML документ содержащий статусы для запрошенных сообщений, либо соответствующие коды ошибок.
Пример ответа:
<?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>
| Параметр | Тип данных | Описание |
|---|---|---|
| msg | Тег сообщения, для которого происходит запрос статуса, в качестве параметра возвращается код статуса | |
| id | integer | Пользовательский числовой идентификатор сообщения, возвращается при указании данного атрибута в запросе |
| sms_id | integer | Числовой идентификатор сообщения, присвоенный шлюзом |
| sms_count | integer | Реальное количество SMS к отправке |
| date_completed | datetime, ISO8601 | Дата присвоения финального статуса |
Коды статусов документа¶
При отправке 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 | Превышение лимита выделенных сообщений |