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

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

• Если не указаны входные параметры, значит, метод не имеет их

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

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

• не возвращают никаких данных — данные методы используются для сигнализации
• возвращают структурированные данные

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

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

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

• Если errorCode = 0 значит операция выполнилась успешно и, в зависимости от метода, производный класс может содержать дополнительную информацию
• Если вызов метода завершился ошибкой, то errorCode отлично от 0, и в поле errorDescription хранится описание ошибки, и, в зависимости от метода, производный класс может содержать дополнительную информацию

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

• Если не указано возвращаемое значение, значит, метод возвращает базовый класс
• Сигнальные методы указываются отдельно

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

3.1.1 logon

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

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

• userName — логин пользователя
• password — пароль пользователя

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

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

3.1.3 getSessionState

Метод проверки текущего состояния сессии
Возвращаемые значения:

• boolResult — состояние сессии
• strResult — если состояние сессии активно, то возвращается имя пользователя, который начал сессию

3.2.1 addPhoneGroup

Добавление группы
Входные параметры:

• name — название группы
• code — код группы (данный код не требуется для работы по средствам SOAP протокола, но может быть использован в других протоколах, например HTTP)

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

• intResult — идентификатор группы

3.2.2 removePhoneGroup

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

• id — идентификатор группы

3.2.3 modifyPhoneGroup

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

• id — идентификатор группы
• newName — новое название группы, если параметр передан пустым, то данное поле меняться не будет
• newCode — новый код группы, если параметр передан пустым, то данное поле меняться не будет

3.2.4 clearPhoneGroup

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

• id — идентификатор группы

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

• intResult — количество удаленных контактов

3.2.5 getPhoneGroupList

Получение списка групп контрагента
Возвращаемое значение:

• listIntResult — список идентификаторов групп

3.2.6 getPhoneGroupInfo

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

• id — идентификатор группы

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

• strResult — название группы
• str2Result — код группы

3.3.1 addPhone

Добавление контакта
Входные параметры:

phone — телефон
name — название контакта для отображения
desc — описание контакта
eMail — почтовый ящик
gender — пол (возможны варианты f либо m)
fName — имя
mName — отчество
lName — фамилия
position — занимаемая должность
iCQ — номер ICQ
custom1 — произвольное текстовое поле
custom2 — произвольное текстовое поле
allowSince — время, раньше которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
allowTill — время, после которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
groupId — список идентификаторов групп, в которые добавить контакт

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

• intResult — идентификатор контакта

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

3.3.2 modifyPhone

Изменения данных контакта
Входные параметры:

• id — идентификатор телефона
• phone — новый номер телефона, если пустое, то значение поля не меняется
• name — новое название контакта для отображения, если пустое, то значение поля не меняется
• desc — новое описание контакта, если пустое, то значение поля не меняется
• eMail — новый почтовый ящик, если пустое, то значение поля не меняется
• gender — новый пол (возможны варианты f либо m), если пустое, то значение поля не меняется
• fName — новое имя, если пустое, то значение поля не меняется
• mName — новое отчество, если пустое, то значение поля не меняется
• lName — новое фамилия, если пустое, то значение поля не меняется
• position — новая занимаемая должность, если пустое, то значение поля не меняется
• iCQ — новый номер ICQ, если пустое, то значение поля не меняется
• custom1 — новое значение произвольного текстового поля, если пустое, то значение поля не меняется
• custom2 — новое значение произвольного текстового поля, если пустое, то значение поля не меняется
• allowSince — новое время, раньше которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399), если пустое, то значение поля не меняется
• allowTill — новое время, после которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399), если пустое, то значение поля не меняется

3.3.3 addPhoneToGroup

Добавление контакта в группу
Входные параметры:

• phoneId — идентификатор контакта
• groupId — идентификатор группы

3.3.4 removePhoneFromGroup

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

• <phoneId — идентификатор контакта
• <groupId — идентификатор группы

3.3.5 getPhoneListInGroup

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

• id — идентификатор группы

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

• listIntResult — список идентификаторов контактов

3.3.6 getGroupListByPhoneId

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

• id — идентификатор контакта

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

• listIntResult — список идентификаторов групп

3.3.7 searchPhone

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

• searchString — часть строки для поиска (не допускается пустое, при поиске обрезается до 32 символов)

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

• listIntResult — список идентификаторов контактов

3.3.8 getPhoneInfo

Получение информации о контакте
Входные параметры:

• id — идентификатор контакта

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

• phone — телефон
• name — название контакта для отображения
• desc — описание контакта
• eMail — почтовый ящик
• gender — пол (возможны варианты f либо m)
• fName — имя
• mName — отчество
• lName — фамилия
• position — занимаемая должность
• iCQ — номер ICQ
• custom1 — произвольное текстовое поле
• custom2 — произвольное текстовое поле
• allowSince — время раньше которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• allowTill — время после которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)

3.3.9 setBirthdayToPhone

Установка дня рождения контакта либо обновление ранее установленной даты
Входные параметры:

• id — идентификатор контакта
• specialDate — дата дня рождения

3.3.10 removeBirthdayFromPhone

Удаление дня рождения контакта
Входные параметры:

• id — идентификатор контакта

3.3.11 getPhoneBirthday

Получение дня рождения контакта
Входные параметры:

• id — идентификатор контакта

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

• dTResult — дата рождения контакта

3.4.1 getAccountList

Получение списка счетов контрагента
Возвращаемое значение:

• listIntResult — список типов счетов контрагента

3.4.2 getAccountInfo

Получение информации о счете по его типу
Входные параметры:

• id — идентификатор группы

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

• name — название
• actualBalance — фактический остаток
• overDraft — размер овердрафта
• active — признак активности
• suspended — признак заморозки счета

3.5.1 sendSimpleSms

Простая отправка SMS сообщения
Входные параметры:

• sender — имя отправителя
• phone — номер получателя
• text — текст (без возможности использовать подстановки)
• allowSince — время, раньше которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• allowTill — время, после которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• usePhoneTime — признак, указывающий, что ограничение по времени определяется по времени абонента

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

• strResult— идентификатор сообщения

3.5.2 sendSimpleFlashSms

Простая отправка flash SMS сообщения
Входные параметры:

• sender — имя отправителя
• phone — номер получателя
• text — текст (без возможности использовать подстановки)
• allowSince — время, раньше которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• allowTill — время, после которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• usePhoneTime — признак, указывающий, что ограничение по времени определяется по времени абонента

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

• strResult — идентификатор сообщения

3.5.3 sendSimpleWapPushSms

Простая отправка WAP push SMS сообщения
Входные параметры:

• sender — имя отправителя
• phone — номер получателя
• text — текст (без возможности использовать подстановки)
• uRL — url
• allowSince — время, раньше которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• allowTill — время, после которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• usePhoneTime — признак, указывающий, что ограничение по времени определяется по времени абонента
• expiredTime — время истечения действия ссылки

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

• strResult— идентификатор сообщения

3.6.1 sendSms

Отправка СМС сообщения контакту
Входные параметры:

• id — идентификатор получателя
• sender — имя отправителя
• text — текст (с возможностью использования подстановок)
• allowSince — время, раньше которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• allowTill — время, после которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• usePhoneTime — признак, указывающий, что ограничение по времени определяется по времени абонента

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

• strResult— идентификатор сообщения

3.6.2 sendFlashSms

Отправка flash СМС сообщения контакту
Входные параметры:

• id — номер получателя
• sender — имя отправителя
• text — текст (с возможностью использования подстановок)
• allowSince — время, раньше которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• allowTill — время, после которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• usePhoneTime — признак, указывающий, что ограничение по времени определяется по времени абонента

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

• strResult— идентификатор сообщения

3.6.3 sendWapPushSms

Отправка WAP push сообщения контакту
Входные параметры:

• id — номер получателя
• sender — имя отправителя
• text — текст (с возможностью использования подстановок)
• uRL — url
• allowSince — время, раньше которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• allowTill — время, после которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• usePhoneTime — признак, указывающий, что ограничение по времени определяется по времени абонента
• expiredTime — время истечения действия ссылки

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

• strResult— идентификатор сообщения

3.7.1 sendSmsToGroup

Отправка СМС сообщения группе
Входные параметры:

• id — идентификатор группы
• sender — имя отправителя
• text — текст (с возможностью использования подстановок)
• gender — пол получателя для фильтрации контактов в группе, если пол не указан, то сообщение отправляется всей группе
• allowSince — время, раньше которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• allowTill — время, после которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• usePhoneTime — признак, указывающий, что ограничение по времени определяется по времени абонента

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

• id — идентификатор группы рассылки
• sentCount — количество контактов, которым было отправлено сообщение
• notSentCount — количество контактов, которым НЕ было отправлено сообщение

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

3.7.2 sendFlashSmsToGroup

Отправка flash СМС сообщения группе
Входные параметры:

• id — идентификатор группы
• sender — имя отправителя
• text — текст (с возможностью использования подстановок)
• gender — пол получателя для фильтрации контактов в группе, если пол не указан, то сообщение отправляется всей группе
• allowSince — время, раньше которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• allowTill — время, после которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• usePhoneTime — признак, указывающий, что ограничение по времени определяется по времени абонента

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

• id — идентификатор группы рассылки
• sentCount — количество контактов, которым было отправлено сообщение
• notSentCount — количество контактов, которым НЕ было отправлено сообщение

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

3.7.3 sendWapPushSmsToGroup

Отправка WAP push сообщения группе
Входные параметры:

• id — идентификатор группы
• sender — имя отправителя
• text — текст (с возможностью использования подстановок)
• gender — пол получателя для фильтрации контактов в группе, если пол не указан, то отправляется всей группе
• uRL — url
• allowSince — время, раньше которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• allowTill — время, после которого нельзя посылать сообщения (в секундах от начала дня — значения между 0 и 86399)
• usePhoneTime — признак, указывающий, что ограничение по времени определяется по времени абонента
• expiredTime — время истечения действия ссылки

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

• id — идентификатор группы рассылки
• sentCount — количество контактов, которым было отправлено сообщение
• notSentCount — количество контактов, которым НЕ было отправлено сообщение

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

3.8.1 getSingleStatus

Запрос статуса одиночного сообщения
Входные параметры:

• id — идентификатор сообщения

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

• status — состояние сообщения
• count — количество частей сообщений для тарификации
• closeTime — время получения финального статуса (время может быть возращено в формате UTC)

Статусы могут быть следующие:
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.8.2 getGroupStatus

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

• id — идентификатор рассылки по группе (не путать с идентификатором группы)

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

• list — список статусов, который содержит следующие поля:
  • id — идентификатор сообщения
  • status — статус сообщения
  • count — количество частей в сообщение
  • closeTime — время закрытия сообщения (время может быть возращено в формате UTC)

Статусы могут быть следующие:
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.1 getInboxList

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

• listIntResult — список идентификаторов входящих ящиков

3.9.2 getInboxInfo

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

• id — идентификатор ящика

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

• number — входящий номер
• prefix — результирующий префикс
• active — состояние активности
• desc — описание
• confirmed — состояние подтверждения

3.9.3 getInSms

Получение списка входящих сообщений
Входные параметры:

• text — фильтр текста (будут выведены только сообщения, содержащие данный текст) (может быть пустым, если пусто, то сообщения не фильтруются по данному признаку)
• status — фильтр статуса (может быть пустым, если пусто, то сообщения не фильтруются по данному признаку)
• since — нижняя граница периода (может быть пустым, если пусто, то сообщения не фильтруются по данному признаку)
• till — верхняя граница периода (может быть пустым, если пусто, то сообщения не фильтруются по данному признаку)
• id — идентификатор ящика (список идентификаторов можно получить с помощью функции getInboxList)

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

• list — список входящих сообщений, которые содержат следующие поля:
  • id — идентификатор сообщения
  • status — статус
  • sender — номер отправителя
  • target — номер получателя
  • text — текст сообщения
  • created — дата поступления сообщения

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

4. Ознакомьтесь с примерами использования:
4.1 C#
4.2 PHP
4.3 Java (axis2)

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://api.sigmasms.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
Отправка простого сообщения:

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

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