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

Протокол SOAP

Содержание

1. Параметры подключения

WSDL (любой из ниже перечисленных)

2. Соглашения

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

Для межъязыковой совместимости все наборы входных параметров обернуты классами.
Далее по тексту:

2.2 Возвращаемые данные

Методы делятся на два типа :

 

Базовый класс для всех возвращаемых данных содержит:

errorCode — целое знаковое число
errorDescription — строка описания

Принято следующее соглашение, верное для всех методов:

Далее по тексту :

3. Методы

3.1 Управление сессией

3.1.1 logon

Начало логической сессии работы с системой
Если на текущий момент сессия уже была начата, то она закрывается и производится попытка начать новую сессию (которая может не увенчаться успехом)

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

3.1.2 logoff (сигнальный)

Вызов данного сигнального метода сообщает системе о прекращении работы с ней

3.1.3 getSessionState

Метод проверки текущего состояния сессии

Возвращаемые значения:

3.2 Управление настройками

3.3 Управление группами контактов Пользователю доступно управление только публичными группами контактов

3.3.1 addPhoneGroup

Добавление группы

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

Возвращаемое значение:

3.3.2 removePhoneGroup

Удаление группы по её идентификатору

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

3.3.3 modifyPhoneGroup

Изменение настроек группы

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

3.3.4 clearPhoneGroup

Удаляет всех контактов из группы. 
Не физическое удаление контактов, а удаление связи Контакт — Группа (все контакты, не входящие ни в одну группу, автоматически удаляются в течение дня)

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

  • id — идентификатор группы
  • Возвращаемое значение:

    3.3.5 getPhoneGroupList Получение списка групп контрагента

    Возвращаемое значение:

    3.3.6 getPhoneGroupInfo

    Получение информации о группе по её идентификатору

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

    Возвращаемые значения:

    3.4 Управление контактами

    3.4.1 addPhone

    Добавление контакта

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

    Возвращаемое значение:

    Если список групп пустой, то контакт будет добавлен без вхождения в группы, но будет автоматически удален системой при следующей чистке.

    3.4.2 modifyPhone

    Изменения данных контакта

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

    3.4.3 addPhoneToGroup

    Добавление контакта в группу

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

    3.4.4 removePhoneFromGroup

    Удаление контакта из группы

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

    3.4.5 getPhoneListInGroup

    Получение списка контактов в группе

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

     

    Возвращаемое значение:

    3.4.6 getGroupListByPhoneId

    Получение списка групп, в которые входит контакт

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

    Возвращаемое значение:

    3.4.7 searchPhone

    Поиск по контактам (по части вхождения в телефоне, или имени, или фамилии, или отчестве, или названии)

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

    Возвращаемое значение:

    3.4.8 getPhoneInfo

    Получение информации о контакте

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

  • id — идентификатор контакта
  • Возвращаемое значение:

    3.4.9 setBirthdayToPhone

    Установка дня рождения контакта либо обновление ранее установленной даты

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

    3.4.10 removeBirthdayFromPhone

    Удаление дня рождения контакта

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

    3.4.11 getPhoneBirthday

    Получение дня рождения контакта

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

    Возвращаемое значение:

    3.5 Информация по счетам

    3.5.1 getAccountList

    Получение списка счетов контрагента

    Возвращаемое значение:

    3.5.2 getAccountInfo 

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

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

    Возвращаемые значения:

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

    sendSimpleSms

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

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

    Возвращаемое значение:

    3.6.1 sendSimpleFlashSms

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

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

    Возвращаемое значение:

    3.6.2 sendSimpleWapPushSms

    Простая отправка WAP push SMS сообщения

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

    Возвращаемое значение:

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

    3.7.1 sendSms

    Отправка СМС сообщения контакту

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

    Возвращаемое значение:

    3.7.2 sendFlashSms

    Отправка flash СМС сообщения контакту

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

    Возвращаемое значение:

    3.7.3 sendWapPushSms

    Отправка WAP push сообщения контакту

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

    Возвращаемое значение:

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

    3.8.1 sendSmsToGroup

    Отправка СМС сообщения группе

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

    Возвращаемое значение:

    INFO Если группа содержит более 1000 контактов, вызов метода вернет ошибку, и сообщения отправлены не будут 

    3.8.2 sendFlashSmsToGroup

    Отправка flash СМС сообщения группе

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

    Возвращаемое значение:

    INFO Если группа содержит более 1000 контактов, вызов метода вернет ошибку, и сообщения отправлены не будут

    3.8.3 sendWapPushSmsToGroup

    Отправка WAP push сообщения группе

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

    Возвращаемое значение:

    INFO Если группа содержит более 1000 контактов, вызов метода вернет ошибку, и сообщения отправлены не будут

    3.9 Получение статусов отправленных сообщений 

    3.9.1 getSingleStatus

    Запрос статуса одиночного сообщения

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

    Возвращаемое значение:

    Статусы могут быть следующие:

    SMS_STATUS_SCHEDULED = 0 — сообщение в очереди отправки
    SMS_STATUS_ENROUTE = 1 — сообщение передано оператору
    SMS_STATUS_DELIVERED = 2 — сообщение доставлено абоненту (финальный статус)
    SMS_STATUS_EXPIRED = 3 — сообщение было передано оператору, но не доставлено
    абоненту в отведенный период времени (финальный статус)
    SMS_STATUS_DELETED = 4 — сообщение удалено (финальный статус)
    SMS_STATUS_UNDELIVERABLE = 5 — сообщение не доставлено (финальный статус)
    SMS_STATUS_ACCEPTED = 6 — сообщение принято
    SMS_STATUS_UNKNOWN = 7 — состояние сообщения не известно (финальный статус)
    SMS_STATUS_REJECTED = 8 — сообщение отклонено оператором (финальный статус)
    SMS_STATUS_ABORTED = 20 — сообщение отменено (финальный статус)
    SMS_STATUS_ERROR = 21 — сообщение не было отправлено из-за ошибки (финальный
    статус)
    SMS_STATUS_TIMEOUT = 22 — сообщение не было передано оператору, и истек
    период отправки данного сообщения (финальный статус)

    3.9.2 getGroupStatus

    Запрос статуса сообщений по идентификатору группы рассылки

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

    Возвращаемое значение:

    Статусы могут быть следующие:

    SMS_STATUS_SCHEDULED = 0 — сообщение в очереди отправки
    SMS_STATUS_ENROUTE = 1 — сообщение передано оператору
    SMS_STATUS_DELIVERED = 2 — сообщение доставлено абоненту (финальный статус)
    SMS_STATUS_EXPIRED = 3 — сообщение было передано оператору, но не доставлено
    абоненту в отведенный период времени (финальный статус)
    SMS_STATUS_DELETED = 4 — сообщение удалено (финальный статус)
    SMS_STATUS_UNDELIVERABLE = 5 — сообщение не доставлено (финальный статус)
    SMS_STATUS_ACCEPTED = 6 — сообщение принято
    SMS_STATUS_UNKNOWN = 7 — состояние сообщения не известно (финальный статус)
    SMS_STATUS_REJECTED = 8 — сообщение отклонено оператором (финальный статус)
    SMS_STATUS_ABORTED = 20 — сообщение отменено (финальный статус)
    SMS_STATUS_ERROR = 21 — сообщение не было отправлено из-за ошибки (финальный
    статус)
    SMS_STATUS_TIMEOUT = 22 — сообщение не было передано оператору, и истек
    период отправки данного сообщения (финальный статус)

    3.10 Входящие сообщения

    3.10.1 getInboxList

    Получение списка идентификаторов входящих ящиков

    Возвращаемое значение:

    3.10.2 getInboxInfo

    Получение информации по входящему ящику

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

    Возвращаемое значение:

    3.10.3 getInSms

    Получение списка входящих сообщений

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

    Возвращаемое значение:

    Статусы сообщений:

    N — New — новый, автоматически после получения помечается на R
    R — Read — прочитанный
    A — Reply — на это сообщение ответили через WEB интерфейс
    F — Forward — данное сообщение было переправлено по протоколу пользователю
    M — Forward and Reply — на данное сообщение ответили WEB интерфейс, и также
    оно было переправлено по протоколу пользователю

    4. Пример использования 

    4.1 C#

    Для начала необходимо из WSDL, расположенном на сервере, получить все классы для работы, для этого необходимо воспользоватся утилитойwsdl, входящей в состав Microsoft SDKs:

    "C:\Program Files\Microsoft SDKs\Windows\v7.0\Bin\wsdl" /l:cs /protocol:SOAP
    /out:"C:\SOAPTelAccess.cs" http://web.mirsms.ru/public/soap/index.php?wsdl

    — создается файл, который содержит основной класс TelAccess,предоставляющий все выше
    описанные методы, и дополнительные вспомогательные классы, необходимые для работы.
    Работа по данному протоколу разделена на два уровня — физическая и логическая
    сессия,обеспечением физической сессии занимаются системные компоненты. Для поддержания
    единой физической сессии первым делом необходимо созданиеcookie:

    CookieContainer cookie = new CookieContainer();

    — данный cookie неообходимо будет указывать для всех объектов класс TelAccess

    TelAccess soapclient = new TelAccess(); soapclient.CookieContainer = cookie;

    — если не использовать cookie, сервер будет считать для разных объектов класса TelAccess
    различные физической сессии
    Начало логической сессии происходит по средствам авторизация методом logon:

    InputLogon Param = new InputLogon(); Param.userName = "10234.3";
    Param.password = "123"; ReturnValueBase rv = soapclient.logon(Param);

    — если авторизация прошла успешно, то в rv.errorCode возвращается 0, в противном случае код ошибки, а в rv.errorDescription текстовое описание ошибки.
    Если в течение 1 минуты не было вызвано ни одного метода, логическая сессия будет закрыта автоматически. Также, логическую сессию можно закрыть сигнальным методом logoff.
    Узнать состояние логической сессии можно, вызвав метод getSessionState

    ReturnValueBooleanString rv = TA.getSessionState().@return;

    — если метод выполнился успешно, то логическая переменная rv.boolResult говорит о том, активна ли сейчас логическая сессия, а rv.strResult о том, какой пользователь инициировал данную логическую сессию.

    INFO При первом вызове любого метода происходит инициализация всех необходимых объектов
    и компонентов в C#, это может занять до 10-15 секунд, дальнейшие вызовы методов происходят
    без задержек. 

    Пример 1

    Отправка простого сообщения:

    CookieContainer cookie = new CookieContainer();
    TelAccess soapclient = new TelAccess();
    soapclient.CookieContainer = cookie;
    // Init session
    InputLogon Param1 = new InputLogon();
    Param1.userName = "11234.5";
    Param1.password = "123";
    ReturnValueBase rv1 = soapclient.logon(Param1);
    if (rv1.errorCode != 0)
    throw new Exception(rv1.errorDescription);
    // Send simple sms
    InputSendSimpleSms Param2 = new InputSendSimpleSms();
    Param2.sender = "test-sms";
    Param2.phone = "79876543210";
    Param2.text = "Тестовое сообщение";             Param2.allowSince = 3600;
    Param2.allowSinceSpecified = true;
    Param2.allowTill = 72000;
    Param2.allowTillSpecified = true;
    Param2.usePhoneTime = checkBoxUsePhoneTime.Checked;
    Param2.usePhoneTimeSpecified = true;
    ReturnValueString rv2 = soapclient.sendSimpleSms(Param2);
    if (rv2.errorCode != 0)
    throw new Exception(rv2.errorDescription);
    else
    MessageBox.Show("Message id: " + rv2.strResult);
    // Close session
    soapclient.logoff();

    Пример 2

    Добавление группы

    CookieContainer cookie = new CookieContainer();
    TelAccess soapclient = new TelAccess();
    soapclient.CookieContainer = cookie;
    // Logon
    InputLogon Param1 = new InputLogon();
    PParam1.userName = "11234.5";
    Param1.password = "123";
    ReturnValueBase rv1 = soapclient.logon(Param1);
    if (rv1.errorCode != 0)
    throw new Exception(rv1.errorDescription);             // Add phone group
    InputAddPhoneGroup Param2 = new InputAddPhoneGroup();
    Param2.name = "Test group";
    ReturnValueInt rv2 = soapclient.addPhoneGroup(Param2);
    if (rv2.errorCode != 0)
    throw new Exception(rv2.errorDescription);
    else
    MessageBox.Show("Group id: " + rv2.intResult);

    Пример 3

    Добавление контакта (опционально помещение данного контакта в 4 некоторые группы контактов)

    CookieContainer cookie = new CookieContainer();
    TelAccess soapclient = new TelAccess();
    soapclient.CookieContainer = cookie;
    // Logon
    InputLogon Param1 = new InputLogon();
    PParam1.userName = "11234.5";
    Param1.password = "123";
    ReturnValueBase rv1 = soapclient.logon(Param1);
    if (rv1.errorCode != 0)
    throw new Exception(rv1.errorDescription);
    // Add phone group
    InputAddPhoneGroup Param2 = new InputAddPhoneGroup();
    Param2.name = "Test group";             ReturnValueInt rv2 = soapclient.addPhoneGroup(Param2);
    if (rv2.errorCode != 0)
    throw new Exception(rv2.errorDescription);
    else
    MessageBox.Show("Group id: " + rv2.intResult);

    4.2 PHP

    Для работы по протоколу SOAP в PHP необходимо подключить модульphp_soap в php.ini
    Для Windows надо добавить следующие строчки в php.ini

    [PHP_SOAP] extension=php_soap.dll

    Для Linux надо добавить следующие строчки в php.ini

    [PHP_SOAP] extension=soap.so

    Пример 1

    Отправка простого сообщения:

    <?php
    $objClient = new SoapClient("http://web.mirsms.ru/public/soap/",
    array('trace' => true)); 
    $params = array('param' => array('userName' => "XXXXX.X", 'password' =>
    "your_password"));
    $objData =  $objClient->logon($params);
    if ($objData->return->errorCode == 0)
    {
    $params = array('param' => array('sender' => "test-sms", 'phone' =>
    "79991234567", 'text' => "SOAP test"));
    $objData =  $objClient->sendSimpleSms($params);
    print "Message send. ID ".$objData->return->strResult;
    $objClient->logoff();
    }
    else
    {
    echo "Error: ".$objData->return->errorDescription;}
    ?>

    4.3 Java (axis2)

    Для создания всех необходимых классов можно воспользоваться утилитой, входящей в состав axis2 

    wsdl2java -uri http://web.mirsms.ru/public/soap/index.php

    Пример 1

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

    package SoapClient;
    import java.rmi.RemoteException;
    import org.apache.axis2.AxisFault;
    import org.apache.axis2.client.Options;
    import telecom.srv.sms.*;
    import telecom.srv.sms.TelAccessStub.*;
    public class Test
    {
    public static void main(String args[])  
    {
    try 
    {
    TelAccessStub soalclient = new TelAccessStub();

    Options options =
    soalclient._getServiceClient().getOptions();
    options.setManageSession(true);
    soalclient._getServiceClient().setOptions(options);

    InputLogon inparam1 = new InputLogon();
    inparam1.setUserName("11234.5");
    inparam1.setPassword("123");    Logon param1 = new Logon();
    param1.setParam(inparam1);

    ReturnValueBase rv1 =
    soalclient.logon(param1).get_return();
    if (rv1.getErrorCode() != 0)
    throw new Exception(rv1.getErrorDescription());

    InputSendSimpleSms inparam2 = new InputSendSimpleSms();
    inparam2.setSender("Test");
    inparam2.setPhone("79876543210");
    inparam2.setText("Java test message");

    SendSimpleSms param2 = new SendSimpleSms();
    param2.setParam(inparam2);
    ReturnValueString rv2 =
    soalclient.sendSimpleSms(param2).get_return();
    if (rv2.getErrorCode() != 0)
    throw new Exception(rv2.getErrorDescription());

    System.out.println("Message id:" + rv2.getStrResult());
    soalclient.logoff();

    catch (AxisFault e) 
    {
    e.printStackTrace();

    catch (RemoteException e) 
    {
    e.printStackTrace();   } 
    catch (Exception e) 
    {
    e.printStackTrace();
    }
    }
    }

    Пример 2 

    Добавление группы

    package SoapClient;
    import java.rmi.RemoteException;
    import org.apache.axis2.AxisFault;
    import org.apache.axis2.client.Options;
    import telecom.srv.sms.*;
    import telecom.srv.sms.TelAccessStub.*;
    public class Test
    {
    public static void main(String args[])  
    {
    try 
    {
    TelAccessStub soalclient = new TelAccessStub();

    Options options =
    soalclient._getServiceClient().getOptions();
    options.setManageSession(true);
    soalclient._getServiceClient().setOptions(options);

    InputLogon inparam1 = new InputLogon();    inparam1.setUserName("11234.5");
    inparam1.setPassword("123");
    Logon param1 = new Logon();
    param1.setParam(inparam1);

    ReturnValueBase rv1 =
    soalclient.logon(param1).get_return();
    if (rv1.getErrorCode() != 0)
    throw new Exception(rv1.getErrorDescription());

    InputAddPhoneGroup inparam2 = new InputAddPhoneGroup();
    inparam2.setName("Java test group");
    AddPhoneGroup param2 = new AddPhoneGroup();
    param2.setParam(inparam2);

    ReturnValueInt rv2 =
    soalclient.addPhoneGroup(param2).get_return();
    if (rv2.getErrorCode() != 0)
    throw new Exception(rv2.getErrorDescription());

    System.out.println("Group id:" + rv2.getIntResult());

    soalclient.logoff();

    catch (AxisFault e) 
    {
    e.printStackTrace();

    catch (RemoteException e) 
    {
    e.printStackTrace();   } 
    catch (Exception e) 
    {
    e.printStackTrace();
    }
    }
    }

    Пример 3

    Добавление контакта (опционально помещение данного контакта в 4 некоторые группы контактов) 

    package SoapClient;
    import java.rmi.RemoteException;
    import org.apache.axis2.AxisFault;
    import org.apache.axis2.client.Options;
    import telecom.srv.sms.*;
    import telecom.srv.sms.TelAccessStub.*;
    public class Test
    {
    public static void main(String args[])  
    {
    try 
    {
    TelAccessStub soalclient = new TelAccessStub();

    Options options =
    soalclient._getServiceClient().getOptions();
    options.setManageSession(true);
    soalclient._getServiceClient().setOptions(options);
    InputLogon inparam1 = new InputLogon();
    inparam1.setUserName("11234.5");
    inparam1.setPassword("123");
    Logon param1 = new Logon();
    param1.setParam(inparam1);

    ReturnValueBase rv1 =
    soalclient.logon(param1).get_return();
    if (rv1.getErrorCode() != 0)
    throw new Exception(rv1.getErrorDescription());

    InputAddPhone inparam2 = new InputAddPhone();
    inparam2.setPhone("79876543210");
    inparam2.setFname("Test");
    inparam2.setLname("Testov");
    inparam2.setCustom1("Очень тестовый клиент");
    inparam2.setIcq("111222333");
    int [] groupid = new int[2];
    groupid[0] = 2770;
    groupid[1] = 2771;
    inparam2.setGroupId(groupid);

    AddPhone param2 = new AddPhone();
    param2.setParam(inparam2);
    ReturnValueInt rv2 =
    soalclient.addPhone(param2).get_return();
    if (rv2.getErrorCode() != 0)
    throw new Exception(rv2.getErrorDescription());

    System.out.println("Phone id:" + rv2.getIntResult());    
    soalclient.logoff();

    catch (AxisFault e) 
    {
    e.printStackTrace();

    catch (RemoteException e) 
    {
    e.printStackTrace();

    catch (Exception e) 
    {
    e.printStackTrace();
    }
    }
    }