Протокол SOAP
Содержание
1. Параметры подключения
WSDL файл, для подключения по к web-сервисам RuFax по протоколу SOAP можно скачать по ссылке:
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
Проект уже включает в себя все необходимые библиотеки.
Пример 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, SoapClient
Используется стандартное расширение SOAP для PHP, его настройка и использование описаны по приведенной ссылке.
Пример
.<?php
/*
Аутентификация
*/ $login = 'login'; // Здесь указывается логин пользователя RuFax $password = 'password'; // Здесь указывается пароль пользователя RuFax $client = new SoapClient( 'http://ws.rufax.ru/export/ws.rufax.ru/gws_01.wsdl', array( // Stuff for development. 'trace' => 1, // Нужен для работы метода __getLastResponse 'exceptions' => false, 'cache_wsdl' => WSDL_CACHE_NONE, 'features' => SOAP_SINGLE_ELEMENT_ARRAYS, ) ); $client->login(array('login' => $login, 'password' => $password)); /*
Получение идентификатора сессии
Сервер возвращает код, который SoapClient не может обработать встроенными стредствами, чтобы получить из него идентификатор сессии. Поэтому в переменную $response сохраняется ответ сервера и с помощью регулярного выражения извлекается идентификатор сессии: */ $response = $client->__getLastResponse(); if(!preg_match('/sessionId>([^<]+)</', $response, $patt)){ throw Exception('Not Found SessionId'); } $sessionId = $patt[1]; /*
Подготовка данных к отправке файла
*/ $file = 'fax.pdf'; $base64Binary = file_get_contents($file); $xBinaryAttachment = array( '_' => $base64Binary, 'md5' => md5($base64Binary), 'fileName' => $file ); $xFaxSubmit = array( 'recipient' => "+74951234567", // Номер получателя в международном формате 'attachment' => $xBinaryAttachment, 'act' => 'send' ); $xFaxSubmitList = array( 'message' => $xFaxSubmit ); $submitFaxListRequestElement = array( 'messageList' => $xFaxSubmitList, 'sessionId' => $sessionId, ); $client->submitFaxList($submitFaxListRequestElement); /* Вывод в консоль ответ сервера на метод submitFaxList Отдельно разбирается и выводится поле description, содержащее сообщение об ошибке или фразу "ok", в случае успеха. */ $response = $client->__getLastResponse(); print_r($response); preg_match('/description>([^<]+)</', $response, $patt); echo "\n\ndescription="; print_r(iconv("utf-8", 'koi8', $patt[1])); echo "\n"; ?>