Спецификация форматов и порядок обмена данными в канале «Сбербанк Интеграция» (API). Версия 33.000

Содержание

Введение

1.1

Назначение документа

1.2

Термины и сокращения

1.3

Ссылки на документы

Интеграция УС с каналом УПШ

2.1.

Особенности реализации

2.2.

Сжатие HTTP-трафика

2.3.

Общая характеристика процессов взаимодействия

2.4.

Общая схема работы с веб-сервисом

2.5.

Тикеты и квитанции

2.6.

Общее описание методов WSDL веб-сервиса канала УПШ

2.6.1.

Версионность запросов

2.6.2.

Передача документов в Банк

2.6.2.1.

Отправка клиентских документов в Банк

2.6.2.2.

Получение идентификатора документа в АС СББОЛ

2.6.2.3.

Запрос состояния клиентских документов

2.6.2.4.

Отправка запроса состояний документов по полученным из СББОЛ идентификаторам 35

2.6.2.5.

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

2.6.2.6.

Взаимодействие при изменении финальных статусов

2.6.2.7.

Получение документов из Банка (получение выписок по счетам)

2.6.2.8.

Отправка запроса на получение документов из Банка

2.6.2.9.

Получение результатов обработки по отправленному запросу

2.6.2.10. Получение результатов обработки по отправленному запросу

2.6.2.11. Пакетная отправка документов

2.6.2.12. Типы связанных документов

2.6.2.13. Режимы работы канала УПШ

2.7.

Особенности взаимодействия УС холдинга с УПШ

2.7.1.

Получение персональных данных организации (обязательно к реализации на стороне

клиента) 57

2.7.2.

Запрос справочников

2.7.3.

Запрос на выпуск сертификата для пользователя Дочерней компании

2.7.4.

Запрос на формирование выписки по счету Дочерней компании

2.7.5.

Запрос выписок и других документов для Дочерней компании

2.8.

Безопасность

2.8.1.

Аутентификация и авторизация

2.8.1.1.

Общие сведения

2.8.1.2.

Формат взаимодействия

2.8.1.3.

Аутентификация по паре логин-пароль

2.8.1.4.

Аутентификация с использованием сертификата ЭП

2.8.1.5.

Правила формирования значения параметра DevicePrint

2.8.1.6.

Расчет свертки пароля

2.8.1.7.

Расчет свертки нового пароля при смене пароля

2.8.2.

Работа с электронной подписью

102

2.8.3.

Общие правила формирования дайджестов и сообщений

104

2.8.3.1.

Дайджест

104

2.8.3.2.

Формат сообщений

105

2.8.4.

Обмен криптографическими документами

106

2.8.4.1.

Запрос на выпуск нового сертификата

106

2.8.4.1.1. Дайджест

106

2.8.4.1.2. Формат взаимодействия

106

2.8.4.1.2.1.

Формат отправки документов в СББОЛ

107

2.8.4.1.3. Особенности получения статусов об обработке из СББОЛ

115

2.8.4.1.3.1.

Проверка ФИО в запросе сертификата

117

2.8.4.1.4. Поля запроса на новый сертификат

118

2.8.4.1.5. Печатная форма сертификата

131

2.8.5.

Подтверждение операций УПШ кодом СМС

134

2.8.5.1.

Основные сведения

134

2.8.5.2.

Запрос на генерацию кода СМС и подтверждение кодом СМС

135

2.8.5.2.1. Дайджест

135

2.8.5.2.2. Формат взаимодействия

135

2.8.5.2.2.1.

Формат передачи запроса СМС

135

2.8.5.2.2.2.

Формат передачи SMS-кода для подписи

137

2.8.5.3. Запрос таймаута действия кода СМС

141

2.8.5.3.1. Дайджест

141

2.8.5.3.2. Формат запроса таймаута действия смс-пароля

143

2.8.5.3.3. Формат получения ответа с таймаутом действия смс-пароля

144

2.8.6.

Контроль используемой архитектуры

145

2.8.7.

Передача параметров ФРОД-мониторинга

145

2.8.7.1.

Общие сведения

145

2.8.7.2.

Формат элемента Request/Sign

146

2.8.7.3.

Формат элемента Request/Fraud

150

История изменений

155

Введение

Данная документация состоит из двух разделов.

В первом можно ознакомиться с назначением документа, пояснениями терминов и сокращений, а

также посмотреть ссылки на остальные части документации.

Второй раздел посвящен общим сведениям интеграции учетных систем клиентов Банка с каналом

универсального платежного шлюза. к АС Сбербанк Бизнес ОнЛ@йн

1.1 Назначение документа

Настоящий документ содержит описание API взаимодействия внешней Учетной системы клиента с

каналом предоставления ДБО «Унифицированный Платежный Шлюз» (УПШ) к АС Сбербанк

Бизнес ОнЛ@йн.

Документ содержит описание особенностей интеграции учетной системы клиента и УПШ,

форматов передаваемых сообщений и особенностей работы.

1.2 Термины и сокращения

Таблица - Глоссарий

№

Термин/Сокращение

Определение

п/п

АБС

Автоматизированная банковская система

АРМ

Автоматизированное рабочее место

Банк

ПАО «Сбербанк»

Головная компания/распорядитель по счетам других

ГК

компаний

Удостоверяющий Центр

- функциональное объединение

сотрудников ПАО Сбербанк и комплекса технических

УЦ

средств, предназначенного для регистрации информации о

субъектах и выданых им сертификатах, а также для издания

и отзыва сертификатов.

ДБО

Дистанционное банковское обслуживание

ДЗО

Дочернее зависимое общество, дочерняя компания

Юридическое лицо/индивидуальный предприниматель,

являющиеся резидентами, имеющие в Банке банковский(-

Клиент

ие) счет

(-а) в валюте Российской Федерации и/или

иностранных валютах и заключившие с Банком Договор

банковского счета

ПАК

Программно-аппаратный комплекс

10.

СББОЛ

АС Сбербанк Бизнес ОнЛ@йн

Сервер учетной системы клиента. Компьютер или группа

11.

Сервер УС

компьютеров, на которых функционирует ПО, интегрируемое

с УПШ.

12.

СКП

Сертификат ключа проверки (ЭП)

Пользователь, использующий для подтверждения операций

код СМС

(у пользователя должен быть только

13.

СМС-клиент

криптопрофиль OneTimePassword и не должно быть

криптопрофиля «Инфокрипт»)

В криптографии соль (модификатор)

— это строка

случайных данных, которая подается на вход хеш-

функции вместе с исходными данными. Используется для

удлинения

строки

пароля,

что

осложняет

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

паролей за один

проход полного перебора или с помощью предварительно

14.

Соль

построенных радужных таблиц. При этом соль не защищает

от полного перебора каждого пароля в отдельности. Исходя

из назначения, соль должна быть уникальной для каждого

пароля из хранимого набора хешей и не является

секретной, т.е. хранится рядом с хешом пароля в открытом

виде.

Канал предоставления услуг дистанционного банковского

15.

УПШ

обслуживания «Сбербанк-интеграция» СББОЛ.

Учетные системы клиентов Банка, доработанные для

16.

УС

взаимодействия с каналом УПШ.

17.

ЭД

Электронный документ

Электронная подпись - информация в электронной форме,

которая присоединена к другой информации в электронной

форме (подписываемой информации) или иным образом

18.

ЭП

связана с такой информацией и которая используется для

определения лица, подписывающего информацию (в ред.

закона от 06.04.2011 № 63-ФЗ).

Язык описания веб-сервисов и доступа к ним, основанный

19.

WSDL

на языке XML

request.xsd,

XSD схемы описывающие форматы данных обмена

20.

response.xsd,

информацией с сервисом УПШ

upg-replication.xml

Защищенный ФПСУ-IP сегмент DMZ (демилитаризованной

21.

Зона TAU

зоны) Банка

1.3

Ссылки на документы

Таблица - Документы

№

Наименование

Назначение

Местонахождение

п/п

документа

Описание

форматов

взаимодействия с СББОЛ:

 Первичная

инициализация Клиента

Документация по

 Репликация

API

УПШ

справочников на сторону

часть.docx

Клиента

 Получение извещения о

результатах обработки

клиентских документов

2.2. Сжатие HTTP-трафика

При передаче xml-сообщения могут быть сжаты средствами протокола HTTP

1.X с

использованием алгоритма gzip.

Признаком того что HTTP-запрос/ответ содержит сжатые данные, служит заголовок протокола

HTTP: Content-Encoding: gzip

Пример заголовка HTTP-запроса содержащего сжатые данные:

HTTP/1.x 200 OK

Content-Encoding: gzip

Content-Type: text/xml; charset=utf-8

[сжатые данные,request/response]

Основываясь на заголовке HTTP, полученные данные должны быть восстановлены

(декомпрессированы) на стороне УС с использованием алгоритма GZip.

В свою очередь передаваемые данные, также должны быть сжаты УС-клиента, и в HTTP-запрос

должен быть добавлен заголовок: Content-Encoding: gzip.

2.3. Общая характеристика процессов взаимодействия

Унифицированный платежный шлюз представляет собой приложение, развернутое в

зоне TAU и предоставляющее Web-сервис, содержащий методы, позволяющие:

 Выполнять первичную инициализацию Клиента:

¾ Передача клиенту сертификата технологической подписи СББОЛ

¾ Передача клиенту личных клиентских сертификатов

¾ Передача клиенту персональных данных организации

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

 Выполнять репликацию справочников на сторону клиента

 Выполнять отправку клиентских криптографических документов из УС в Банк:

¾ Запрос на новый сертификат

¾ Запрос на отзыв сертификата

 Выполнять отправку клиентских документов из УС в Банк:

¾ Рублёвое платежное поручение

¾ Запрос рублевой и валютной выписки

¾ Запрос входящих

¾ Платежное поручение в иностранной валюте

Поручение на продажу валюты

Поручение на покупку валюты

Распоряжение на осуществление обязательной продажи

Справка о валютных операциях

Справка о подтверждающих документах

Закрытие паспорта сделки

Переоформление паспорта сделки

Паспорт сделки (форма 1: по контрактам)

Паспорт сделки (форма 2: по кредитным договорам)

Электронный реестр (Зарплатная ведомость)

Заявление на заключение зарплатного договора

Заявление на открытие счетов и выпуск карт

Электронный реестр по уволившимся сотрудникам

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

Платёжное требование

Инкассовое поручение

Письмо в Банк

Рублевые получатели

Запрос информации об овердрафте

Распоряжение о переводе кредитных средств

Информация об акцепте/отказе от акцепта

Запрос на удаление контрагента

Запрос на изменение признака проверки контрагентов

Запрос на генерацию SMS пароля

Запрос на обновление прошивки токена

Запрос сведений о бенефициаре

Запрос информации валютного контроля

Письмо для целей ВК (в банк)

Паспорта сделок из других банков

Клиентам Банка получать результаты обработки документов, соответствующих их

жизненному циклу;

Клиентам Банка получать:

¾ Информацию о движении денежных средств по рублевому счету

(рублевая выписка);

¾ Информацию о движении денежных средств по валютному счету

(валютная выписка);

¾ Письма из Банка;

¾ Выполнять подтверждение операций УПШ кодом СМС.

Клиентам Банка получать Банковскую информацию по безопасности:

¾ Передача клиенту списка отозванных сертификатов (CRL);

¾ Передача клиенту сертификатов ЭП/шифрования.

Основной задачей канала УПШ является передача в АС СББОЛ электронных

документов (ЭД), формируемых на стороне клиента. АС СББОЛ полученные ЭД

использует для передачи их далее в АБС Банка, где производится их обработка. АБС

Банка затем отправляет результаты обработки документов назад в АС СББОЛ, откуда

по каналу УПШ их может получить УС клиентов.

АС СББОЛ сведения обо всех ЭД (в том числе, полученных по каналу УПШ) хранит в

виде записей в базах данных. Информация об этапах обработки документов в АБС

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

жизненного цикла документов.

Статусы делятся на две пересекающиеся группы: внутрибанковские и статусы для

уведомления.

Процесс формирования, подписания

(ЭП), передачи, проверки, получения и

исполнения Сторонами ЭД в Системе ДБО должно сопровождаться изменением

статуса ЭД.

При получении ЭД из канала УПШ АС СББОЛ заносит его информацию в базу

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

жизненному циклу обычного документа, созданного в клиентском интерфейсе АС

СББОЛ. ПО канала УПШ может запрашивать текущий статус документов в базах АС

СББОЛ и передавать эти сведения в УС клиентов.

Взаимодействие УС клиентов с каналом УПШ можно охарактеризовать следующим

образом:

 Асинхронное взаимодействие

 Инициатором может выступать только УС клиента

При взаимодействии УС клиента направляет запрос (или передает информацию) веб-

сервису УПШ. В ответ сервис возвращает идентификатор запроса. Отправив позднее

запрос с этим идентификатором, учетная система клиента в ответ получает результат

обработки исходного запроса (если он уже был обработан). Таким образом, любое

взаимодействие происходит в два этапа:



Отправка запроса

o Отправка запроса происходит при вызове метода sendRequestsSRP и

передаче сообщения в формате, описанном в request.xsd. При отправке

запроса система сразу возвращает тикет (32-символьный

идентификационный код полученного сообщения).

o Если при вызове WEB-сервиса «sendRequestsSRP» в ответ тикет не

вернулся, можно отправить документ еще раз с тем же самым RequestID

запроса, и в том случае, если в ответ вернется REQUESTID_DUBLIC, то

попробовать получить квитанцию на документ и DocId путем отправки

вместо тикета значения RequestID в WEB-сервис

«getRequestStatusSRP», так как они совпадают с тикетом. Далее следует

стандартный алгоритм обмена сообщениями.

o Если по каким-то причинам СББОЛ не может сформировать тикет, он

вернет ошибку (код и причину)



Получение результатов (через некоторое время)

o Для получения результатов обработки исходного сообщения

необходимо, при вызове метода getRequestStatusSRP передать

полученный ранее тикет. В ответ система сразу вернет сообщение в

формате, описанном в response.xsd, содержащее результат обработки

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

o Если исходный запрос не был обработан, то при попытке получить

результат будет возвращено сообщение, что обработка еще не

состоялась. В этом случае необходимо попытаться получить результат

чуть позже.

Основными процессами взаимодействия УС и СББОЛ являются:

 Передача документов в Банк

 Запрос состояния клиентских документов

 Получение документов из Банка

ВАЖНО:

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

информационных полей запросов к сереверу УПШ может быть

регламентоирвано договором на подключение к УПШ.

2.4. Общая схема работы с веб-сервисом

Общая схема работы с каналом УПШ предполагает двухэтапное взаимодействие: на первом этапе

сообщение передается в Банк, на втором этапе из Банка возвращается ответ

- результат

обработки исходного сообщения.

Описание этапа 1

Сообщения предаются веб-сервису в метод sendRequestsSRP в элементе Request. Xml-

сообщение может представлять собой только один элемент Request, структура которого должна

соответствовать схеме request.xsd.

При этом в xml-сообщении служебные символы должны быть заменены на коды:

Служебный символ

Код служебного символа

“

‘

Символ перевода строки

Символ возврата каретки

В ответ на полученные данные возвращается тикет (сихронно и в порядке следования запросов),

равный значению, указанному в запросе Клиента в поле requestId.

Описание этапа 2

После получения тикетов на стороне Клиента через некоторое время, достаточное для обработки

сообщения (рекомендуемое время задержки - 3 сек) эти тикеты могут быть отправлены в метод

getRequestStatusSRP. В ответ веб-сервис УПШ синхронно отправит результат обработки

исходного сообщения (квитанцию о статусе электронного документа или сообщения с ЭД из Банка

в пакете). Все ответы на запрос методу getRequestStatusSRP передаются в элементе Response,

формат которого описан в response.xsd

Если исходное сообщение еще не обработано, веб-сервис вернет синхронно одно из специальных

сообщений (описаны ниже). Если произошли какие-либо ошибки, веб-сервис вернет синхронно

специальный тикет или квитанцию об ошибке (см. описание ниже).

Подробно каждое взаимодействия рассмотрено в соответствующем разделе.

В таблице ниже приведены форматы вызовов в соответствии с WSDL веб-сервиса

УПШ.

№

Описание

Сообщение

Ответ

п/

soapenv:Envelope

<soap:Envelope

Вызов метода

xmlns:soapenv="http://schemas.xmlso

xmlns:soap="http://schemas.xmlsoap

sendRequestsSR

ap.org/soap/envelope/"

.org/soap/envelope/">

xmlns:upg="http://upg.sbns.bssys.com/

<soap:Body>

<sendRequestsSRPResponse

<soapenv:Header/>

xmlns="http://upg.sbns.bssys.com/">

<soapenv:Body>

<return>f6a466de-1e31-4ca6-a450-

<upg:sendRequestsSRP>

344e70375d7d</return>

</sendRequestsSRPResponse>

<upg:requests>

</soap:Body>

XML-сообщение в соответствии с

</soap:Envelope>

форматом request.xsd

</upg:requests>

Примечание:

</upg:sendRequestsSRP>

В элементе <return> система

</soapenv:Body>

возвращает тикет (32-символьный

</soapenv:Envelope>

идентификатор с разделителями).

Тикет возвращается без обертки в

структуру <![CDATA[]]>

<soapenv:Envelope

<soap:Envelope

Вызов метода

xmlns:soapenv="http://schemas.xmlso

xmlns:soap="http://schemas.xmlsoap

getRequestStatus

ap.org/soap/envelope/"

.org/soap/envelope/">

SRP

xmlns:upg="http://upg.sbns.bssys.com/

<soap:Body>

<getRequestStatusSRPResponse

<soapenv:Header/>

xmlns="http://upg.sbns.bssys.com/">

<soapenv:Body>

<return><![CDATA[

<upg:getRequestStatusSRP>

XML-сообщение в соответствии с

форматом response.xsd

<upg:requests>6dcdaebb-caa8-4227-

]]></return>

b965-4f84100cc065</upg:requests>

</getRequestStatusSRPResponse>

</upg:getRequestStatusSRP>

</soap:Body>

</soapenv:Body>

</soap:Envelope>

</soapenv:Envelope>

Примечание:

В элементе <requests> передается

тикет исходного запроса

Примеры взаимодействия с каналом УПШ с помощью программы soapUI при отправке запроса

текущих статусов в АС СББОЛ двух переданных ранее документов (передаются идентификаторы

двух документов, затем запрашивается результат обработки сообщения - статусы документов в

АС СББОЛ).

<soapenv:Envelope

Вызов

метода

<soap:Envelope

xmlns:soapenv="http://schemas.xm

sendRequestsSRP

xmlns:soap="http://schemas.xmlsoap

lsoap.org/soap/envelope/"

.org/soap/envelope/">

Отправка запроса

xmlns:upg="http://upg.sbns.bssys.c

(передаются

om/">

<soap:Body>

идентификаторы

<soapenv:Header/>

<sendRequestsSRPResponse

двух

ранее

<soapenv:Body>

xmlns="http://upg.sbns.bssys.com/">

переданных

<upg:sendRequestsSRP>

банк документов)

<return>c9c0efae-f567-4532-b458-

<upg:requests>

6f07784a1ebf</return>

<![CDATA[<Request

xmlns="http://bssys.com/upg/reque

</sendRequestsSRPResponse>

st"

</soap:Body>

xmlns:xs="http://www.w3.org/2001/

XMLSchema"

</soap:Envelope>

xmlns:xsi="http://www.w3.org/2001/

XMLSchema-instance"

xsi:type="Request"

requestId="256529fe-bbb6-4e20-

9bf5-b950196821d1"

orgId="dba24080-ac26-4ec2-9351-

1bd8987febc4" version="1.0"

sender="Ромашка"

receiver="SBBOL_DBO">

<DocId docId="1c915d54-4015-

49d7-8eb0-ac4b07acd6d8"/>

<DocId docId="3b97db30-897a-

4dae-a4a9-99b128b48192"/>

</DocIds>

</Request>]]>

</upg:requests>

</upg:sendRequestsSRP>

</soapenv:Body>

</soapenv:Envelope>

Вызов метода

<soapenv:Envelope

<soap:Envelope

getRequestStatusS

xmlns:soapenv="http://schemas.xm

xmlns:soap="http://schemas.xmlsoap

lsoap.org/soap/envelope/"

.org/soap/envelope/">

Получение

xmlns:upg="http://upg.sbns.bssys.c

результатов

om/">

<soap:Body>

(через некоторое

<soapenv:Header/>

<getRequestStatusSRPRespo

время передается

<soapenv:Body>

nse

тикет исходного

<upg:getRequestStatusSRP>

xmlns="http://upg.sbns.bssys.com/">

сообщения)

<upg:requests>c9c0efae-f567-

<return><![CDATA[<Response

createTime="2013-08-22T13:52:10"

4532-b458-

receiver="Ромашка"

6f07784a1ebf</upg:requests>

</upg:getRequestStatusSRP>

requestId="256529fe-bbb6-4e20-

</soapenv:Body>

9bf5-b950196821d1"

</soapenv:Envelope>

responseId="c9c0efae-f567-4532-

b458-6f07784a1ebf" sender="DBO"

version="1.1"

xmlns="http://bssys.com/upg/respons

e">

<Ticket createTime="2013-08-

22T13:52:12" docId="1c915d54-

4015-49d7-8eb0-ac4b07acd6d8">

<Info docExtId="db8f1f62-

f41a-4b4b-a70e-f7025c0d831e"

statusStateCode="INVALIDEDS">

</Info>

<Sign>

<ISSUER>CN = УЦЦАСБРФ

(ТЕСТ)

O = ЦАСБРФ

C = RU</ISSUER>

<SN>3030434130303936</SN

<Value>HBFKhHO7zPY34YU

sZjqsm9L+vV1f5Lef8AAGYB8wWHJ

e0fXE/y5p5lPnJbvfX9I3Rd7fyBarJHD

POOfWxcZuug==</Value>

</Sign>

</Ticket>

<Ticket createTime="2013-08-

22T13:52:12" docId="3b97db30-

897a-4dae-a4a9-99b128b48192">

<Info docExtId="db8f1f62-

f41a-4b4b-a70e-f7025c0d831e"

statusStateCode="DELIVERED">

</Info>

<Sign>

<ISSUER>CN =

УЦЦАСБРФ(ТЕСТ)

O = ЦАСБРФ

C = RU</ISSUER>

<SN>3030434130303936</SN

<Value>EB0UAilMO5iIN4wVL

7vZaCDEWG+t77SPoY6w/nqB6YgK

TpOcZzXIlugTIqEs6i9SP8qE4euljv83

ipx75v4U7Q==</Value>

</Sign>

</Ticket>

</Tickets>

</Response>]]></return>

</getRequestStatusSRPRespo

nse>

</soap:Body>

</soap:Envelope>

При установлении соединения с веб-сервисом открывается сессия. Время жизни

сессии настраивается на сервере УПШ заданием параметров

# таймаут пользовательской сессии в минутах

usersession.timeout=10

usersession.lifetime=10

Параметр usersession.timeout определяет время жизни сессии при отсутствии

активности по данной сессии, а параметр usersession.lifetime определяет время жизни

сессии при наличии активности по данной сессии, то есть, например, если

установлены значения параметров

usersession.timeout=15

usersession.lifetime=30

и УС Клиента получила sessionId, то при полном отсутствии активности по

полученному sessionId срок действия данного sessionId истечет через 15 мин, а при

наличии активности по полученному sessionId срок действия данного sessionId

истечет после момента последней активности +15 минут, но не позднее, чем через 30

минут после получения sessionId

На данный момент в промышленной среде заданы следующие значения:

usersession.timeout=15

usersession.lifetime=15

На тестовом стенде:

usersession.timeout=10

usersession.lifetime=10

2.5. Тикеты и квитанции

Квитанции передаются по запросу со стороны клиента и содержат коды состояний

обработки документов

(коды статусов). Эти сведения передаются в составном

элементе Response/Tickets/Ticket.

Пример квитанции:

<soap:Envelopexmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<return><![CDATA[<Response

createTime="2013-08-22T13:52:10"

receiver="Ромашка"

requestId="256529fe-bbb6-4e20-9bf5-b950196821d1"

responseId="c9c0efae-f567-4532-b458-

6f07784a1ebf" sender="DBO" version="1.1" xmlns="http://bssys.com/upg/response">

</Info>

<Sign>

<ISSUER>CN = УЦ ЦА РК РФ (ТЕСТ)

O = ЦА ДА РФ

C = RU</ISSUER>

<Value>HBFKhHO7zPY34YUsZjqsm9L+vV1f5Lef8AAGYB8wWHJe0fXE/y5p5lPnJbvfX9I3Rd7fyBarJHD

POOfWxcZuug==</Value>

</Sign>

</Tickets>

</Response>]]></return>

</getRequestStatusSRPResponse>

</soap:Body>

</soap:Envelope>

Тикет в УПШ - уникальный идентификатор принятого сообщения, который синхронно

возвращается веб-сервисом в ответ отправившей стороне. Тикет представляет собой

32-символьный идентификатор, разделенный четырьмя дефисами, возвращается в

элементе <return> (см. пример).

Пример тикета - ответа веб-сервиса на метод sendRequestsSRP:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

</sendRequestsSRPResponse>

</soap:Body>

</soap:Envelope>

Если по запросу со стороны УС Клиента не был получен тот или иной ответ в течение

длительного времени, то это означает, что в очереди обрабатывается большое

количество сообщений или возникла ошибка обработки на стороне Банка.

В промышленной среде каждая проблема отдельно должна решаться через службу

поддержки.

2.6. Общее описание методов WSDL веб-сервиса канала УПШ

В WSDL указаны следующие методы:



sendRequestsSRP. Служит для передачи запросов из Учетной системы клиента

в СББОЛ. В ответ на вызов метод sendRequestsSRP должен возвращаться

ответ от веб-сервиса УПШ в УС клиента. В метод можно передавать xml-

сообщения в соответствии со схемой request.xsd. В метод за один раз может

быть отправлено любое количество xml-сообщений. Ответ веб-сервиса

представляет собой набор тикетов (уникальных идентификаторов принятых

сообщений), по одному на каждое сообщение, переданное в метод. Тикеты

следуют в порядке обработки последовательно поступивших в сервис УПШ

сообщений. Каждому принятому веб-сервисом xml-сообщению соответствует

свой тикет.

Прежде чем использовать метод sendRequestsSRP, sessionId должен быть

обязательно подтвержден, для чего при аутентификации

(методы login,

loginSign) нужно получить успешный код возврата. Обязательным условием

использования метода является наличие действующего sessionId. В ответе

для УС будет передан код возврата.

Если исходное сообщение, тикет которого был передан методу, не

обработано, то сообщение будет содержать информацию, что исходное

сообщение (которому соответствует тикет) не обработано.

Сообщения, которые могут быть переданы в ответ при вызове метода

sendRequestSRP, если исходное сообщение не было обработано системой,

представлены ниже в таблице.

Таблица - Значения, которые могут быть переданы, если запрос не был обработан (передаются в

ответ на метод sendRequestSRP)

№

Версионно

Код состояния запроса

Назначение кода состояния

п/п

сть

Запрос с таким идентификатором уже был

ранее получен и сохранен в БД СББОЛ,

Актуально с

повторное сохранение в БД СББОЛ

версии 27

записи с повторяющимся

идентификатором недопустимо

При невозможности отправить тикет в ответ на вызов метода sendRequestsSRP веб-сервис

вернет XML-сообщение с кодом и описанием ошибки.

Пример ответа с кодом и описанием ошибки

<?xml

version="1.0"

encoding="UTF-8"?><Response

xmlns='http://bssys.com/upg/response'><Errors><Error><Code>103</Code><Type>Error</Type><Desc

>Неверные параметры авторизации</Desc></Error></Errors></Response>

В элементе Code могут быть переданы следующие коды ошибок:

Таблица - Перечень ошибок, которые

возвращает УПШ в ответ на вызов метода sendRequestSRP и

getRequestStatusSRP

Код ошибки

Код состояния

документа/запроса

Описание

(Response/

Метод

Версионность

Errors/Error/

(Response/Errors/Error/T

(Response/Errors/Error/Desc)

Code)

ype)

Не специфицированная ошибка

sendRequest

SRP,

Изменено в

999

Error

getRequestS

версии 29

tatusSRP

Ошибка валидации xml по xsd

Ошибка выдается, если входящая

xml не прошла валидацию по xsd -

sendRequest

следовательно, при получении

SRP,

Изменено в

101

данного кода повторять

getRequestS

версии 29

Error

аналогичного формата запрос до

tatusSRP

исправления xml на стороне УС

или xsd на стороне СББОЛ не

имеет смысла

Ошибка проверки подписи

getRequestS

Изменено в

102

Error

tatusSRP

версии 29

Неверные параметры авторизации

sendRequest

Изменено в

103

Error

SRP

версии 29

Операция не доступна для сессии:

sendRequest

Изменено в

104

Error

“sessionId”

SRP

версии 29

sendRequest

Принятие документов данным

способом недоступно для

SRP,

Изменено в

105

Error

getRequestS

версии 29

организации

tatusSRP

Изменено в

106

Неверно указан пароль

Error

версии 28

Архив пуст или параметр orgId не

Изменено в

107

Error

совпадает с содержимым

версии 28

запакованного запроса

Таблица - Перечень специальных тикетов, которые может вернуть УПШ в случае ошибок, а также ответов

метода getRequestStatusSRP на эти тикеты

Код ошибки,

передаваемый

Назначение кода

Контекст ответа метода getRequestStatusSRP на

Версионн

в тикете

состояния

данный тикет

ость

<soap:Envelope

xmlns:soap="http://schemas.xmlsoap.org/soap/envelope

/">

<soap:Body>

<getRequestStatusSRPResponse

xmlns="http://upg.sbns.bssys.com/">

<return><![CDATA[<Response

xmlns="http://bssys.com/upg/response"

Сервис временно

createTime="2013-11-21T17:17:40"

недоступен

requestId="00000000-0000-0000-0000-000000000000"

UNKNOWN_ORG

responseId="00000000-0000-0000-0000-

00000000-0000-

UNKNOWN_RESPONS

000000000000" sender="UPG Service" version="1.0">

Актуально

0000-0000-

E_ID

с версии

UNKNOWN_EXCEPTIO

<Error>

000000000000

<Code>00000000-0000-

0000-0000-000000000000</Code>

<Type>Error</Type>

<Desc>Service is

temporary unavailable</Desc>

</Error>

</Errors>

</Response>]]></return>

</getRequestStatusSRPResponse>

</soap:Body>

</soap:Envelope>

<Error>

Неверный формат

<Code>00000000-0000-

00000000-0000-

идентификатора

0000-0000-000000000001</Code>

Актуально

сессии (не GUID)

<Type>Error</Type>

0000-0000-

с версии

(SRP)

<Desc>Invalid session id

000000000001

INVALID_SESSION_ID

format</Desc>

_FORMAT

</Error>

</Errors>

<Error>

<Code>00000000-0000-

00000000-0000-

Неверный

0000-0000-000000000002</Code>

Актуально

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

<Type>Error</Type>

0000-0000-

с версии

(SRP)

<Desc>Invalid session

000000000002

INVALID_SESSION_ID

id</Desc>

</Error>

</Errors>

<Error>

<Code>00000000-0000-

При вызове метода

00000000-0000-

0000-0000-000000000003</Code>

SendRequestSRP

Актуально

<Type>Error</Type>

0000-0000-

отправлен пустой

с версии

<Desc>Request is

request

000000000003

empty</Desc>

EMPTY_REQUEST

</Error>

</Errors>

<Error>

Среди параметров

<Code>00000000-0000-

00000000-0000-

метода

0000-0000-000000000004</Code>

Актуально

SendRequestSRP нет

<Type>Error</Type>

0000-0000-

с версии

request-ов

<Desc>List of requests is

000000000004

EMPTY_REQUEST_LIS

empty</Desc>

</Error>

</Errors>

<Error>

<Code>00000000-0000-

00000000-0000-

Неверный логин

0000-0000-000000000005</Code>

Актуально

пользователя

<Type>Error</Type>

0000-0000-

с версии

INVALID_USER_LOGI

<Desc>Invalid user

000000000005

</Error>

</Errors>

В сообщении не

<Error>

найден orgId либо

<Code>00000000-0000-

00000000-0000-

значение не

0000-0000-000000000006</Code>

Актуально

соответствует

<Type>Error</Type>

0000-0000-

с версии

формату

<Desc>OrgId not found

000000000006

ORGID_NOT_FOUND_I

in message</Desc>

N_MESSAGE

</Error>

</Errors>

<Error>

000000000-

<Code>00000000-0000-0000-

0000-0000-

orgID отсутствует в бд

Актуально

0000-000000000007</Code>

роутера СББОЛ

с версии

0000-

<Type>Error</Type>

ORG_NOT_FOUND

<Desc>Org not found</Desc>

000000000007

</Error>

</Errors>

<Error>

Не найден

<Code>00000000-0000-0000-

00000000-0000-

ContractAccessCode в

0000-000000000008</Code>

Актуально

0000-0000-

<Type>Error</Type>

с версии

БД роутера

<Desc>ContractAccessCode

000000000008

CONTRACT_ACCESS_

CODE_NOT_FOUND

not found</Desc>

</Error>

</Errors>

<Error>

<Code>00000000-0000-0000-

00000000-0000-

Только для SRP. Не

0000-000000000009</Code>

Актуально

верный формат org id

0000-0000-

<Type>Error</Type>

с версии

INVALID_ORG_ID_FO

<Desc>Invalid org id

000000000009

RMAT

format</Desc>

</Error>

</Errors>

<Error>

<Code>00000000-0000-0000-

00000000-0000-

0000-000000000010</Code>

Актуально

Не найден сертификат

0000-0000-

<Type>Error</Type>

с версии

CERT_NOT_FOUND

<Desc>Certificate not

000000000010

found</Desc>

</Error>

</Errors>

<Error>

Размер пакета

<Code>00000000-0000-0000-

00000000-0000-

превысил

0000-000000000011</Code>

Актуально

максимально

0000-0000-

<Type>Error</Type>

с версии

допустимый

<Desc>Size of request list

000000000011

REQUEST_LIST_SIZE_

exceed max size</Desc>

EXCEED_MAX

</Error>

</Errors>

<Error>

<Code>00000000-0000-0000-

00000000-0000-

Ошибка доступа к

0000-000000000012</Code>

Актуально

серверу

0000-0000-

<Type>Error</Type>

с версии

SERVER_ACCESS_ER

<Desc>Ошибка доступа к

000000000012

ROR

серверу</Desc>

</Error>

</Errors>

00000000-0000-

Актуально

WRONG_PART_PARA

0000-0000-

с версии

METER

000000000013

00000000-0000-

Актуально

INCORRECT_CUSTOM

0000-0000-

с версии

S_PARAMS

000000000014

00000000-0000-

Актуально

INCORRECT_ACCESS

0000-0000-

с версии

_TOKEN

000000000015

<Error>

<Code>00000000-0000-0000-0000-

00000000-0000-

000000000012</Code>

Актуально

0000-0000-

INCORRECT_SID2

<Type>Error</Type>

с версии

<Desc> Неверный формат SID2

000000000016

</Desc>

</Error>

</Errors>



getRequestStatusSRP. Служит для запроса результатов обработки ранее

отправленных запросов. В метод передается идентификатор из тикета. В ответ

приходит xml-сообщение в соответствии со схемой Response.xsd.

Обязательным условием использования метода является наличие

действующего sessionId. В ответе в УС Клиента будет передан код возврата.

Пример запроса метод getRequestStatusSRP:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"

<SOAP-ENV:Body><getRequestStatusSRP xmlns="http://upg.sbns.bssys.com/">

</getRequestStatusSRP>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

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

Параметр

Название

requests

Идентификатор запроса, полученный в тикете

sessionId

ID сессии

orgld

Идентификатор организации

Перечень кодов возвратов в методе getRequestStatusSRP

Код возврата

Описание

Версионность

Не специфицированная ошибка

Актуально с версии 27

Операция выполнена успешно

Актуально с версии 27

Время жизни идентификатора сессии истекло

Актуально с версии 27

Если исходное сообщение, тикет которого был передан методу, не обработано, то сообщение

будет содержать информацию, что исходное сообщение (которому соответствует тикет) не

обработано.

Сообщения, которые могут быть переданы в ответ при вызове метода getRequestStatusSRP,

если исходное сообщение не было обработано системой, представлены ниже в таблице.

Таблица - Значения, которые могут быть переданы, если запрос не был обработан (передаются в ответ на

метод getRequestStatusSRP)

№

Назначение кода

Версионно

Код состояния запроса

Пример в логах

п/п

состояния

сть

2012-05-02

13:38:37.850,com.bssys.sbns.upg.Uni

versalPaymentGateTest,3b8f3db2-

<!--NOT PROCESSED YET--

Запрос еще не

Актуально с

8862-4933-b8f8-db10d0a92608,[pool-

был обработан

версии 27

1-thread-1],ERROR -

getRequestStatusSRP response:

[]

2012-05-02

13:38:37.850,com.bssys.sbns.upg.Uni

Запрос

versalPaymentGateTest,3b8f3db2-

<!--REQUEST NOT FOUND-

указанным

Актуально с

8862-4933-b8f8-db10d0a92608,[pool-

идентификатором

версии 27

1-thread-1],ERROR

не найден в БД

getRequestStatusSRP response:

[]

Возвращается в

ответ на запрос,

<getRequestStatusSRPResponse

если

sessionId

xmlns="http://upg.sbns.bssys.com/"><r

был получен под

Актуально с

eturn><!--USER_IP_CHANGED--

одним ip-адресом,

версии 27

></return></getRequestStatusSRP

запрос

Response>

отправлен

другого ip-адреса

Если тикет соответствовал ранее переданному сообщению с ЭД, то после обработки по

методу getRequestStatusSRP будет возвращена квитанция

(Response/Tickets/Ticket) с

уникальным идентификатором записи в БД АС СББОЛ и другой информацией.

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

(Request/DocIds), то будут возвращены квитанции (Response/Tickets) с кодами состояний

документов, по которым был исходный запрос.

Значения, которые могут быть переданы в квитанции при запросе состояний документов,

представлены в таблице ниже.

Таблица - Значения, которые могут быть переданы в квитанции¹

Код состояния

Наименов

№

документа/запроса

Версионно

ание

Назначение кода состояния

Тип статуса

п/п

(Response/Tickets/Ticket/I

сть

статуса

nfo@statusStateCode)

Запрос не соответствует

Окончательный

Актуально с

FORMAT_ERROR

формату

/Прекратить опрос/

версии 27

Дублирующий RqUID

Окончательный

Запрос

таким

/Прекратить опрос/

Актуально с

RQUID_DUPLIC

идентификатором уже был

версии 27

получен и обработан

Клиент не обслуживаются по

Окончательный

Актуально с

ORG_NOT_FOUND

ДБО или неверный ORGID

/Прекратить опрос/

версии 27

Доставлен

Промежуточный

Запрос доставлен в ДБО и

Актуально с

DELIVERED

/Продолжать

взят в обработку.

версии 27

опрашивать/

Поиск

сертификата

для

Окончательный

проверки ЭП под ЭД на

/Прекратить опрос/

стороне

банка

дала

Актуально с

SERT_NOT_FOUND

отрицательный результат. Нет

версии 27

соответствия

статусу

документа в ДБО.

ЭП

не

Окончательный

Проверка ЭП под ЭД на

верна

/Прекратить опрос/

Актуально с

INVALIDEDS

стороне

Банка

дала

версии 27

отрицательный результат

Ошибка

Электронный документ не

Окончательный

реквизитов

прошел логические контроли

/Прекратить опрос/

Актуально с

REQUISITE_ERROR

Системы ДБО при приеме на

версии 27

стороне Банка или Запрос на

выписку превышает 15 дней

Окончательный

DOCUMENT_NOT_FO

Электронный документ с

/Прекратить опрос/

Актуально с

указанным идентификатором

UND

версии 27

не найден в БД

Принят

Промежуточный

Электронный документ принят

Актуально с

ACCEPTED

/Продолжать

на стороне Банка

версии 27

опрашивать/

¹В следующих частях документа для каждого документа описан определенный перечень статусов

Выгружен

Промежуточный

10.

Электронный

документ

Актуально с

EXPORTED

/Продолжать

выгружен Банком в АБС

версии 27

опрашивать/

Принят

Электронный документ был

Промежуточный

Актуально с

11.

ACCEPTED_BY_ABS

АБС

принят к обработке в АБС

/Продолжать

версии 27

Банка

опрашивать/

Картотека

Электронный

документ

Окончательный

передан в картотеку в

/Прекратить опрос/

Актуально с

12.

CARD2

ожидание средств на счету

версии 27

клиента

Отказан

Электронный

документ

Окончательный

Актуально с

13.

DECLINED_BY_ABS

АБС

отказан АБС Банка

/Прекратить опрос/

версии 27

Приостано

Обработка

электронного

Промежуточный

14.

Актуально с

DELAYED

влен

документа

была

/Продолжать

версии 27

приостановлена

опрашивать/

Отозван

Электронный документ был

Окончательный

Актуально с

15.

RECALL

отозван Клиентом по запросу

/Прекратить опрос/

версии 27

Исполнен

Электронный

документ

Окончательный

Актуально с

16.

IMPLEMENTED

исполнен Банком

/Прекратить опрос/

версии 27

Ошибка

Промежуточный

17.

Электронный документ не

Актуально с

EXPORT_ERROR

экспорта

/Продолжать

выгрузился в АБС Банка

версии 27

опрашивать/

Принят ВК

Документ принят валютным

Промежуточный/Пр

контролем

екратить

18.

Актуально с

ACCEPTED_BY_CFE

опрос/Выполнять

версии 27

опрос

по

отдельному запросу

Отказан

Промежуточный/Пр

ВК

екратить

19.

Документ не принят валютным

Актуально с

DECLINED_BY_CFE

опрос/Выполнять

контролем

версии 27

опрос

по

отдельному запросу

Отвергнут

Электронный

документ

Окончательный

20.

Актуально с

REFUSEDBYBANK

Банком

отвергнут в СББОЛ Банка

/Прекратить опрос/

версии 27

вручную.

Частично

Промежуточный

PARTIMPLEMENTED

Исполнен

/Продолжать

Актуально с

21.

Документ исполнен частично

опрашивать/

версии 27

Нет соответствия статусу

Окончательный

документа. Документы в таком

/Прекратить опрос/

статусе не попадают в

СББОЛ.

Невалидный

документ,

документе

22.

содержится

критическая

Актуально с

FAIL

ошибка. В этом случае от

версии 27

сервиса УПШ отправляется

ответ с

разъяснениями

ошибки, ответ записывается в

таблицу

SBNS_UPG_INBOUND

Ошибка

случае

Промежуточный

недоступности БД, отсутствие

/Продолжать

23.

Актуально с

SOFT_FAIL

необходимых

настроек

опрашивать/

версии 27

клиентаю Документ может

быть обработан позднее

На

Со стороны ФРОД-анализа

Промежуточный

24.

проверке у

получен статус документа «На

/Продолжать

Актуально с

FRAUDREVIEW

специалис

проверке

специалиста

опрашивать/

версии 27

та Банка

Банка»

Требуется

Со стороны ФРОД-анализа

Промежуточный

25.

подтвержд

получен статус документа

/Продолжать

Актуально с

FRAUDSMS

ение sms-

«Требуется подтверждение

опрашивать/

версии 27

паролем

sms-паролем»

Отправлен

Документ

отправлен

Окончательный

26.

Актуально с

SENDED_TO_PAYER

плательщи

плательщику

/Прекратить опрос/

версии 27

ку

Обработан

Документ обработан

Окончательный

Актуально с

27.

PROCESSED

/Прекратить опрос/

версии 27

На акцепт

Входящее

платежное

Промежуточный

28.

Актуально с

ONACCEPTANCE

поручение получено из АБС

/Продолжать

версии 27

опрашивать/

Истек срок

Срок акцепта истек

Окончательный

Актуально с

29.

ACCEPTEXPIRE

акцепта

/Прекратить опрос/

версии 27

В АБС поступило «Заявление

Промежуточный

30.

Акцептова

Актуально с

ACCEPTANCE

на акцепт»

/Продолжать

версии 27

опрашивать/

Отказ от

В АБС поступило

Окончательный

NONEACCEPTANCE

акцепта

«Заявление об отказе от

/Прекратить опрос/

31.

Актуально с

акцепта»

версии 27

2. В АБС поступил отзыв ПТ

получателем

В АБС поступило «Заявление

Промежуточный

PARTACCEPT

Частично

о частичном акцепте»

/Продолжать

Актуально с

32.

акцептова

опрашивать/

версии 27

Оплачено

Выполнено

списание

Окончательный

Актуально с

33.

PAID

соответствии с заявлением

/Прекратить опрос/

версии 27

Клиент

сформировал

Промежуточный

34.

«Заявление

об

/Продолжать

Актуально с

PROCESSING

обработке

акцепте/частичном

опрашивать/

версии 27

акцепте/отказе от акцепта»

Окончательный

Актуально с

35.

APPROVE

Одобрен

Документ одобрен

/Прекратить опрос/

версии 27

Промежуточный

36.

Требует

Актуально с

MODIFYREQUIRED

Документ требует доработки

/Продолжать

доработки

версии 27

опрашивать/

Окончательный

Актуально с

37.

PROCESSERROR

Отказан

Документ отказан

/Прекратить опрос/

версии 27

Промежуточный

Актуально

Документ

38.

SIGNED

Документ подписан

/Продолжать

с версии

подписан

опрашивать/

ЭД был подписан

Промежуточный

Актуально

Частично

39.

PARTLY_SIGNED

неполным набором

/Продолжать

с версии

подписан

подписей

опрашивать/

Окончательный

Актуально с

40.

CLOSED

Закрыт

Документ закрыт

/Прекратить опрос/

версии 27

Промежуточный

41.

Представл

Электронный документ принят

Актуально с

SUBMITTED

/Продолжать

ен

ВК

версии 27

опрашивать/

Промежуточный

Проверяет

Документ принят в работу

Актуально с

42.

TRIED_BY_CFE

/Продолжать

ся ВК

сотрудником ВК в МВК ЕКС

версии 27

опрашивать/

PARTIALLY_ACCEPTED

Электронный

документ

43.

Частично

Актуально с

частично принят Валютным

_BY_CFE

принят ВК

версии 27

контролем

Статус

уведомляет

Окончательный

44.

Актуально с

RESPONSE_DIVISION

разбиении большого ответа на

/Прекратить опрос/

версии 27

пакеты

Документ записан в БД

Промежуточный

45.

Актуально с

CREATED

Создан

СББОЛ,

проверки

не

/Продолжать

версии 27

выполнялись

опрашивать/

Приведенный выше список кодов статусов является исчерпывающим. При получении в

квитанции любого кода состояния, отличающегося от перечисленных выше, он должен

интерпретироваться как код статуса

«FAIL»

(Нет соответствия статусу документа,

неопределенная ошибка).

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

документов из Банка (запрос Request/Incoming), то в ответ придет сообщение с выписками

клиента и другими документами, подготовленными на стороне Банка для данной организации.

Существует механизм оптимизации, который позволяет убирать повторяющиеся выписки за

одну и ту же дату по одному и тому же счету, отправляя клиенту последнюю актуальную

выписку, при этом выписка клиенту на запрос Request/Incoming может быть отправлена

однократно, т.е., например, поступление двух запросов Request/Incoming подряд не повлечет

двукратной отправки клиенту одной и той же информации. Если выписка клиентов будет

потеряна, то потребуется сначала отправить в банк запрос на выписку, а после его обработки

снова отправить запрос Request/Incoming. Если ночная выписка за дату была передана в УС

Клиента, то повторная ее отправка не предусмотрена.

 getResponsePartSRP. Служит для запроса заархивированных частей

документа, т.н. пакетов, которые были сформированы на стороне АС СББОЛ в

результате разбиения большого ответа в элементе Response. В метод

передается ID исходного запроса, номер пакета, sessionId и orgId. В ответ

приходит xml-сообщение в соответствии со схемой Response.xsd.

Обязательным условием использования метода является наличие

действующего sessionId

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

Параметр

Название

Идентификатор запроса, полученный в тикете

requests

Номер пакета

part

ID сессии

sessionId

Идентификатор организации

orgld

2.6.1.Версионность запросов

В запросах есть возможность использования версионности.

Поле protocolVersion используется для направления в обработчик соответствующей

версии. В случае не указания версии, обработка будет производиться по самой

старой из доступных версий. В случае поступления новых требований регулятора

старые версии не дорабатываются, а направленные документы по старым форматам

будут отказаны т.к. не удовлетворяют требованиям регулятора.

Поле protocolVersion заполняется цифрами, например, 27.

2.6.2.Передача документов в Банк

Передачу документов в Банк можно разделить на два процесса:

 Процесс отправки клиентских документов

 Процесс получения идентификатора документа в СББОЛ

Общая схема взаимодействия приведена на Рисунке 1.

Рисунок 1. Схемы взаимодействия систем при обработке документа

2.6.2.1. Отправка клиентских документов в Банк

Для отправки клиентских документов должна выполняться следующая

последовательность шагов:

ШАГ 1:

 На стороне клиента формируется список документов для отправки.

 Для каждого документа из данного списка, формируются (либо уже были

сформированы) необходимое количество электронных подписей.

 Электронные подписи формируются в соответствии с ГОСТ, по утвержденной

Банком технологии и с использованием определенных Банком форматов.

 Каждый документ и соответствующие(ая) ему ЭП помещаются в специальный

XML-контейнер, в соответствии с форматом request.xsd (формируется строка,

содержащая xml-сообщение).

 Все сформированные таким образом xml-сообщения (строки) передаются в

запросе веб-сервису УПШ при вызове метода sendRequestsSRP.

Примечание.

Требуется учесть ограничения на количество документов в одном сообщении. Так при

отправке клиентского документа в одном xml-сообщении может быть передан только

один документ, согласно ограничениям, указанным в схеме request.xsd.

Однако при вызове метода sendRequestsSRP может быть в одном вызове requests

последовательно передано произвольное количество отдельных xml-сообщений,

содержащих по одному документу. Необходимо ограничивать количество

сообщений (не более 100) за один вызов метода, поскольку обработка сообщений

начинается только после полного получения всех данных, переданных с помощью

вызова метода. Текущее ограничение размера сообщения составляет 2 МБ.

Для передачи пакета документов, следует использовать метод sendRequestPackage.

Пример ШАГа

1: Вызов метода sendRequestsSRP, на примере отправки

документа «Платежное поручениеª

Важно: Параметр sender является константой для всех xml-сообщений

направляемых УС Клиента в СББОЛ. Значение данного параметра устанавливается в

настройках организации в СББОЛ на основании указанного Клиентом (головной

компании холдинга) значения в договорах с Банком при подключении и не подлежит

изменению. Головной компании холдинга и ВСЕМ его дочерним зависимым

подразделениям (ДЗО) холдинга устанавливается единое значение параметра в

СББОЛ. Установленное значение контролируется на стороне Банка. При поступлении

на обработку хml-сообщения со значением отличным от согласованного сервис

вернет ошибку.

Данную информацию необходимо учитывать при разработке интеграционного

решения в УС Клиента и в документах, заключаемых с Банком.

Рекомендация к константному значению параметра sender=:

Желательно указывать латинцей, слитно и кратко (либо сокращенно). Например:

Объединенная космическая компания Москва-Кассиопея

- вполне приемлемый

вариант, с большой долей вероятности исключающий пересечения с другими УС

Клиента, - OKKMOS-KAS

<?xmlversion="1.0" encoding="UTF-8"?>

<Request xmlns="http://bssys.com/upg/request" requestId="8f108043-ebfd-4844-9e3f-1aac71ac0812"

version="0.1" orgId="24b70f22-703f-bf04-db60-bd110572f40d"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://bssys.com/upg/request request.xsd" sender="Ромашка"

receiver="SBBOL_DBO">

<AccDoc purpose="ВтомчислеНДС 18 % - 188.31" accDocNo="123" docDate="2012-

05-02" docSum="1234.5" transKind="01" paytKind="электронно" priority="1"/>

<Payer inn="201234567890" kpp="201234567"

personalAcc="40000000000000000000">

<Name>ОАО "СБЕРБАНК"</Name>

<BankCity>Москва</BankCity>

</Bank>

</Payer>

<Name>Получатель</Name>

<Name> ФИЛИАЛ ОАО "БЕЛЫЙ ПЛЕН"</Name>

<BankCity>Москва</BankCity>

</Bank>

</Payee>

</PayDocRu>

<Sign>

<Issuer>CN=ЛавринСВ-Тестовая печать-УЦ-9</Issuer>

<Value>dnenujcvma20d0W4S98ucGOcXAmFUYeevq2SVUapKbY6JdjrsGE4gvN5u6myqSBiAXj

dSD3xK3ZDoF7ixWIRmg==</Value>

<PcPropHash>ECCB0C2EA8F72D3961A9BADFC5BF67A4C1E3154A59F2CC39A62F9EA6976

426481DE75A977F79BD00CDE82E059126EBAA2B496D2F5C4182EF91EB9798EF62B32E</PcPropH

ash>

<Fraud>

<Login>Тестовый Пользователь</Login>

<TokenInfo> BCRYPT;;;;; </TokenInfo>

<PcProp>8FBE0BC4-5F7C-11E1-AEBF-

DF3EA9FF2800;BFEBFBFF000206A7;PBAF441;

Z2AMA1FK</PcProp>

<DevicePrint>version%3D3.4.1.0_1%26pm_fpua%3DWin64%7C0%7Cx64%7Cru%7C01.005.00

%26pm_fpsc%3D32%7C1600%7C900%7C1600%26pm_fpsw%3Dabk%3D6%2C1%2C7601%2C17514

%7Cwnt%3D6%2C1%2C7601%2C18952%7Cdht%3D11%2C0%2C9600%2C18376%7Cie5%3D%7Cibe

%3D11%2C0%2C9600%2C18376%7Cieh%3D11%2C0%2C9600%2C18376%7Ciee%3D6%2C3%2C96

00%2C18376%7Cwmp%3D12%2C0%2C7601%2C19148%7Cobp%3D11%2C0%2C9600%2C18376%7

Coex%3D6%2C1%2C7601%2C17514%7Cvbs%3D5%2C6%2C0%2C8833%26pm_fptz%3D3%26pm_fpl

n%3Dlang%3Dru%7Csyslang%3Dru%7Cuserlang%3Dru%26pm_fpjv%3D0%26pm_fpco%3D0%26pm_f

pasw%3D%26pm_fpan%3DSBB%26pm_fpacn%3DSBB%26pm_fpol%3Dfalse%26pm_fposp%3D%26p

m_fpup%3D%26pm_fpsaw%3D1600%26pm_fpspd%3D32%26pm_fpsbd%3D%26pm_fpsdx%3D96%26

pm_fpsdy%3D96%26pm_fpslx%3D96%26pm_fpsly%3D96%26pm_fpsfse%3Dfalse%26pm_fpsui%3D%2

6pm_os%3DWindows%26pm_brmjv%3D01.005.00%26pm_br%3DSBB%26pm_inpt%3D%26pm_expt%

3D</DevicePrint>

</Fraud>

</Sign>

<Fraud>

<Login>Тестовый Пользователь</Login>

<TokenInfo> BCRYPT;;;;; </TokenInfo>

<PcProp>8FBE0BC4-5F7C-11E1-AEBF-

DF3EA9FF2800;BFEBFBFF000206A7;PBAF441;

Z2AMA1FK</PcProp>

</Fraud>

</Request>

ШАГ 2:

В ответ веб-сервис УПШ синхронно возвращает служебное сообщение (тикет), в

котором указывается присвоенный каждому принятому xml-сообщению уникальный

идентификатор (значение тикета равно значению requestId xml-сообщения). Дубли

значений requestId контролируются в разрезе orgId xml-сообщения, При поступлении

дубля возвращается соответствующий код возврата REQUESTID_DUBLIC вместо

уникального идентификатора

(см. Таблица

«Значения, которые могут быть

переданы, если запрос не был обработан (передаются в ответ на метод

sendRequestSRP)ª).

 Идентификатор сообщения позволяет в дальнейшем получить результат его

обработки в системе.

 Тикет возвращается после успешной валидации запроса по схеме request.xsd

и до начала обработки документа в СББОЛ.

 Такое сообщение не подписывается технологической подписью АС СББОЛ, так

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

ошибкам, связанным с превышением таймаута.

Результатом обработки сообщений-запросов на передачу документов в Банк

является создание в АС СББОЛ записей, соответствующих переданным документам.

 Идентификаторы этих записей в АС СББОЛ могут быть затем переданы в УС

клиента.

 С помощью идентификаторов записей впоследствии учетная система клиента

сможет запросить текущий статус документов.

 Статус отражает текущий этап обработки документа на стороне Банка и может

быть промежуточным либо окончательным. (Окончательные статусы

документов в особых случаях могут быть изменены на стороне банка позднее.

В таком случае информация об этих документах включается в составе ответов

на запрос incoming(подробнее см.Документация по API УПШ 2 часть, п.п.

Получение изменений документа на конечных статусах).

Пример ШАГа 2: Получение ответа системы (тикет)

9478aa08-6079-4cec-81a4-04d362edc52f

2.6.2.2. Получение идентификатора документа в АС СББОЛ

Для того, чтобы запросить данные о текущем состоянии документа в АС СББОЛ,

необходимо знать уникальный идентификатор документа (уникальный идентификатор

записи в базах данных АС СББОЛ, содержащей данные документа). Для получения

уникального идентификатора документа должна быть выполнена следующая

последовательность шагов:

ШАГ 3:

 На стороне клиента формируется список отправленных сообщений-запросов

на передачу документов в Банк, по которым еще не получен результат

обработки (идентификатор документа).

 Каждому запросу соответствует полученное ответное служебное сообщение

(тикет). Составляется список тикетов. Каждый тикет соответствует

отправленному запросу на передачу документов. Формируется список тикетов

по переданным в АС СББОЛ документам.



Тикеты из списка передаются в веб-сервис канала УПШ при вызове метода

getRequestStatusSRP. В этом случае при вызове метода за один раз ему

может быть передано произвольное количество тикетов. Для этого требуется,

чтобы каждый тикет передавался в отдельном элементе <requests> (элемент,

содержащий входящие данные при вызове метода getRequestStatusSRP, в

соответствии с WSDL схемой). Таким образом, за один вызов метода может

быть передан весь список тикетов.

Пример ШАГа 3: Вызов метода getRequestStatusSRP, передача тикета системе

9478aa08-6079-4cec-81a4-04d362edc52f

ШАГ 4:

 В ответ веб-сервис УПШ по каждому тикету из переданного списка синхронно

возвращает ответ. При отправке нескольких тикетов в процессе одного вызова

метода ответные сообщения возвращаются в порядке следования тикетов при

передаче их методу. Содержание ответных сообщений в зависимости от

ситуации может быть различно:

ШАГ 4А:

Если результат обработки исходного сообщения еще не готов, то

система по тикету возвращает информацию о том, что запрос еще не

был обработан.

Пример ШАГа 4А: Ответ системы «Исходное сообщение еще не обработаноª

 ШАГ 4B:

Если результат обработки исходного сообщения готов, веб-сервис УПШ

возвращает квитанцию, в которой для данного тикета указывается

идентификатор документа, статус delivered, текущие дату, время и

прочие данные. Квитанция заверена технологической подписью АС

СББОЛ.

Пример ШАГа 4B: Ответ системы «Идентификатор созданной по переданному

документу записи в базах АС СББОЛ и код состояния документаª

<?xml version="1.0" encoding="UTF-8"?>

<Response xmlns="http://bssys.com/upg/response" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"

xmlns:ns1="http://bss.ru/sbrfbus" xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" createTime="2012-05-02T13:35:07"

requestId="9478aa08-6079-4cec-81a4-04d362edc52f" responseId="a5f465fb-0098-4640-b976-

3b0aeadfd58f" receiver="Ромашка" sender="DBO" version="0.1"

xsi:schemaLocation="http://bssys.com/upg/response response.xsd">

<Ticket createTime="2012-05-02T13:35:07" docId="6d7c9c84-28a8-4334-8d74-

2bcc12aeb51b">

<Sign>

<ISSUER>CN=VeriSign Class 3 Code Signing 2009-2 CA, OU=Term of use at

https://www.verisign.com/rpa (c)09, OU=Verisign Trust Network, O=Verisign, Inc., C=US</ISSUER>

<Value>ZGVmYXVsdA==</Value>

</Sign>

</Ticket>

</Tickets>

</Response>

 ШАГ 4C:

Если данные содержали ошибку, из-за которой исходное сообщение

(запрос на формирование документа) обработать не удалось (например,

было несоответствие форматов, даже при правильном содержании), то

в ответ будет отправлена квитанция с кодом состояния документа

«FAIL».

Пример ШАГа 4С: Ответ системы «Исходное сообщение не удалось обработать

из-за ошибкиª

<Response createTime="2013-10-02T13:42:40" receiver="unknown" requestId="9478aa08-6079-4cec-

81a4-04d362edc52f" responseId="bf3c2e2e-0035-48a5-869d-87a702540034" sender="DBO"

version="1.1" xmlns="http://bssys.com/upg/response">

<MsgFromBank author="UPG" message="invalid xml:SAXParseException:null:null[line:column]=[1:1]

message = Атрибутсодержимого (Content) нельзяуказыватьвпрологе. "/>

</Info>

</Ticket>

</Tickets>

</Response>

2.6.2.3. Запрос состояния клиентских документов

Запрос состояния клиентских документов можно разделить на два процесса:

 Отправка запроса состояний документов по полученным из СББОЛ

идентификаторам;

 Получение результатов обработки по отправленным запросам.

Общая схема взаимодействия приведена на Рисунке 2.

Рисунок 2.Схемы взаимодействия систем при запросе состояний обработки документов

2.6.2.4.

Отправка запроса состояний документов по

полученным из СББОЛ идентификаторам

После того, как УС Клиента получила уникальный идентификатор документа из АС

СББОЛ, с его помощью можно получать из системы информацию об этапах

обработки документа на стороне Банка.

Примечание.

В целях поддержания актуальности информации о статусах документов в учетной

системе клиента необходимо учитывать признаки окончательности статусов

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

завершить опрос статуса в рамках описываемого процесса.

Для получения на клиентской стороне информации о статусе обработки документа

требуется отправить запрос состояния документа. Используется следующая

последовательность шагов:

ШАГ 5:

 На стороне клиента формируется список исходных документов, для которых

необходимо получить данные о текущем состоянии, если они были ранее

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

получены идентификаторы документов. Рекомендуется составлять список по

всем документам, которым еще не присвоен финальный статус, и состояние

обработки которых еще может измениться.

 Идентификатор каждого документа помещается XML-контейнер согласно

формату request.xsd. Каждый идентификатор указывается как значение

атрибута Request/DocIds/DocId/@docId. Формируется xml-сообщение

Request/DocIds.

 Все элементы с указанными атрибутами передаются в сформированном xml-

сообщении веб-сервису УПШ при вызове метода sendRequestsSRP.

Пример ШАГа 5: Вызов метода sendRequestsSRP, запрос текущего состояния

документа с переданным идентификатором

<?xml version="1.0" encoding="UTF-8"?>

<Request xmlns="http://bssys.com/upg/request" xmlns:xs="http://www.w3.org/2001/XMLSchema"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Request" requestId="3299c9be-

a2ab-4a88-8ad0-3a0f7cd2efe8" orgId="24b70f22-703f-bf04-db60-bd110572f40d" version="1.0"

xsi:schemaLocation="http://bssys.com/upg/request request.xsd" sender="Ромашка"

receiver="SBBOL_DBO">

</DocIds>

</Request>

ШАГ 6:

 В ответ веб-сервис УПШ синхронно возвращает служебное сообщение (тикет),

в котором указывается присвоенный принятому xml-сообщению

идентификатор. Идентификатор сообщения позволяет в дальнейшем получить

результат его обработки в системе. Тикет возвращается сразу (до начала

обработки запроса). Такое сообщение не подписывается технологической

подписью АС СББОЛ, так как наложение ЭП сильно повлияет на время

отклика и может привести к ошибкам, связанным с превышением таймаута.

Примечание.

Следует учесть, что в каждом запросе состояний документов может содержаться

множество идентификаторов документов, но в ответ будет возвращен тикет на

сообщение в целом: один запрос - один тикет, даже если в исходном запросе были

отправлены идентификаторы нескольких документов.

Пример ШАГа 6: Получение ответа системы (тикет)

7ed0e4cb-063f-4b53-83d4-a8772e8fbcce

2.6.2.5. Получение результатов обработки по отправленным

запросам

Для получения результатов запроса нужно вызвать метод getRequestStatusSRP и

передать тикет исходного запроса. Используется следующая последовательность

шагов:

ШАГ 7:

 На стороне клиента формируется список отправленных сообщений-запросов

(запросов состояний клиентских документов), которые были переданы

системе.

 Каждому запросу соответствует полученное ответное служебное сообщение

(тикет). Составляется список тикетов. Каждый тикет соответствует

отправленному запросу состояний одного или многих документов.

Формируется список тикетов по переданным в систему запросам.

 Тикеты из списка передаются в веб-сервис канала УПШ при вызове метода

getRequestStatusSRP. В этом случае при вызове метода за один раз ему

может быть передано произвольное количество тикетов. Для этого требуется,

чтобы каждый тикет передавался в отдельном элементе <requests> (элемент,

содержащий входящие данные при вызове метода getRequestStatusSRP, в

соответствии с WSDL схемой). Таким образом, за один вызов метода может

быть передан весь список тикетов.

Пример ШАГа 7: Вызов метода getRequestStatusSRP, передача тикета системе

7ed0e4cb-063f-4b53-83d4-a8772e8fbcce

ШАГ 8:

 В ответ веб-сервис УПШ по каждому тикету из переданного списка сразу

возвращает ответ. При отправке нескольких тикетов в процессе одного вызова

метода ответные сообщения возвращаются в порядке следования тикетов при

передаче их методу. Содержание ответных сообщений в зависимости от

ситуации может быть различно:

ШАГ 8А:

 Если результат обработки исходного запроса состояний документов готов,

ответные сообщения содержат квитанции с данными о состояниях обработки

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

состояний клиентских документов. Квитанции заверены технологической

подписью Банка.

 Таким образом, в одном ответном сообщении может быть несколько

квитанций, по одной для каждого идентификатора из исходного запроса. В

квитанциях указан код текущего состояния документа, текущие дату и время, а

также, возможно, некоторые другие данные (например, указание на ошибки в

клиентском документе, если они были).

 Сообщения передаются в составном элементе Response/Tickets, содержащем

квитанции в дочерних элементах Response/Tickets/Ticket, в соответствии с

форматом response.xsd.

Примечание

Важно понимать, что при вызове метода может быть передано много тикетов, а по

каждому тикету будет получено сообщение, в свою очередь, содержащие множество

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

документов).

Пример ШАГа

8А: Ответ системы

«Код текущего состояния документа,

идентификатор которого был передан в исходном сообщенииª

<?xml version="1.0" encoding="UTF-8"?>

<Response xmlns="http://bssys.com/upg/response" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"

xmlns:ns1="http://bss.ru/sbrfbus" xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" createTime="2012-05-02T13:35:07"

requestId="3299c9be-a2ab-4a88-8ad0-3a0f7cd2efe8" responseId="31da8d69-0e63-46fa-869f-

7d6f34914154" sender="DBO" version="0.1" xsi:schemaLocation="http://bssys.com/upg/response

response.xsd">

<Ticket createTime="2012-05-02T13:35:07" docId="6d7c9c84-28a8-4334-8d74-

2bcc12aeb51b">

<Info docExtId="2dcb3631-4b1d-408d-9fc7-3701b2b0afe9"

tatusStateCode="INVALIDEDS">

</Info>

<Sign>

<ISSUER>CN=VeriSign Class 3 Code Signing 2009-2 CA, OU=Term of

use at

https://www.verisign.com/rpa (c)09, OU=Verisign Trust Network,

O=Verisign, Inc

C=US</ISSUER>

<Value>ZGVmYXVsdA==</Value>

</Sign>

</Ticket>

</Tickets>

</Response>

ШАГ 8B:

 Если результат обработки исходного сообщения еще него готов, то система по

тикету возвращает информацию о том, что запрос еще не был обработан.

Примечание.

Если после исполнения документа в АБС, документ был отказан в расчётной системе,

то на запрос УС Клиента о подготовленных выписках СББОЛ должен вернуть вместе

с выписками квитанции с текущим состоянием документа в СББОЛ. Такая квитанция

возвращается только в случае, если УС Клиента сначала было получено сообщение

об исполнении документа, а потом документ был отказан в расчётной системе Банка.

Пример ШАГа 8В: Ответ системы «Исходное сообщение еще не обработаноª

2.6.2.6. Взаимодействие при изменении финальных статусов

В случае присвоения документу финального статуса, учетной системе клиента не

требуется запрашивать обновление данного статуса, т.к. документ достигает

конечного этапа жизненного цикла, и дальнейших изменений не предполагается

(например, статус

«Исполнен»). Однако в некоторых редких случаях бывают

изменения также и на финальных статусах.

Если после исполнения документа в АБС документ был отказан в расчётной системе

(РС) Банка, то УС Клиента не будет запрашивать обновление статуса по этому

документу (для нее документ достиг финального статуса).

Поэтому информация о таких изменениях финальных статусов документов

передаётся в учетную систему клиента вместе с подготовленными выписками по

счетам. В ответ на попытку получить подготовленные выписки

(запрос

Request/Incoming) канал УПШ вернет вместе с выписками квитанции с текущим

(изменившимся) состоянием документа в АС СББОЛ. Такие квитанции возвращаются

только в случае, если учетной системе клиента ранее было передано сообщение об

успешном исполнении документа, а потом документ был отказан в расчётной

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

запросе

Request/Incoming

отсутствует

параметр

Request/Incoming/@includeChangedDocs либо присутствует со значением “TRUE”.

Если же указанный параметр присутствует со значением “FALSE”, то изменения

финальных статусов документов не будут возвращены в УС Клиента.

Таким образом, если нужно сообщить об изменения статуса документа, уже после

того, как в учетную систему клиента была передана квитанция с кодом финального

статуса (например, «Исполнен»), то вместе с выписками по счету будет передана

квитанция с кодом нового статуса («Отказан АБС»). Формат квитанций по отказанным

в расчетной системе Банка документам аналогичен обычным квитанциям.

Рисунок

3. Схема процесса получения информации о результатах обработки клиентских

документов в случае изменения статуса после отправки в УС статуса «Исполненª (отказ в РС)

2.6.2.7. Получение документов из Банка (получение выписок по

счетам)

Получение документов из банка можно разделить на два процесса:

 Отправка запроса на получение документов из Банка

 Получение результатов обработки по отправленному запросу

Общая схема взаимодействия приведена на рисунке 3.

Рисунок 4. Схемы взаимодействия систем в рамках процесса получения выписки

2.6.2.8. Отправка запроса на получение документов из Банка

Для получения документов из Банка необходимо сначала отправить запрос на

получение готовых к отправке документов. Используется следующая

последовательность шагов:

ШАГ 13:

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

который представляет собой сообщение, содержащее элемент

Request/Incoming и электронную подпись сообщения в составном элементе

Request/Sign.

 Запрос передается в Web-сервис УПШ при вызове метода sendRequestsSRP.

ПримерШАГа 13: Запрос sendRequestsSRP