Часто задаваемый вопрос

Руководство по взаимодействию с сервисом коротких сообщений (SMS) на основе HTTPS протокола в XML формате

Последнее Обновление около месяца назад

Общие принципы отправки

На определенный адрес сервера отправляются XML документы (описание XML документов, их назначение и адреса сервера приведены ниже). При этом используется POST метод.

Заголовки отправляемых данных должны содержать:

Content-type: text/xml; charset=utf-8

Пример передачи XML документа на php

$src = '<?xml version="1.0" encoding="utf-8"?>
<request>
<security>
<login value="логин" />
<password value="пароль" />
</security>
</request>';
// XML-документ
$href = 'https://server/script.php'; // адрес сервера
$ch = curl_init();
curl_setopt ($ch, CURLOPT_HTTPHEADER, array ('Content-type: text/xml','charset=utf-8','Expect:'));
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt ($ch, CURLOPT_CRLF, true);
curl_setopt ($ch, CURLOPT_POST, true);
curl_setopt ($ch, CURLOPT_POSTFIELDS, $src);
curl_setopt ($ch, CURLOPT_URL, $href);
$result = curl_exec($ch);
curl_close($ch);
echo $result;

Отправка SMS

Адрес сервера:

https://имя_хоста/xml/
XML-документ:

<?xml version="1.0" encoding="utf-8" ?>
<request>
<security>
    <login value="логин" />
    <password value="пароль" />
</security>
<message type="sms">
    <sender>Отправитель 1</sender>
    <text>Текст сообщения 1</text>
    <translite>1</translite>
    <name_delivery>Рассылка 1</name_delivery>
    <abonent phone="79001234567" number_sms="1" client_id_sms="101" time_send="2001-12-31 12:34" validity_period="2001-12-31 15:34" />
    <abonent phone="79001234567" number_sms="2" client_id_sms="102" time_send="2001-12-31 12:35" />
    <abonent phone="79001234567" number_sms="10" client_id_sms="110" time_send="" />
</message>
<message>
    <sender>Отправитель 2</sender>
    <text>Текст сообщения 2</text>
    <name_delivery>Рассылка 2</name_delivery>
    <abonent phone="79001234567" number_sms="11" client_id_sms="111" />
    <abonent phone="79001234567" number_sms="12" client_id_sms="112" />
    <abonent phone="79001234567" number_sms="20" client_id_sms="120" />
</message>
</request>

Где

  • type - тип отправляемого SMS сообщения:
    • sms – обычная SMS.
  • sender – отправитель SMS. Именно это значение будет выводиться на телефоне абонента в поле от кого SMS.
  • text – текст SMS.
  • name_delivery – Название рассылки. По умолчанию "Шлюз";
  • translite - транслитерация текста СМС с кириллицы на латиницу (не обязательный параметр). Для транслитерации данный параметр должен быть равен 1.
  • phone – номер абонента, которому адресована SMS. В международном формате, например, 79000000001 (Для России), 380442589632 (Для Украины) и т.д.
  • логин - ваш логин в системе.
  • пароль - ваш пароль в системе.
  • number_sms - номер сообщения в пределах отправляемого XML документа.
  • client_id_sms - число. Необязательный параметр, позволяет избежать повторной отправки. Если раннее с этого аккаунта уже было отправлено SMS с таким номером, то повторная отправка не производится, а возвращается номер ранее отправленного SMS.
  • time_send – дата и время отправки в формате: YYYY-MM-DD hh:mm где, YYYY-год, MM-месяц, DD-день, hh-часы, mm-минуты. Если не задано, то SMS отправляется сразу же.
  • validity_period – дата и время, после которых не будут делаться попытки доставить SMS в формате: YYYY-MM-DD hh:mm , где YYYY-год, MM-месяц, DD-день, hh-часы, mm-минуты. Если не задано, то SMS имеет максимальный срок жизни.
В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе

<?xml version="1.0" encoding="utf-8"?>
<response>
<error>текст ошибки</error>
</response>

error - текст ошибки может принимать следующие значения:

  1. Неправильный формат XML документа
  2. Ваш аккаунт заблокирован
  3. Неправильный логин или пароль
  4. POST данные отсутствуют

В случае получения правильного XML-документа

<?xml version="1.0" encoding="utf-8" ?>
<response>
<information number_sms="1" id_sms="ID SMS в системе для проверки статуса" parts="2">Статус/сообщение об ошибке</information>
<information number_sms="2" id_sms="ID SMS в системе для проверки статуса" parts="2">Статус/сообщение об ошибке</information>
<information number_sms="3" id_sms="ID SMS в системе для проверки статуса" parts="2">Статус/сообщение об ошибке</information>
</response>

Где:

  • number_sms - номер сообщения указанный при отправке XML документа.
  • id_sms - номер SMS сообщения. Используется для проверки статуса SMS. Если в процессе отправки SMS произошла ошибка, то id_sms не передается.
  • parts - количество частей SMS.
  • information - статус сообщения («send»), если SMS была отправлена. Или сообщение об ошибке, если в процессе отправки SMS произошла ошибка:
    1. У нас закончились SMS. Для разрешения проблемы свяжитесь с менеджером.
    2. Закончились SMS.
    3. Аккаунт заблокирован.
    4. Укажите номер телефона.
    5. Номер телефона присутствует в стоп-листе.
    6. Данное направление закрыто для вас.
    7. Данное направление закрыто.
    8. Недостаточно средств для отправки SMS. SMS будет отправлена как только вы пополните счет по данному направлению.
    9. Текст SMS отклонен модератором.
    10. Нет отправителя.
    11. Отправитель не должен превышать 15 символов для цифровых номеров и 11 символов для буквенно-числовых.
    12. Номер телефона должен быть меньше 15 символов.
    13. Нет текста сообщения.
    14. Нет ссылки.
    15. Такого отправителя Нет.
    16. Отправитель не прошел модерацию.
    17. Данное сообщение уже было отправлено.

Запрос статуса SMS сообщения (первый способ)

Адрес сервера:

https://имя_хоста/xml/state.php
XML-документ:

<?xml version="1.0" encoding="utf-8" ?>
<request>
<security>
    <login value="логин" />
    <password value="пароль" />
</security>
<get_state>
    <id_sms>IDSMS в системе для проверки статуса</id_sms>
    <id_sms>IDSMS в системе для проверки статуса</id_sms>
    <id_sms>IDSMS в системе для проверки статуса</id_sms>
    <id_sms>IDSMS в системе для проверки статуса</id_sms>
</get_state>
</request>

Где

  • логин - ваш логин в системе.
  • пароль - ваш пароль в системе.
  • id_sms - номер SMS сообщения, полученный в ответном XML-документа в процессе отправки SMS сообщения.
В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе:

<?xml version="1.0" encoding="utf-8"?>
<response>
<error>текст ошибки</error>
</response>

error - текст ошибки может принимать следующие значения:

  1. Неправильный формат XML документа
  2. Неправильный логин или
  3. POST данные отсутствуют

В случае получения правильного XML-документа:

<?xml version="1.0" encoding="utf-8" ?>
<response>
<state id_sms="IDSMS в системе для проверки статуса" time="2017-01-01 12:57:46" num_parts="2" price="1.15">Статус</state>
<state id_sms="IDSMS в системе для проверки статуса" time="2017-01-01 12:57:46" num_parts="2" price="1.15">Статус</state>
<state id_sms="IDSMS в системе для проверки статуса" time="2017-01-01 12:57:46" num_parts="2" price="1.15">Статус</state>
</response>

Где

  • id_sms - номер SMS сообщения, полученный в ответном XML-документа в процессе отправки SMS сообщения.
  • time - время изменения статуса.
  • state - статус сообщения:
    1. «send» - статус сообщения не получен. В этом случае передается пустой time (time="").
    2. «not_deliver» - сообщение не было доставлено. Конечный статус (не меняется со временем).
    3. «expired» - абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный Статус (не меняется со временем.
    4. «deliver» - сообщение доставлено. Конечный статус (не меняется со временем)
    5. «partly_deliver» - сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки.
  • num_parts - Количество частей в СМС.
  • price - Цена за одну часть СМС.

Получение статуса SMS сообщения (второй способ)

При использовании данного способа необходимо сообщить менеджеру адрес вашего сервера, который будет принимать статусы SMS. XML-документ будет отправлен POST методом.

К примеру, в php XML-документ будет доступен через переменную

$GLOBALS['HTTP_RAW_POST_DATA']

Система отправляет XML-документ серверу клиента следующего содержания:

<?xml version="1.0" encoding="utf-8"?>
<request>
    <state id_sms="ID SMS в системе для проверки статуса" time="2017-01-01 12:57:46">Статус</state>
    <state id_sms="ID SMS в системе для проверки статуса" time="2017-01-01 12:57:46">Статус</state>
</request>

Где:

  • id_sms - номер SMS сообщения, полученный в ответном XML-документа в процессе отправки SMS сообщения.
  • state - статус сообщения:
    1. «send» - статус сообщения не получен. В этом случае передается пустой time (time="").
    2. «not_deliver» - сообщение не было доставлено. Конечный статус (не меняется со временем).
    3. «expired» - абонент находился не в сети в те моменты, когда делалась попытка доставки. Конечный Статус (не меняется со временем).
    4. «deliver» - сообщение доставлено. Конечный статус (не меняется со временем).
    5. «partly_deliver» - сообщение было отправлено, но статус так и не был получен. Конечный статус (не меняется со временем). В этом случае для разъяснения причин отсутствия статуса необходимо связаться со службой тех. поддержки.
В ответ сервер клиента должен вернуть XML-документ следующего содержания:

<?xml version="1.0" encoding="utf-8" ?>
<response>
<id_sms>3234</id_sms>
<id_sms>3234</id_sms>
</response>

Где:

  • id_sms - номер SMS сообщения, полученный в ответном XML-документа в процессе отправки SMS сообщения.
  • time - время изменения статуса.
Если сервер клиента не передаст id_sms, то статус будет считаться не полученным клиентом. При этому будет сделано 5 попыток доставить статус.

Запрос проверки баланса

Адрес сервера:

https://имя_хоста/xml/balance.php
XML-документ:

<?xml version="1.0" encoding="utf-8" ?>
<request>
<security>
    <login value="логин" />
    <password value="пароль" />
</security>
</request>

Где

  • логин - ваш логин в системе.
  • пароль - ваш пароль в системе.
В ответ может быть выдан один из следующих XML-документов:

  1. В случае возникновения ошибки в отправляемом XML-документе:
<?xml version="1.0" encoding="utf-8"?>
<response>
<error>текст ошибки</error>
</response>

error - текст ошибки может принимать следующие значения:

  1. Неправильный формат XML документа
  2. Неправильный логин или пароль
  3. POST данные отсутствуют
  4. В случае получения правильного XML-документа:
<?xml version="1.0" encoding="utf-8" ?>
<response>
<money currency="RUR">150</money>
<sms area="Россия">111</sms>
<sms area="Украина">111</sms>
</response>

Где:

  • money - остаток средств.
  • area - направление в котором может быть отправлено данное количество SMS.
  • sms - количество доступных SMS сообщений для данного направления.
При этом количество SMS не может быть суммировано по разным направлениям. При отправке смс в одном направлении уменьшается количество доступных SMS сообщений во всех других направлениях в соответствии с их стоимостью.

Пример

У вас на балансе 10 y.e.

Стоимость SMS сообщения отправленного в Россию составляет 1 y.e.

Стоимость SMS сообщения отправленного в Украину составляет 2 y.e.

При этом вам вернется XML документ следующего содержания.

<?xml version="1.0" encoding="utf-8" ?>
<response>
<money>10</money>
<sms area="Россия">10</sms>
<sms area="Украина">5</sms>
</response>

Если вы отправите две смс в Россию, то XML-документ изменится следующим образом:

<?xml version="1.0" encoding="utf-8" ?>
<response>
<money>8</money>
<sms area="Россия">8</sms>
<sms area="Украина">4</sms>
</response>

Запрос на получения списка отправителей

Адрес сервера:

https://имя_хоста/xml/originator.php
XML-документ:

<?xml version="1.0" encoding="utf-8" ?>
<request>
<security>
    <login value="логин" />
    <password value="пароль" />
</security>
</request>

Где:

  • логин - ваш логин в системе.
  • пароль - ваш пароль в системе.
В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе:

<?xml version="1.0" encoding="utf-8"?>
<response>
<error>текст ошибки</error>
</response>

error - текст ошибки может принимать следующие значения:

  1. Неправильный формат XML документа
  2. Неправильный логин или пароль
  3. POST данные отсутствуют

В случае получения правильного XML-документа:

<?xml version="1.0" encoding="utf-8" ?>
<response>
<any_originator>FALSE</any_originatоr>
<list_originator>
    <originator state="rejected">Отправитель</originator>
</list_originator>
</response>

Где

  • any_originator - TRUE/FALSE - может ли клиент отправлять от любого отправителя или только от заранее одобренных. Если TRUE, то клиент может использовать любого отправителя. При этом список отправителей не возвращается. FALSE – можно использовать только отправителей со статусом «completed».
  • state - статус отправителя:
    1. order – оформляется
    2. completed - готов к использованию
    3. rejected – отклонен

Запрос входящих SMS

Адрес сервера:

https://имя_хоста/xml/incoming.php
XML-документ:

<?xml version="1.0" encoding="utf-8" ?>
<request>
    <security>
        <login value="логин" />
        <password value="пароль" />
    </security>
<time start="2017-01-31 12:23:00" end="2017-02-31 12:23:00" />
</request>

Где

  • login value - ваш логин в системе.
  • password value - ваш пароль в системе.
  • time start - время (не включительно), с которого запрашиваются входящие SMS.
  • time end - время (не включительно), по которое запрашиваются входящие SMS. Не обязательный параметр. Если не задан, то будут возвращены все смс.
В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе:

<?xml version="1.0" encoding="utf-8"?>
<response>
<error>текст ошибки</error>
</response>

error -

  1. Неправильный формат XML документа
  2. Неправильный логин или пароль
  3. POST данные отсутствуют

В случае получения правильного XML-документа:

<?xml version="1.0" encoding="utf-8" ?>
<response>
<sms id_sms="1234" date_receive="2017-01-31 12:50:31" originator="79001234567" prefix="MAGZ" phone="79001111111">ТекстСМС.</sms>
<sms id_sms="1234" date_receive="2017-01-31 12:50:31" originator="79001234567" prefix="MAGZ" phone="79001111111">ТекстСМС.</sms>
</response>

Где

  • id_sms - уникальный номер, состоящий только из цифр.
  • date_receive - дата и время получения SMS.
  • originator - номер телефона абонента, отправившего SMS.
  • prefix - префикс. Начальная часть текста SMS, по которой было определено, что эта SMS принадлежит именно этому клиенту. (Используется если один и тот же номер используется разными клиентами).
  • phone - номер телефона, на который бала отправлена SMS.
  • sms - текст смс.

Запрос на получение информации по номеру телефона

Адрес сервера:

https://имя_хоста/xml/def.php
XML-документ:

<?xml version="1.0" encoding="utf-8" ?>
<request>
<security>
    <login value="логин" />
    <password value="пароль" />
</security>
<phones>
    <phone>79612242243</phone>
    <phone>79612242244</phone>
</phones>
</request>

Где:

  • login value - ваш логин в системе.
  • password value - ваш пароль в системе.
  • phone - Номер телефона.
В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе:

<?xml version="1.0" encoding="utf-8"?>
<response>
<error>текст ошибки</error>
</response>

error -

  1. Неправильный формат XML документа
  2. Неправильный логин или пароль
  3. POST данные отсутствуют

В случае получения правильного XML-документа:

<?xml version="1.0" encoding="utf-8" ?>
<response>
<phone operator="МТС" region="Самарскаяобласть" time_zone="1">79001234567</phone>
<phone operator="МТС" region="Калининград" time_zone="-1">79007654321</phone>
</response>

Где:

  • operator - Оператор.
  • region - Регион.
  • time_zone - Смещение времени в часах относительно времени в Москве.
  • phone - номер телефона.

Запрос на получение списка баз

Адрес сервера:

https://имя_хоста/xml/list_bases.php
XML-документ:

<?xml version="1.0" encoding="utf-8" ?>
<request>
    <security>
        <login value="логин" />
        <password value="пароль" />
    </security>
</request>

Где:

  • login value - ваш логин в системе.
  • password value - ваш пароль в системе.
В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе:

<?xml version="1.0" encoding="utf-8"?>
<response>
<error>текст ошибки</error>
</response>

error - текст ошибки может принимать следующие значения:

  1. Неправильный формат XML документа
  2. Неправильный логин или пароль
  3. POST данные отсутствуют

В случае получения правильного XML-документа:

<?xml version="1.0" encoding="utf-8" ?>
<response>
<base id_base="1234" name_base="Базаглавногоофиса" time_birth="12:48" local_time_birth="yes" day_before="1" originator_birth="fitnes" on_birth="yes">Поздравляем!</base>
<base id_base="1235" name_base="БазаСамарскогоофиса" time_birth="12:48" local_time_birth="yes" day_before="1" originator_birth="fitnes" on_birth="yes">Поздравляем!</base>
</response>

Где:

  • id_base - уникальный номер базы в системе.
  • name_base - название базы.
  • time_birth - время поздравления.
  • local_time_birth - читать время поздравления относительно местного времени абонента(yes) или относительно времени системы (no).
  • day_before - за сколько дней до дня рождения поздравлять.
  • originator_birth - отправитель поздравления.
  • on_birth - включены ли поздравления yes – включены, no - выключены.
  • base - текст поздравления.

Запрос на изменение параметров/добавление/удаление баз

Адрес сервера:

https://имя_хоста/xml/bases.php
XML-документ:

<?xml version="1.0" encoding="utf-8" ?>
<request>
<security>
    <login value="логин" />
    <password value="пароль" />
</security>
<bases>
    <base id_base="1234" name_base="Базаглавногоофиса" time_birth="12:48" local_time_birth="yes" day_before="1" originator_birth="fitnes" on_birth="yes">Поздравляем!</base>
    <base number_base="1" name_base="БазаСамарскогоофиса" time_birth="12:48" local_time_birth="yes" day_before="1" originator_birth="fitnes" on_birth="yes">Поздравляем!</base>
</bases>
<delete_bases>
    <base id_base="1235" />
    <base id_base="1236" />
</delete_bases>
</request>

Где:

  • login value - ваш логин в системе.
  • password value - ваш пароль в системе.
  • id_base - уникальный номер базы в системе. Если не указан произойдет добавление базы. При этом нужно указать параметр number_base.
  • number_base - номер базы в XML запросе. Указывается только при создании новой базы. Используется для сопоставления ID добавленных баз (если их было не сколько в запросе).
  • name_base - название базы.
  • time_birth - время поздравления.
  • local_time_birth - считать время поздравления относительно местного времени абонента (yes) или относительно времени системы (no).
  • originator_birth - отправитель поздравления.
  • on_birth - включены ли поздравления yes – включены, no - выключены.
  • base - текст поздравления.
В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе:

<?xml version="1.0" encoding="utf-8"?>
<response>
<error>текст ошибки</error>
</response>

error - текст ошибки может принимать следующие значения:

  1. Неправильный формат XML документа
  2. Неправильный логин или пароль
  3. POST данные отсутствуют

В случае получения правильного XML-документа:

<?xml version="1.0" encoding="utf-8" ?>
<response>
<base id_base="1234">edit</base>
<base number_base="1" id_base="1235">insert</ base>
<base number_base="2" id_base="1236">edit</ base>
<base id_base="1235">delete</ base>
<base id_base="1235">not_found</ base>
</response>

Запрос на получение списка абонентов базы

Адрес сервера:

https://имя_хоста/xml/list_phones.php
XML-документ:

<?xml version="1.0" encoding="utf-8" ?>
<request>
<security>
    <login value="логин" />
    <password value="пароль" />
</security>
<base id_base="1234" page="1" last_update="2017-07-21 09:01:15"/>
</request>

Где:

  • login value - ваш логин в системе.
  • password value - ваш пароль в системе.
  • baseid_base - номер базы в системе.
  • basepage - номер страницы. Весь список номеров базы делится на страницы. Запросить целиком базу нельзя. Можно лишь запросить отдельную страницу. Нумерация начинается с единички.
  • last_update - минимальная дата и время регистрации (или последнего изменения) данных абонента, которых Вам нужно запросить.
В ответ может быть выдан один из следующих XML-документов:

В случае возникновения ошибки в отправляемом XML-документе:

<?xml version="1.0" encoding="utf-8"?>
<response>
<error>текст ошибки</error>
</response>

error - текст ошибки может принимать следующие знач

Категории Заявок
  • Техническая поддержка / Работа с API

Пожалуйста, подождите!

Пожалуйста подождите... это не займёт много времени!