Руководство по подключению сайта/ПО к сервису по протоколу XML POST

Руководство по подключению сайта/ПО к сервису, по протоколу XML POST

Вступление

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

Адрес службы: https://smsbat.com/api/xml.php

Отправка сообщений

Пример отправки SMS сообщения с использованием логина и пароля:

<?xml version="1.0" encoding="utf-8" ?>
<package login="login" password ="pass"> 
<message> 
<msg recipient= "+380….." sender= "SMSbat" type="0">test</msg> 
<msg recipient= "+380….." sender= "SMSbat" type="0">test</msg>
… 
</message> 
</package>
						

где:

  • package

    • login – логин пользователя;
    • password – пароль пользователя.
  • msg – тег сообщения, в качестве параметра возвращается код статуса, может содержать следующие атрибуты:

    • id – (integer) пользовательский числовой идентификатор сообщения, необязательный атрибут, при использовании пользователь должен гарантировать уникальность данного идентификатора в пределах своей учетной записи;
    • recipient – (varchar(21)) получатель сообщения (номер телефона), может использоваться в формате с «+» или без него;
    • sender – (varchar(11)) отправитель сообщения (подпись сообщения), обязательный атрибут;
    • type – (integer) тип сообщения: 0-обычное сообщение, 1-флеш сообщение, 2wap-push сообщение, 3 – голосовое сообщение (только на городские телефоны в Украине).

На полученный запрос сервис возвращает в виде параметра статус сообщения, а в атрибутах идентификаторы присвоенные сообщениям

Статус: 1 – сообщение успешно принято
<?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 к отправке.

Пример отправки SMS сообщения с использованием ключа:

<?xml version="1.0" encoding="utf-8" ?> 
<package key="fcb200c6cf9951b2faea825a1d3ca67b311ee324"> 
<message> 
<msg recipient= "+380…." sender= "SMSbat" type="0">test</msg> 
</message> 
</package> 
						

где:

  • msg – тег сообщения, в качестве параметра возвращается код статуса, может содержать следующие атрибуты:
    • key – ключ авторизации пользователя. Если используется ключ то логин и пароль вводить не нужно;
    • recipient – (varchar(21)) получатель сообщения (номер телефона), может использоваться в формате с «+» или без него;
    • sender – (varchar(11)) отправитель сообщения (подпись сообщения), обязательный атрибут;
    • type – (integer) тип сообщения: 0-обычное сообщение, 1-флеш сообщение, 2wap-push сообщение, 3 – голосовое сообщение (только на городские телефоны в Украине).
  • На полученный запрос сервис возвращает в виде параметра статус сообщения, а в атрибутах идентификаторы присвоенные сообщениям

    Статус: 1 – сообщение успешно принято
    <?xml version="1.0" encoding="utf-8"?> 
    <package>       
    <message> 
    <msg id="0" sms_id="85244344" sms_count="1">1</msg> 
    <msg id="0" sms_id="0" sms_count="0">202</msg> 
    </message> 
    </package> 
    						

    Пример отправки запланированного SMS сообщения:

    <?xml version="1.0" encoding="utf-8" ?> 
    <package login=" login " password ="pass"> 
    <message> 
    <msg recipient= "+380…." sender= "SMSbat" date_beg="2013-01-24T14:30"     
    date_end="2013-01-24T14:35" type="0">test</msg> 
    </message> 
    </package> 
    						

    где:

  • msg – тег сообщения, в качестве параметра возвращается код статуса, может содержать следующие атрибуты:
    • date_beg – (datetime, ISO8601) дата отправки сообщения, необязательный атрибут, указывается для отложенной отправки сообщений;
    • date_end – (datetime, ISO8601) дата, когда сообщение, не дождавшись получателя, будет аннулировано. Необязательный атрибут, указывается для ограничения времени жизни SMS сообщений. Минимально +1 минута, максимально +5 дней с момента отправки SMS. По умолчанию +1 день.
  • На полученный запрос сервис возвращает в виде параметра статус сообщения, а в атрибутах идентификаторы присвоенные сообщениям

    Статус: 1 – сообщение успешно принято
    <?xml version="1.0" encoding="utf-8"?>   
    <package>   
    <message>   
    <msg id="0" sms_id="85244344" sms_count="1">1</msg>   
    <msg id="0" sms_id="0" sms_count="0">202</msg>  
    </message>   
    </package> 
    						

    Пример отправки SMS сообщения Wap-Push ссылка:

    <?xml version="1.0" encoding="utf-8" ?> 
    <package login="login" password ="1234" > 
    <message> 
    <msg recipient= "+380…." sender= "SMSbat" url="http://www.url.com /" type="2">test</msg> 
    </message> 
    </package> 
    						

    где:

    • url – (varchar(100)) ссылка для создания wap-push сообщения;
    • type – (integer) тип сообщения: 0-обычное сообщение, 1-флеш сообщение, 2-wap-push сообщение, 3 – голосовое сообщение (только на городские телефоны в Украине).

    На полученный запрос сервис возвращает в виде параметра статус сообщения, а в атрибутах идентификаторы присвоенные сообщениям

    Статус: 1 – сообщение успешно принято
    <?xml version="1.0" encoding="utf-8"?>  
    <package>
    <message>
    	<msg id="0" sms_id="85244344" sms_count="1">1</msg> 
    <msg id="0" sms_id="0" sms_count="0">202</msg>  
    </message>  
    </package>  
    						

    Коды статусов ошибок при отправке сообщений

    Данные статусы могут быть для каждой смс индивидуально.

    • ERR_UNKNOWN = 200// Неизвестная ошибка
    • ERR_ID = 201// Неправильный ID сообщения
    • ERR_SENDER = 202// Неправильный идентификатор отправителя
    • ERR_RECIPIENT = 203// Неправильный номер получателя
    • ERR_LENGTH = 204// Слишком длинное или пустое сообщение
    • ERR_BILLING = 206// Ошибка биллинга
    • ERR_OVERLIMIT = 207// Превышение лимита выделенных сообщений
    • ERR_DUPLICATE = 208// Сообщение с указанным ID уже существует
    • ERR_DELETE = 211// Ошибка удаления SMS

    Коды статусов ошибок XML запроса

    Данные статусы говорят про ошибку в запросе в целом.

    • ERR_UNKNOWN = 200// Неизвестная ошибка
    • ERR_FORMAT = 201// Неправильный формат документа
    • ERR_AUTHORIZATION = 202// Ошибка авторизации
    • ERR_USER_DISABLE = 205// Пользователь отключен
    • ERR_API_DISABLE => 209// АПИ отключено пользователем
    • ERR_IP_DENIED => 210// IP адрес не разрешен для осуществленя запросов
    • ERR_THROTTLE = 212// Превышение допустимой скорости отправки смс

    Пример ошибки:

    <?xml version="1.0" encoding="utf-8" ?>    
    <package>    
    <error>201</error>    
    </package> 
    						

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

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

    <?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-0314T15: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) дата присвоения финального статуса.

    Коды статусов сообщений

    Данные коды используются при возврате статусов сообщений.

    Статус: 1 – сообщение успешно принято

    • //1** статусы сообщений
    • SCHEDULED = 100// The message is scheduled. Delivery has not yet been initiated.
    • ENROUTE = 101// The message is in enroute state.
    • DELIVERED = 102// Message is delivered to destination.
    • EXPIRED = 103 // Message validity period has expired.
    • DELETED = 104// Message has been deleted.
    • UNDELIVERABLE = 105// Message is undeliverable.
    • ACCEPTED = 106 // Message is in accepted state (i.e. has been manually read on behalf of the subscriber by customer service)
    • UNKNOWN = 107// Message is in invalid state The message state is unknown.
    • REJECTED = 108// Message is in a rejected state The message has been rejected by a delivery interface.
    • DISCARDED = 109// Message discarded
    • SENDING = 110// Message in process of transferring to mobile network
    • NOT_SUPPORTED = 111//Receiver’s operator is not supported. Message will not be billed.
    • WRONG_ALPHANAME = 112// Alphaname (sender’s name) was not approved by operator. Only for Life:) Ukraine.
    • WRONG_ALPHANAME_RETURNED = 113// Alphaname (sender’s name) was not approved by operator. Money for this SMS was returned. Only for Life:) Ukraine.

    Проверка баланса

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

    Пример отправки SMS сообщения с использованием логина и пароля:

    <?xml version="1.0" encoding="utf-8" ?> 
    <package login="login" password="123456"> 
    <balance></balance> 
    </package> 
    						

    В ответ на запрос возвращается XML документ содержащий информацию о балансе пользователе и валюте счета, либо соответствующие коды ошибок

    <?xml version="1.0" encoding="utf-8" ?> 
    <package> 
    <balance> 
    <amount>7.15</amount> 
    <currency>UAH</currency> 
    </balance> 
    </package> 
    						

    где:

    • balance – тег сообщения для которого происходит запрос баланса, в качестве параметра возвращается сумма баланса и валюта, содержит следующие атрибуты:
      • amount – (float) сумма текущего баланса;
      • currency – (string) буквенное обозначение валюты.

    Пример отправки SMS сообщения с использованием ключа:

    <?xml version="1.0" encoding="utf-8" ?> 
    <package key="fcb200c6cf9951b2faea825a1d3ca67b311ee324"> 
    <balance></balance> 
    </package> 
    						

    В ответ на запрос возвращается XML документ содержащий информацию о балансе пользователе и валюте счета, либо соответствующие коды ошибок

    <?xml version="1.0" encoding="utf-8"?> 
    <package> 
    <balance> 
    <amount>10.526</amount>  
    <currency>UAH</currency>  
    </balance>  
    </package>
    						

    Запрос на удаление SMS из очереди

    Выполняется аналогично запросу статуса сообщения.

    Сообщение может быть удалено из очереди, если сообщение еще не было отправлено оператору.

    <?xml version="1.0" encoding="utf-8" ?> 
    <package login="login" password="123456"> 
    <delete> 
    <msg id="1234"/> 
    <msg sms_id="1234568"/> 
    </delete> 
    </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-0314T15:27:03">102</msg>  
    <msg sms_id="1234568" sms_count="1">1</msg>  
    </status>  
    </package> 
    						

    где:

    • msgg – тег сообщения для которого происходит запрос статуса, в качестве параметра возвращается код статуса, может содержать следующие атрибуты:
      • id – (integer) пользовательский числовой идентификатор сообщения, необязательный атрибут, возвращается при указании данного атрибута в запросе;
      • sms_id – (integer) числовой идентификатор сообщения присвоенный шлюзом;
      • sms_count – (integer) реальное количество SMS к отправке;
      • date_completed – (datetime, ISO8601) дата присвоения финального статуса.

    Асинхронная отправка сообщений

    Большой пакет сообщений можно отправить асинхронно. Система принимает все сообщения на отправку, в ответ выдает ID задачи, по которой потом можно узнать статус и результат ее выполнения.

    Способ отправки аналогичен обычным сообщениям, только тег message надо заменить на тег message-async

    <message-async> 
    <msg recipient= "+380….." sender= "SMSbat" type="0">test</msg> 
    <msg recipient= "+380….." sender= "SMSbat" type="0">test</msg> 
    … 
    </message-async> 
    						

    В случае успешной постановки задачи в ответ на запрос возвращается XML документ содержащий ID задачи.

    <?xml version="1.0" encoding="utf-8" ?> 
    <package>  
    <message-async>  
    <job>8714ea91e9bb454d25ef42ba6f18ea4e></job>  
    </message-async> 
    </package> 
    						

    где:

    • job – тег содержащий ID задачи (varchar(64)).

    Запрос результатов асинхронной задачи

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

    <?xml version="1.0" encoding="utf-8" ?> 
    <package login="login" password="123456"> 
    <job>job_id_here></ job > 
    </package> 
    						

    где:

    • job_id_here – ID задачи полученный при асинхронной отправке.

    В ответ придейт XML следующего вида:

    <?xml version="1.0" encoding="utf-8" ?> 
    <package>  
    <job>   
    <progress>50</progress>   
    <status>text</status>  
    </job> 
    </package> 
    						

    где:

    • progress – (int(0, 100)) числовое значение в процентах количества обработанных сообщений.
    • status – (string) текущий статус задачи. Возможен один из следующих вариантов:
    • WAITING – задача ожидает в очереди на выполнение
    • RUNNING – задача выполняется
    • FAILED – ошибка при выполнении задачи. Возможно часть сообщений принято в отправку. Это можно узнать запросив статусы доставку сообщений по пользовательскому ID
    • COMPLETE – задача выполнена
    • NOTFOUND – задача не найдена

    В случае если статус = COMPLETE, тогда в ответе будет тег message аналогичный ответу при обычной отправке смс.

    Проверка стоимости отправки сообщения

    По переданным номерам проверят стоимость отправки одной части смс. Стоимость выдается в валюте пользователя.

    <?xml version="1.0" encoding="utf-8" ?> 
    <package login="login" password="123456"> 
    <prices>   
    <phone>380501234567</phone>   
    <phone>37122123456</phone> 
    </prices> 
    </package> 
    						

    где:

    • phone – тег c номером телефона, для которого надо определить стоимость отправки смс

    В ответ на запрос возвращается XML документ содержащий стоимость и валюту для запрошенных номеров, либо соответствующие коды ошибок

    Если доставка на указанный номер не возможна – то аттрибут price будет равен нулю.

    <?xml version="1.0" encoding="utf-8" ?> 
    <package> 
    <prices>  
    <phone price="0.28" currency="UAH" >380501234567</phone>  
    <phone price="1.6" currency="UAH">37122123456</phone> 
    </prices>  
    </package> 
    						

    где:

    • phone – тег с номером телефона для которого определялась стоимость, в качестве параметра возвращается стоимость и валюта, может содержать следующие атрибуты:
      • price – (float) стоимость отправки одной части смс. Если значение 0 – то отправка на данный номер не поддерживается.
      • currency – (string) ISO код валюты, например UAH, RUB, USD, EUR. Если параметр пустой – то считать цену, в валюте пользователя.