Протокол SOAP

Содержание

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

WSDL файл, для подключения по к web-сервисам RuFax по протоколу SOAP можно скачать по ссылке:

http://ws.rufax.ru/export/ws.rufax.ru/gws_01.wsdl.

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

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

Soap-функции могут иметь или не иметь входных параметров.

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

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

Функции делятся на два типа:

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

Все классы возвращаемых данных содержат:

result — логический тип (boolean)
description — строка (string)

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

Если операция выполнилась успешно, то result = true, и, в зависимости от функции, возвращаемый класс может содержать дополнительную информацию.
Если вызов функции завершился ошибкой, то result = false, в поле description хранится описание ошибки, и, в зависимости от функции, возвращаемый класс может содержать дополнительную информацию.

3. Функции

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

3.1.1 login()

Начало логической сессии работы с системой.

Одновременно может быть открыто несколько сессий, т.е сессии полностью независимы друг от друга и действительны до тех пор, пока не выполнена функция disconnect() или не истекло время жизни сессии (30 минут).

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

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

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

sessionId — идентификатор сессии

3.1.2 disconnect()

Вызов данной функции сообщает системе о завершении работы с данной сессией.

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

sessionId — идентификатор сессии

3.2 Отправка факсимильных сообщений

3.2.1 submitFaxList()

Отправка или сохранение в черновики одного или нескольких факсимильных сообщений. Каждое сообщение может содержать несколько факсимильных страниц(от 1 до 30) и несколько(от 1 до 20) номеров телефонов получателей.

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

messageList — список факсимильных сообщений (от 1 до 50)
sessionId — идентификатор сессии

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

submittedFaxMessageIdList — список идентификаторов(id) сообщений которые были отправлены (если одно из сообщений не было отправлено в списке будет id=0), позиция записи в списке соответствует номеру сообщения в messageList из входных параметров.

Отправляемое факсимильное сообщение (класс xFaxSubmit) содержит следующие поля:

terminalId<необязательный параметр> — идентификатор телефонного номера, который будет назначен в качестве номера-отправителя; для некоторых видов номеров звонки будут выполняться с использованием с этого номера (по умолчанию дозвон получателю факс-сообщения осуществляется с использованием общего факс-шлюза).
voiceDocumentSID<необязательный параметр> — идентификатор предварительно загруженного голосового файла (загружается с помощью функции putVoiceDocument)
recipients — список получателей факса; полное описание формата телефонных номеров.
faxCsId<необязательный параметр> — TSID для отправляемого факс сообщения
subj<необязательный параметр> — тема сообщения; нужна только для поиска сообщения через web-интерфейс, на факс не отправляется
attachments<необязательный параметр> — список вложений для отправки на факс; сразу после отправки на сервер файлы будут преобразованы в факсимильные страницы;описание разрешенных типов файлов
tags<необязательный параметр> — список меток которые нужно поставить на факс
act<необязательный параметр> — действие, которое нужно совершить над списоком факсов (send — отправить, draft — сохранить в черновиках)

3.2.2 putVoiceDocument()

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

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

sessionId — идентификатор сессии
voiceDocument — голосовой файл в формате wav или mp3; полное описание разрешенных голосовых форматов

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

voiceDocumentSID — Идентификатор (SID) голосового файла на сервере, можно использовать в функции submitFaxList, повторно один и тот же файл загружать не нужно, SID у одинаковых файлов будет одинаковый.

3.2.3 getReportSummaryList()

Получить информацию о статусе ранее отправленных факсимильных сообщений.

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

sessionId — идентификатор сессии
reportsummaryFilter — фильтр для запроса информации об отправленных факсимильных сообщениях

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

reportSummaryList — список объектов(reportSummary) содержащих информацио о статусе отправленных факсимильных сообщений

Поля объекта reportSummary:

faxRecipientId — уникальный идентификатор получателя факса(внутри разных факсимильных сообщений на один и тот же номер, этот id будет разным)
faxMessageId — идентификатор факсимильного сообщения
recipient — номер получателя факса; полное описание формата телефонных номеров.
delivered — равно 1, если сообщение было доставлено; равно 0, если не было получено уведомлений о доставке; полное описание алгоритма отправки и прихода извещений
error — равно 1, если сообщение было не доставлено; равно 0, если не было получено уведомлений о не доставке; полное описание алгоритма отправки и прихода извещений
lastarrivaltime — время последнего пришедшего извещения; (о доставке или недоставке);
ei — ID получателя внутри сообщения, если получатель один EI=1
pagesTotal — поле "всего страниц" в сообщении, после конвертации их в факс-формат
pagesSent — поле "доставлено страниц" из квитка о доставке, (могут быть доставлены не все страницы)
faxCsid — CSID факс аппарата, куда было доставлено факс сообщение
dc — код доставки; полное описание алгоритма отправки и прихода извещений
supInfo — дополнительная текстовая информация о доставке

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

4.1 Java (axis2)

1. скачать библиотеку axis2
2. запустить скрипт для генерации классов-оболочек на основе wsdl-файла:

wsdl2java -uri http://ws.rufax.ru/export/ws.rufax.ru/gws_01.wsdl --noBuildXML --noWSDL

Примечание: wsdl2java — утилита из комплекта axis2

SDL файл, для подключения по к web-сервисам RuFax по протоколу SOAP можно скачать по ссылке:

Скачайте готовый проект для IntelliJ IDEA здесь.

Проект уже включает в себя все необходимые библиотеки.

Пример 1

Аутентификация и создание сессии

Gws_01Stub.UserAuthElement userAuthElement = new Gws_01Stub.UserAuthElement(); 
userAuthElement.setLogin(login); 
userAuthElement.setPassword(pass);  

Gws_01Stub.SessionBooleanResponseElement response = serviceStub.login(userAuthElement);  

if (!response.getResult()){     
throw new Exception(response.getDescription());
}

Пример 2

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

Gws_01Stub.SubmitFaxListRequestElement request = new Gws_01Stub.SubmitFaxListRequestElement();  

Gws_01Stub.XFaxSubmitList xFaxSubmitList = new Gws_01Stub.XFaxSubmitList(); 
Gws_01Stub.XFaxSubmit[] xFaxSubmitArray = new Gws_01Stub.XFaxSubmit[1];
xFaxSubmitArray[0] = new Gws_01Stub.XFaxSubmit(); 
if (faxRecipient != null) {     
   xFaxSubmitArray[0].addRecipient(faxRecipient); 
}  

xFaxSubmitArray[0].setAct(Gws_01Stub.XFaxSubmitAction.send); 
if (voiceDocumentSID != null) {     
xFaxSubmitArray[0].setVoiceDocumentSID(voiceDocumentSID); 
} xFaxSubmitArray[0].setFaxCsId(faxCsId);  

Gws_01Stub.XBinaryAttachment binaryAttachment = new Gws_01Stub.XBinaryAttachment(); 
binaryAttachment.setBase64Binary(new DataHandler(new FileDataSource(pdfAttachment))); 
binaryAttachment.setFileName(pdfAttachment.getName()); 

xFaxSubmitArray[0].addAttachment(binaryAttachment);   

xFaxSubmitList.setMessage(xFaxSubmitArray);  
request.setMessageList(xFaxSubmitList); 
request.setSessionId(sessionId);  

Gws_01Stub.SubmitFaxListResponseElement response = serviceStub.submitFaxList(request); 
int[] submittedFaxMessageIdList = response.getSubmittedFaxMessageIdList().getVal(); 
 
if (submittedFaxMessageIdList == null || submittedFaxMessageIdList.length < 1)     
   throw new Exception(response.getDescription());  

int messageId = response.getSubmittedFaxMessageIdList().getVal()[0];  
if (messageId > 0) {     
   System.out.println("Сообщение отправлено."); 
} 
else {     
   System.out.println("Ошибка отправки сообщения, " + response.getDescription()); 
} 

userAuthElement.setLogin(login); 
userAuthElement.setPassword(pass);  

Gws_01Stub.SessionBooleanResponseElement response = serviceStub.login(userAuthElement);  

if (!response.getResult()){     
  throw new Exception(response.getDescription());
}

4.2 PHP (WSO2)

Один из предлагаемых вариантов для работы по протоколу SOAP с сервисами RuFAX в PHP это библиотека WSO2.

Примечание: наш пример тестировался на PHP версии 5.3.19 и WSO2 версии 2.1.0.

Скачать тестовое приложение для PHP и библиотеки WSO2

Для того чтобы запустить тестовое приложение выполните следующие шаги:

1. скачать и установить библиотеку "WSF for PHP" от WSO2 http://wso2.org/library/wsf/php

2. извлечь файлы примера из архива

3. в файле test.php задать правильные значения логина и пароля в секции конфигурации

//=== Задание конфигурационных параметров запуска ==========
$login = "";
$password = "";
$faxNumber = "+7(495)626-99-96";
$attachmentFileName = "test.pdf";
$wsdlPath = "http://ws.rufax.ru/export/ws.rufax.ru/gws_01.wsdl";
//=== Задание конфигурационных параметров запуска ==========

4. запустить файл test.php на выполнение

Сам пример построен на автоматически сгенеренном из WSDL коде, для того, чтобы сделать это самостоятельно:

Зайти в папку <директория установки wso2-wsf-php>/scripts и запустить команду:

php wsdl2php.php http://ws.rufax.ru/export/ws.rufax.ru/gws_01.wsdl >result.php

Пример 1

Аутентификация и создание сессии

 $wsdlPath,
    "classmap" => $class_map,
    "useMTOM" => TRUE
    ));

    // get proxy object reference form client
    $proxy = $client->getProxy();

    echo "вызываем login() ... \n";
    $input = new UserAuthElement();
    $input->login = $login;
    $input->password = $password;

    $response = $proxy->login($input);

    if (!$response->result) {
    throw new Exception($response->description);
    }

    $sessionId = $response->sessionId;
    printf("login() выполнена успешно, SessionId = '%s'\n", $sessionId);
    echo "\n";
?>

Протокол SOAP

Содержание

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

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

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

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

3. Функции

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

3.1.1 login()

3.1.2 disconnect()

3.2 Отправка факсимильных сообщений

3.2.1 submitFaxList()

3.2.2 putVoiceDocument()

3.2.3 getReportSummaryList()

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

4.1 Java (axis2)

Пример 1

Пример 2

4.2 PHP (WSO2)

Пример 1

Попробуйте сервисв действии прямо сейчас!

Дополнительные сервисы