Наши телефоны
mirsms.rumirsms.ru → API

API для отправки смс сообщений через протокол HTTP (SMS).

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

Обычно SMS-шлюз, в котором задействован HTTP-протокол для рассылки сообщений, предоставляет следующие возможности для настройки протокола:

Содержание

Протокол HTTP (SMS). Его применение для отправки / обработки сообщений.

Описание отсылки SMS сообщений через протокол HTTP.

Данный протокол используется в веб-разработке и представлен, как правило, определенным набором HTTP-запросов и HTTP-ответов.

Для работы класса требуется PHP 5

Входные параметры

1. Авторизация

Авторизация требуется при каждом подключении к серверу независимо от дальнейших действий.



Параметр Значение По умолчанию
user
Логин для входа в систему на сайте
http://web.mirsms.ru
-
pass
Пароль для входа в систему на сайте
http://web.mirsms.ru
-
gzip
none - не использовать Content-encoding: gzip none
HTTP_ACCEPT_LANGUAGE
Переменная клиента, предпочтение относительно
языка (необязательный параметр).
-
CLIENTADR IP адрес клиента (необязательный параметр) IP сервера
comment
Описание подключения (необязательный параметр;
до 512 символов)
-


2. Отправка сообщения

SMS сообщение



Параметр Значение По умолчанию
action post_sms -
message текст сообщения -
target
Список адресатов через запятую. (Н-р: «+70010001212,
80009990000»).
(Разрешается использование только или "target", или
"phl_codename")
-
phl_codename
Кодовое имя контакт-листа в системе //web.mirsms.ru.
(Разрешается использование только или "target" или
"phl_codename")
-
sender
Имя отправителя, зарегистрированного для Вас в системе
//web.mirsms.ru.
Имя
отправителя
по умолчанию
post_id
пользовательский ID рассылки, необязательный параметр,
возвращается обратно в неизменном виде.
-
period
Время жизни сообщения в секундах. Необязательный
параметр. Максимальное время, в течение которого
сообщение должно быть доставлено на телефон. Если в
течение этого времени доставка не возможна (например,
абонент не в зоне действия сети), сообщение не будет
доставлено вовсе. Внимание, данная функция может не
работает для некоторых направлений, например для CDMA
телефонов.
-
sms_type
Тип SMS:
  • Пустое значение: Простое SMS
  • W: Wap push сообщение
  • F: Flash SMS сообщение
  • Пустое
    значение
    wap_url
    HTTP ссылка с текста сообщения (//.....).
    Используется только для sms_type = W, то есть Wap
    push сообщения.
    -
    wap_expires
    Дата и время, когда истекает срок доставки Wap push
    сообщения.
    (Формат: dd.mm.yyyy hh:ii:ss (дд.мм.гггг чч:ми:сс))
    -


    3. Получение статусов сообщений асинхронно

    Данный вариант позволяет получать статусы сообщений в реальном времени. Для настройки укажите в Личном кабинете > Услуги «URL скрипта для приёма статуса отправленных SMS».Как
    только система получает статус сообщения, она немедленно пересылает вам его по HTTP протоколу с помощью POST запроса.


    Формат данных:


    Параметр Значение
    ORDID
    Номер сообщения (соответствует значению атрибута ID тэга SMS, возвращаемого
    при отправке сообщения)
    CNRID ID контрагента
    RESCOUNT Количество сообщений для тарификации.
    STATUS
    Код статуса:
  • 2 - сообщение доставлено
  • 3 - время попыток доставить сообщение оператором истекло
  • 5 - сообщение не может быть доставлено (ошибка в номере, номер не
    существует и т.д.)
  • 8 - сообщение не принято оператором
  • 20 - отправка отменена пользователем
  • 21 - системная ошибка
  • 22 - оператор не сообщил о состоянии сообщения за отведенное время.
  • FINALTIME время получения финального статуса в UTC


    4. Получение данных и статусов сообщений

    action = status

    Три варианта получения статусов для сообщений:

    Параметр Значение
    sms_id
    Номер сообщения (соответствует значению атрибута ID тэга SMS,
    возращаемого при отправке сообщения)
    sms_group_id
    Номер рассылки (соответствует значению атрибута sms_group_id тэга result,
    возращаемого при отправке сообщений)
    date_from,
    date_to
    Данные по всем сообщениям за период времени от date_from до date_to.
    (Формат date_from, date_to: dd.mm.yyyy hh:ii:ss (дд.мм.гггг чч:ми:сс))


    5. Получение текущего баланса

    Параметр Значение
    action balance


    6. Получение входящих сообщений

    Параметр Значение
    По
    умолчанию
    action inbox -
    sib_num
    Номер входящего ящика
    (Обязательный параметр, соответствует значению "ID ящика"
    в закладке "Настройки")
    -
    new_only
    Статус сообщений:
  • 1 - только новые непрочитанные сообщения
  • 0 - все сообщения
  • 0
    date_from,
    date_to
    Данные по всем сообщениям за период времени от date_from
    до date_to.
    (Формат date_from, date_to: dd.mm.yyyy hh:ii:ss (дд.мм.гггг
    чч:ми:сс))


    Примеры использования протокола

    Пример 1. Отправка одного сообщения по адресатам.

    Запрос

    POST= (
    [user] => userX
    [pass] => ***
    [action] => post_sms
    [message] => Привет
    [target] => +79999999991, +79999999992, +7999999999999
    [post_id] => x124127456
    [period] => 600
    [CLIENTADR] => 127.0.0.1
    [HTTP_ACCEPT_LANGUAGE] => ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3
    )


    Результат XML

    <output>
    <result>
    <sms post_id="x124127456" id="99991" smstype="SENDSMS"
    phone="+79999999991" sms_res_count="1"><![CDATA[Привет]]></sms>
    <sms post_id="x124127456" id="99992" smstype="SENDSMS"
    phone="+79999999992" sms_res_count="1"><![CDATA[Привет]]></sms>
    </result>
    <errors>
    <error code="-20117" post_id="x124127456">Неправильный номер телефона:
    +7999999999999</error>
    </errors>
    </output>

    Использование PHP-класса

    <?php
    Include('QTSMS.class.php');
    // Отправка SMS сообщения по списку адресатов
    $sms_text='Привет';
    $target='+79999999991, +79999999992, +7999999999999';
    $sender='vasya';
    $period=600;
    $sms= new QTSMS('userX.Y','пароль','web.mirsms.ru');
    $result=$sms->post_message($sms_text, $target, $sender, 'x124127456',
    $period);
    // результат XML
    echo $result;
    // Отправка SMS по кодовому имени контакт листа
    $sms_text='Привет';
    $phl_codename='druzya';
    $result=$sms->post_message_phl($sms_text, $phl_codename, $sender,
    'x124127456', $period);
    header("Content-Type: text/xml; charset=UTF-8");
    // результат XML
    echo $result;
    ?>


    Пример 2. Получение данных сообщения id=6666

    Запрос

    POST= (
    [action] => status
    [sms_id] => 6666
    [user] => userX
    [pass] => ***
    [CLIENTADR] => 127.0.0.1
    [HTTP_ACCEPT_LANGUAGE] => ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3
    )
    Результат XML
    <output>
    <MESSAGES>
    <MESSAGE SMS_ID="6666" SMSTYPE="SENDSMS">
    <CREATED>24.12.07 15:57:45</CREATED>
    <AUL_USERNAME>userX.Y</AUL_USERNAME>
    <AUL_CLIENT_ADR>127.0.0.1</AUL_CLIENT_ADR>
    <SMS_SENDER>SenderName</SMS_SENDER>
    <SMS_TARGET>89999991111</SMS_TARGET>
    <SMS_RES_COUNT>1</SMS_RES_COUNT>
    <SMS_TEXT>
    <![CDATA[ Привет ]]>
    </SMS_TEXT>
    <SMSSTC_CODE>wait</SMSSTC_CODE>
    <SMS_STATUS>Сообщение в процессе доставки</SMS_STATUS>
    <SMS_CLOSED>0</SMS_CLOSED>
    <SMS_SENT>0</SMS_SENT>
    </MESSAGE>
    </MESSAGES>
    </output>


    Использование PHP-класса

    <?php
    // Получение статуса SMS сообщений
    Include('QTSMS.class.php');
    $sms= new QTSMS('userX.Y','пароль','service.qtelecom.ru');
    // данные о сообщении SMS_ID=6666
    $r_xml1=$sms->status_sms_id(6666);
    // данные о сообщениях отправки SMS_GROUP_ID=110
    $r_xml2=$sms->status_sms_group_id(110);
    // Получить данные сообщений отправленных с 18.12.2007 00:00:00 по
    23.12.2007 23:00:00
    $r_xml3=$sms->status_sms_date('18.12.2007 00:00:00','23.12.2007 23:00:00');
    header("Content-Type: text/xml; charset=UTF-8");
    echo $r_xml1; // результат XML
    //echo $r_xml2;
    //echo $r_xml3;
    ?>


    Пример 3. Отправка сообщений и получение статусов

    Запрос

    POST= (
    [data] => Array (
    [0] => Array (
    [action] => post_sms
    [message] => Привет!
    [sender] =>
    [target] => +79999999999, +79999999992
    )
    [1] => Array (
    [action] => post_sms
    [message] => С днём рождения!
    [sender] =>
    [target] => +79999999991
    )
    [2] => Array (
    [action] => status
    [sms_id] => 6666
    )
    )
    [user] => userX
    [pass] => ***
    [CLIENTADR] => 127.0.0.1
    [HTTP_ACCEPT_LANGUAGE] => ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3
    )


    Результат XML

    <output>
    <result sms_group_id="996">
    <sms id="99991" smstype="SENDSMS" phone="+79999999991"
    sms_res_count="1"><![CDATA[Привет]]></sms>
    <sms id="99992" smstype="SENDSMS" phone="+79999999992"
    sms_res_count="38"><![CDATA[С днём рождения!]]></sms>
    </result>
    <errors>
    <errors>
    <error code="-20117" post_id="x425256">Неправильный номер телефона:
    +7999999999999</error>
    </errors>
    <MESSAGES>
    <MESSAGE SMS_ID="6666" SMSTYPE="SENDSMS">
    <CREATED>24.12.07 15:57:45</CREATED>
    <AUL_USERNAME>userX.Y</AUL_USERNAME>
    <AUL_CLIENT_ADR>127.0.0.1</AUL_CLIENT_ADR>
    <SMS_SENDER>SenderName</SMS_SENDER>
    <SMS_TARGET>89999991111</SMS_TARGET>
    <SMS_RES_COUNT>1</SMS_RES_COUNT>
    <SMS_TEXT>
    <![CDATA[ Привет ]]>
    </SMS_TEXT>
    <SMSSTC_CODE>wait</SMSSTC_CODE>
    <SMS_STATUS>Сообщение в процессе доставки</SMS_STATUS>
    <SMS_CLOSED>0</SMS_CLOSED>
    <SMS_SENT>0</SMS_SENT>
    </MESSAGE>
    </MESSAGES>
    </output>


    Данные по сообщению:



    Использование PHP-класса

    <?php
    // Единый запрос
    Include('QTSMS.class.php');
    $sms= new QTSMS('userX.Y','пароль','web.mirsms.ru');
    // !!! Команда на кеширование запросов
    $sms->start_multipost();
    // Отправка смс
    $sms->post_message('Привет', '+79999999991,+79999999992', 'Vasya');
    // Отправка смс
    $sms->post_message_phl('С днём рождения!', 'druzya', 'Petya', 'x425256');
    // данные о сообщении SMS_ID=6666
    $sms->status_sms_id(6666);
    // данные о сообщениях с SMS_GROUP_ID=110
    $sms->status_sms_group_id(110) ;
    // !!! отправить всё одним запросом и получить результат в XML
    $r_xml=$sms->process();
    header("Content-Type: text/xml; charset=UTF-8");
    echo $r_xml; // результат XML
    ?>


    Пример 4. Получение баланса.

    Запрос

    POST= (
    [user] => userX
    [pass] => ***
    [action] => balance
    [CLIENTADR] => 127.0.0.1
    [HTTP_ACCEPT_LANGUAGE] => ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3
    )
    Результат XML
    <output>
    <BALANCE>
    <AGT_BALANCE>1000</AGT_BALANCE> [текущее состояние счёта]
    <OVERDRAFT>100</OVERDRAFT> [максимальных уход в минус]
    </BALANCE>
    </output>

    Использование PHP-класса

    <?php
    Include('QTSMS.class.php');
    $sms= new QTSMS('XXXXX','пароль','web.mirsms.ru');
    // получение баланса
    $r_xml=$sms->get_balance();
    // результат в XML
    header("Content-Type: text/xml; charset=UTF-8");
    echo $r_xml; // результат XML
    ?>


    Пример 5. Получение входящих сообщений.

    Запрос

    POST= (
    [user] => userX
    [pass] => ***
    [action] => inbox
    [sib_num] => 123
    [date_from] => 12.01.2010 00:00:00
    [date_to] => 15.01.2010 12:00:00
    )


    Результат XML

    <output>
    <RECEIVER AGT_ID="10XXX" DATE_REPORT="08.02.2010 14:10:42"/>
    <inbox>
    <MESSAGE SMS_ID="10001234235782138" SMSTYPE="RECVSMS">
    <CREATED>13.01.2010 18:08:29</CREATED>
    <SMS_SENDER>79670413211</SMS_SENDER>
    <SMS_TARGET>79037672810</SMS_TARGET>
    <SMS_RES_COUNT>1</SMS_RES_COUNT>
    <SMS_TEXT>test 1111</SMS_TEXT>
    <SMS_STATUS>N</SMS_STATUS>
    </MESSAGE>
    <MESSAGE SMS_ID="1000123312382134" SMSTYPE="RECVSMS">
    <CREATED>14.01.2010 18:03:03</CREATED>
    <SMS_SENDER>79670413211</SMS_SENDER>
    <SMS_TARGET>79037672810</SMS_TARGET>
    <SMS_RES_COUNT>1</SMS_RES_COUNT>
    <SMS_TEXT>qwerty 22</SMS_TEXT>
    <SMS_STATUS>N</SMS_STATUS>
    </MESSAGE>
    </inbox>
    </output>


    Использование PHP-класса

    <?php
    Include('QTSMS.class.php');
    $sms= new QTSMS('XXXXX','пароль','web.mirsms.ru');
    // получение только новых входящих смс для ящика 134
    $r_xml=$sms->inbox_sms(1, 134);
    // получение только новых входящих смс
    // для ящика 134 c 10.01.2010 00:00:00 до 15.01.2010 00:00:00
    // $r_xml=$sms->inbox_sms(0,134,'10.01.2010 00:00:00','15.01.2010
    00:00:00');
    // результат в XML
    header("Content-Type: text/xml; charset=UTF-8");
    echo $r_xml; // результат XML
    ?>


    Обработка ошибок

    Коды ошибок тэга error:
  • -20117 Неправильный номер телефона.
  • -20170 Слишком большой текст сообщения. Максимальная длина не должна превышать
    160 байт.
  • -20171 Не пройдена проверка текста сообщения на наличие недопустимых слов и/или
    фраз.
  • -20158 Отправитель или получатель в черном списке.
  • -20167 Сработало ограничение по отправке одинакового текста на один и тот же номер в
    течение небольшого промежутка времени. Обратитесь в поддержку, если хотите
    отключить или уменьшить период.
  • -20144 Нет доступного тарифа для запрашиваемого направления.
  • -20147 Нет подходящего тарифа у вышестоящего контрагента.
  • -20174 Политика маршрутизации не найдена.
  • -20154 Ошибка транспорта. При возникновении этой ошибки обратитесь в службу
    поддержки.
  • -20148 Не поддерживаемое направление.
    Скачать примеры на PHP
    Для работы класса требуется PHP 5__



    Метки: http смс, http sms, протокол http отправка sms сообщений;