XML API

Обзор

Документация включает описание API для отправки SMS-сообщений через платформу Devino Telecom с примерами запросов. API включает в себя возможность как транзакционных, так и массовых рассылок, получение подробной статистики по рассылкам. Документ предназначен для разработчиков, которые хотят добавить возможность взаимодействия с Сервисом отправки SMS-сообщений на страницы своих сайтов или в свои приложения. Общение с сервисом осуществляется при помощи отправки XML запросов в кодировке UTF-8 на заданный адрес сервиса по протоколу HTTPS методом POST, проверка типа контента не осуществляется. Каждый запрос может состоять из отправляемых сообщений и (или) запросов для получения статусов и (или) запросов для получения входящих сообщений. Авторизация пользователя происходит путем передачи учетных сведений в теге package, обязательна при выполнении любых запросов.

Предупреждение

Внимание! Для использования данного вида интеграции необходимо обратиться к своему менеджеру, либо в техническую поддержку support@devinotele.com для настройки доступа.

Сервис доступен по адресу:

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 к отправке

Запрос статусов сообщений

Статусы сообщений содержат информацию о текущем состоянии сообщения, регулярно обновляются и могут быть запрошены пользователем в любое время. Статусы можно запрашивать за последний 7 календарных дней.

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

<?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 Превышение лимита выделенных сообщений