"ДБО BS-Client. Частный Клиент" v.2.4

Описание Адаптера для интеграции с платежной системой e-port

Руководство администратора

Версия 2.4.0.6

2. Аннотация

Система «Частный Клиент» это полнофункциональное тиражируемое решение, обеспечивающее удобное и надежное обслуживание розничных клиентов через Интернет и по телефону. Система включает в себя практически полный пакет электронных услуг для обслуживания счетов Клиентов, операций с кредитами, депозитами и картами Клиента, осуществления переводов и платежей.

Система «Частный Клиент» включает в себя следующие подсистемы:

· Интернет-клиент

· Телефон-клиент

· Информационный клиент

· Мобильный клиент (КПК)

· WAP-клиент

· iPhone-Клиент

· Android-Клиент

· Мобайл-Клиент (сотовые телефоны)

· Киоск Самообслуживания.

Система предназначена для решения задач доставки, контроля и обработки различных типов платежных и информационных документов Клиентов, обмена сообщениями в произвольном формате, получения выписок по картам и счетам.

Данный документ предназначен для администраторов системы и содержит общее описание взаимодействия системы «Частный Клиент» с системой e-port.

СОДЕРЖАНИЕ:

1. Аннотация. 2

2. Настройка платежной системы в ЧК. 4

2.1. Параметры Адаптера. 4

2.2. Настройка ЭЦП. 5

2.3. Настройки в Построителе. 6

2.4. Настройки контролей. 6

2.5. Создание автопроцедур для выгрузки оплаты услуг 6

2.6. Журнализация обмена данными с ПС. 7

2.7. Обновление справочника «Виды услуг». 8

НЕ нашли? Не то? Что вы ищете?

2.7.1. Принципы обмена справочной информацией. 8

2.7.2. Версия справочника. 8

2.7.3. Формат справочника получаемого с сервера и преобразование его данных в ЧК. 8

3. Взаимодействие ЧК, ПС и АБС. 11

3.1. Порядок обмена данными с сервером e-port. 11

3.2. Обмен сообщениями с сервером e-port. 14

3.2.1. Формирование сообщения. 14

3.2.2. Выгрузка оплаты услуг 14

3.2.3. Обработка ответа на запрос 16

4. Описание обмена с сервером e-port. 17

4.1.1. Параметры протокола HTTP. 17

4.1.1.1. MIME-тип сообщения и кодировка (заголовок "Content-Type") 17

4.1.1.2. Размер сообщения (заголовок "Content-Length") 17

4.1.1.3. Аутентификация (заголовок "X-Eport-Auth") 18

4.1.1.4. Аутентификация ответа сервера. 18

4.1.1.5. Версия справочника (заголовок "X-Eport-Version") 18

4.1.1.6. Списки альтернативных серверов (заголовки "X-Eport-Host") 18

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

4.1.2.1. Код статуса HTTP в ответе сервера. 19

4.1.2.2. Способы форматирования сообщений протокола. 20

4.1.2.2.1. Простой текстовый формат. 20

4.1.2.2.2. XML-формат. 20

4.1.2.2.3. Формат справочника. 21

4.1.2.3. Расширения протокола. 21

4.1.2.4. Пример HTTP-запроса. 21

3. Настройка платежной системы в ЧК.

3.1. Параметры Адаптера

Параметры Адаптера содержаться в справочнике «Платежные системы» (Справочники – Оплата услуг – Платежные системы), запись «e-port».

На закладке «Основная» указывается BLL модуль, в котором хранятся настройки адаптера. И устанавливается галка «Обновлять справочник в автоматическом режиме» для автоматического обновления записей справочника «Виды услуг» связанных с системой e-port.

На закладке «Дополнительные параметры» представлены настройки адаптера (Рис. 2‑1).

Рис. 2‑1 Дополнительные параметры платежной системы E-port

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

Описание

Rate

Текущий курс e-port

RateUpdadeDate

Дата обновления курса

SrvListVer

Версия списка серверов

SrvList

Список URL-адресов серверов

CurSrvIndex

Порядковый номер текущего сервера

RefVer

Версия справочника (используется при обновлении справочника «Виды услуг»)

CurRate

Курс системы RUR/EYE (= RUR/USD)

LastSession

Дата/время последнего запроса к ПС

LastOperNum

Счетчик операций. Содержит порядковый номер последней операции. Используется при формировании идентификатора операции (в блоке OPERATION запроса к ПС).

RequestInt

Минимальный интервал между запросами в миллисекундах, по умолчанию 5000

MaxLength

Максимальный размер сообщения в E-Port в байтах, по умолчанию 4096

MaxDocsPerRequest

Количество одновременно обрабатываемых документов

PointID

Номер точки агента

ConnectionTimeOut

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

При вызове Адаптер посылает запросы в ПС, и в случае необходимости, автоматически обновляет настройки установленные по умолчанию.

Внимание!

Параметр RequestInt автоматически не обновляется.

Параметр RefVer обновляется при обновлении справочника «Виды услуг»

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

3.2. Настройка ЭЦП

Для шифрования сообщений между ЧК и E-port используется технология OpenSSL.

Для работы с системой необходимо наличие в каталоге SYSTEM (%BSSRoot%\ SYSTEM) следующих файлов:

· WrapSignVerify. dll – предназначен для подписи/проверки подписи средствами OpenSSL.

(библиотека, необходимая для работы модуля подписи/проверки подписи)

· ssleay32.dll

· libeay32.dll

(библиотеки для OpenSSL версии 0.9.8)

С помощью приложения openssl. exe (подробную информацию по установке и использованию данного приложения можно получить на сайте www. openssl. org.) необходимо сформировать закрытый ключ и запрос сертификата. Запрос сертификата необходимо зарегистрировать на сервере e-port. Оттуда же необходимо скачать открытый ключ e-port. Подробные инструкции для этих действий: http://www. *****/dev/2/info. html#sign.

После получения необходимых файлов необходимо указать пути к ним в справочнике «Платежные системы» (Справочники _-> Оплата услуг -> Платежные системы), для записи «e-port» на вкладке «Настройка филиалов» (Рис. 2‑2).

Если запись «e-port» создается для отдельного филиала, надо указать его БИК. Если БИК на вкладке не указан, то параметры записи используются для головного офиса.

F Для настройки ЭЦП для головного отделения банка или филиала:

· Откройте справочник «Платежные системы» (Справочники _-> Оплата услуг -> Платежные системы);

· Среди записей справочника выберите запись «e-port» и двойным щелчком левой кнопки мыши откройте форму для её редактирования.

· В открывшейся форме прейдите на закладку «Настройки филиалов». Для редактирования существующей записи необходимо её выбрать и двойным щелчком левой кнопки мыши открыть форму для редактирования. Для создания новой записи необходимо нажать кнопку «Insert».

Рис. 2‑2 Настройка ЭЦП для системы E-port

· В открывшемся окне редактирования (Рис. 2‑2) укажите необходимые данные для настройки ЭПЦ.

3.3. Настройки в Построителе

В Построители должны быть настроены следующие параметры:

· StandartABSReq (Конфигурации -> IFIZ -> PUPAY), чтобы документы могли выгружаться в ПС, необходимо установить значение FALSE. Если установлено значение TRUE, то документы будут выгружаться только в АБС.

· CancelDocumentAfterPSReject (Конфигурации -> IFIZ -> PUPAY), если установить значение TRUE, то при отказе ПС будет формироваться запрос на отзыв документа из АБС (если АБС поддерживает отзыв документа).

· NewFormat (Конфигурации -> IFIZ -> ABSAPI -> Eport) если установлено значение TRUE, то будет использоваться протокол взаимодействия с системой «E-port» вступивший в действие 10.07.2011.

3.4. Настройки контролей

Для того, что бы в Интернет-Клиенте отображались услуги, оплачиваемые через систему CyberPlat, необходимо в контроле ShowExtPaysIDS (Настройки -> Настройки контролей -> Документы -> Распоряжение на единовременную оплату услуг -> RETPUPAYONETIME_IFIZ. ShowExtPaysIDS) указать ID платежной системы (для E-port = 3).

3.5. Создание автопроцедур для выгрузки оплаты услуг

Необходимо создать автопроцедуру выгрузки оплаты услуг аналогично другим выгрузкам. В качестве итоговых статусов должны быть указаны: Принят+, Отказан АБС+, Исполнен АБС, Проверка ПС, Проверен ПС, Подтверждение ПС, Отмена ПС, Отмена ПС+ (Рис. 2‑3).

Рис. 2‑3 Создание автопроцедуры для системы E-port

Подробная информация о работе и настройке автопроцедур содержится в документе «Руководство администратора».

3.6. Журнализация обмена данными с ПС

Полный текст запросов к серверу ПС и ответов от него Адаптер записывает в общие логи с запросами/ответами в АБС (в папки RetABS и BS_R_PUPAY). Папки с логами хранятся в каталоге «Logs» (%BSSRoot%\SUBSYS\Logs).

В лог пишется следующая информация:

· Идентификатор ПС из параметров функции Адаптера

· Референс документа в ЧК

· Дата/время создания записи

· Полный текст http-запроса или ответа

3.7. Обновление справочника «Виды услуг»

3.7.1. Принципы обмена справочной информацией

Обмен справочной информацией ЧК с системой e-port необходим для поддержания в актуальном состоянии информации об услугах доступных к оплате через данную платежную систему. Обмен справочной информацией с сервером ПС инициализируется автопроцедурой «Обновление справочника услуг».

Адаптер в запросе справочника указывает номер локального справочника, и получить в ответ справочник изменений, содержащий информацию только по измененным, добавленным и удаленным объектам справочника.

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

При импортировании списка видов услуг Реквизиты поставщика услуги не обновляются (поля БИК банка (RecipientBankBIC), номер счета (RecipientAccount) таблицы PUTypes). При необходимости эти поля заполняются вручную.

3.7.2. Версия справочника

При первом вызове Адаптер посылает в ПС запрос справочника услуг (указывает в HTTP-заголовке X-Eport-Version: dir=0) и модифицирует PUTypes в соответствии с полученным ответом. Номер версии из заголовка ответа записывается в настройку RefVer

При последующих запросах Адаптер сравнивает версию справочника, информация о которой содержится в каждом ответе сервера ПС (X-Eport-Version: dir=ref_version), и текущую версию локального справочника (RefVer). При расхождении версий Адаптер запрашивает у сервера ПС данные об измененных записях справочника.

Заголовок справочника, полученного в ответе ПС, содержит номер предыдущей версии справочника, на основе которого сформирован данный инкрементный справочник (справочник изменений).

Для определения необходимых действий Адаптер проверяет его значение следующим образом:

· Адаптер выполняет модификационные команды в случае, если версия справочника совпадает с текущей версией локального справочника.

· Если версия справочника равна нулю, то это означает, что сервер ПС принял решение передать Адаптеру полный (а не инкрементный) справочник, и Адаптер выполняет замену локального справочника новым.

· В случае, если RefBaseVersion не равен текущей версии локального справочника и не равен нулю, Адаптер запрашивает полный справочник (X-Eport-Version: dir=0).

3.7.3. Формат справочника получаемого с сервера и преобразование его данных в ЧК.

Справочник представляет собой набор записей, состоящих из полей. Разделителем записей служит «CLRF», разделителем полей - символ табуляции.

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

"-" (минус) - удалить объект из локального справочника

"+" (плюс) - добавить или заменить объект в локальном справочнике.

Остальные символы указывают на тип объекта:

"x" - заголовок справочника

"v" - описатель провайдера (в ЧК не анализируется)

"e" - описатель услуги пополнения

"p" - описатель услуги продажи пин-кода

В запросе «заголовок» справочника имеет следующий вид:

	1	2	3	4
+x		0	00:01:01	27.8789

Поля заголовка:

· Номер версии справочника (1) сервера, тип LONG (заполняет поле RefVer в таблице с параметрами Адаптера)

· Номер предыдущей версии справочника (2), на основе которой сформирован справочник изменений, или "0" в случае полного справочника.

· Дату и время формирования справочника сервера (3), тип TIMESTAMP (заполняет поле RateUpdateDate в таблице с параметрами Адаптера)

· Курс системы (4), тип MONEY (заполняет поле Rate в таблице с параметрами Адаптера)

Запись "описатель услуги" и в случае пополнения, и в случае продажи пин-кода содержит одинаковый набор параметров. В запросе «описатель услуги» справочника имеет следующий вид:

4420

406

МТС

0..0000

1.0000EYE

0.0000

Номер телефона

^\d$

ЧК обрабатывает параметры полученной записи "описателя услуги" и заполняет поля справочника «Виды услуг» следующим образом:

· Если тип услуги (1) «+p», то будет установлена галка «Услуга выдачи нового ПИН кода».

· Идентификатор товара/услуги (2), LONG, уникальный в системе. Заполняется поле «Идентификатор услуги в ПС».

· Идентификатор провайдера (3), LONG, ссылается на описатель провайдера. В зависимости от провайдера услуга будет включена в определенную группу услуг.

· Наименование товара/услуги (4), VARCHAR(1024). Заполняется поле «Название услуги (русское)».

· Цена единицы провайдера для данной услуги с признаком валюты (6), МОNEY c тройкой символов 'RUR' или 'EYE' справа. Поле «Цена единицы провайдера» заполняется значением параметра без трех последних символов. Три последних символа («RUR» или «EYE») подставляются в поле «Признак валюты». Поле «Точность (количество знаков после разделителя) на объем сделки EYE» заполняется путем подсчета количества десятичных знаков в параметре.

· Ограничение на объем сделки (5), значение типа MONEY или список значений типа MONEY с разделителем «;» в случае фиксированной величины, или значения типа MONEY с разделителем «-» в случае диапазона. Значение параметра используется для заполнения следующих полей:

o Если объем сделки фиксированный, т. е. параметр содержит перечень значений через разделитель «;» или единственное значение суммы, то будет установлена галка «Фиксированная сумма оплаты» и заполнено поле «Список сумм, допустимых до оплаты в единицах EYE».

o Если объем сделки фиксированный, то поле «Список сумм, допустимых до оплаты» заполняется предопределенным перечнем значений платежа, разделенных «;». Рассчитывается на основе значений из поля «Список сумм, допустимых до оплаты в единицах EYE». Значения умножаются на цену единицы провайдера (если «Признак валюты» «RUR») или на цену единицы провайдера и курс RUR/EYE из таблицы ExtPays (если «Признак валюты» «EYE»). Полученные значения округляются в большую сторону до двух знаков после запятой.

o Минимальным значением из параметра заполняется поле «Минимальный объем сделки» в единицах провайдера.

o Значение подставляемое в поле «Минимальная сумма платежа» рассчитывается следующим образом:

§ Если «Признак валюты» «RUR», то Минимальная сумма платежа является произведением цены единицы провайдера на минимальный объем сделки (округляется в большую сторону до двух знаков после запятой).

§ Если «Признак валюты» «EYE», Минимальная сумма платежа является произведением цены единицы провайдера на минимальный объем сделки и курс RUR/EYE из таблицы ExtPays (округляется в большую сторону до двух знаков после запятой).

o Максимальное значением из параметра заполняется поле «Максимальный объем сделки» в единицах провайдера.

o Значение подставляемое в поле «Максимальная сумма платежа» рассчитывается следующим образом:

§ Если «Признак валюты» «RUR», то Максимальная сумма платежа является произведением цены единицы провайдера на максимальный объем сделки (округляется в большую сторону до двух знаков после запятой).

§ Если «Признак валюты» «EYE», Максимальная сумма платежа является произведением цены единицы провайдера на максимальный объем сделки и курс RUR/EYE из таблицы ExtPays (округляется в большую сторону до двух знаков после запятой).

· Ограничение на максимальный размер комиссии Агента (7), MONEY, величина в процентах. Величину единовременного вознаграждения Агента по данной услуге, MONEY, величина в процентах. ЧК не обрабатывается. Заполняется в Сbank-е вручную на закладке «Комиссия».

· Перечень наименований атрибутов (8), список значений типа VARCHAR(1024) с разделителем точка с запятой. Содержит наименования дополнительных реквизитов используемых при оплате услуги (записи на вкладке «Дополнительные реквизиты»).

· Перечень регулярных выражений (9) POSIX для контроля значений этих атрибутов, список значений типа VARCHAR(1024) с разделителем точка с запятой. Содержит маски ввода для дополнительных реквизитов используемых при оплате услуг.

· Следующие поля в справочнике «Виды услуг» заполняются по умолчанию:

o «Платежная система» - 3, e-port.

o Устанавливается галка «Автоматическое обновление из ПС»

o Устанавливается галка «Услуга доступна для оплаты»

o Устанавливается галка «Единовременная оплата»

4. Взаимодействие ЧК, ПС и АБС

4.1. Порядок обмена данными с сервером e-port

Операция в платежной системе e-port представляет собой пополнение лицевого счета клиента у провайдера или продажу пин-кода провайдера. Дополнительно может осуществляться обмен справочной информацией с сервером e-port; в процессе взаимодействия получаем информацию об ассортименте предоставляемых услуг и общих бизнес-правилах и ограничениях проведения сделок в системе e-port.

Электронный документ представляет собой набор именованных атрибутов (пара имя-значение) и имеет определенную структуру. Документ передается в виде сообщения, оформленного в текстовом формате или в формате xml.

Обмен данными производится по протоколу HTTPS. В процессе устанавливается защищенное SSL-соединение с сервером, формирует и направляет серверу сообщение с использованием HTTP-метода POST (запрос), и в контексте этого же соединения получает сообщение сервера (ответ). Тело HТTP-сообщения содержит оформленный документ, заголовки сообщения указывают на формат и кодировку документа, объем передаваемых данных и аутентификационную информацию. Сервер аутентифицирует запрос Адаптера по электронной цифровой подписи Адаптера (ЭЦП). Адаптер также может произвести аутентификацию ответа сервера по ЭЦП.

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

Порядок проведения распоряжения на оплату услуг с использованием ПС:

1. При подаче клиентом распоряжения на единовременную оплату услуг ЧК подает в ПС команду проверить корректность введенных клиентом данных.

2. При подтверждении ПС возможности исполнения данного распоряжения ЧК подает в ПС распоряжение, после ожидает подтверждение.

3. При подтверждении ПС возможности исполнения данного распоряжения в шлюз с АБС передаётся запрос BS_R_PUPAY.

4. На основании данных из BS_R_PUPAY шлюз формирует платёжный документ в учётной системе банка.

5. После исполнения документа АБС в ПС направляется подтверждение распоряжения.

При отказе АБС в исполнении распоряжения в ПС направляется команда об отмене распоряжения.

6. При получении от ПС подтверждения исполнения распоряжения дальнейшая обработка прекращается, и документ считается исполненным.

7. В случае отказа ПС в проведении распоряжения, Адаптер формирует запрос к АБС на отзыв документа (если АБС поддерживает запрос BS_R_CANCEL) либо сразу присваивает документу статус «Ошибка отзыва». Дальнейшие действия с такими документами производятся вручную сотрудниками банка (либо отзываются из учётной системы, либо выясняется причина отказа ПС).

В случае если АБС поддерживает запрос BS_R_CANCEL, при успешном отзыве распоряжения дальнейшая обработка прекращается.

Рис. 3‑1 Схема проведения распоряжения на оплату услуг с использованием системы E-port

4.2. Обмен сообщениями с сервером e-port

4.2.1. Формирование сообщения

Запросы к ПС

Адаптер всегда проводит операции в двухфазном режиме (ЧК подает распоряжение в АБС только после проверки данных в ПС): блоки CHECK OPERATION в одном запросе и блок типа CONFIRM – в последующем запросе.

Для запроса в ПС возможности проведения платежа Адаптер формирует запрос– в блоке типа CHECK.

Для подачи в ПС распоряжений на оплату услуг Адаптер формирует запросы специального формата, содержащие информацию о каждом подаваемом распоряжении – в блоке типа OPERATION. При подаче запросов Адаптер соблюдает минимальный интервал между ними (в зависимости от настройки RequestInt из записи справочника )

Для подачи в ПС подтверждений распоряжений на оплату услуг Адаптер формирует запросы специального формата, содержащие информацию в блоке типа CONFIRM.

Для отмены распоряжения предусмотрены блоки типа CANCEL.

Ответ из ПС

В ответ на каждый запрос Адаптера сервер ПС возвращает ответ, содержащий информацию со статусами распоряжений – блоки типа RESULT. Ответ сервера ПС включает блок типа RESULT для распоряжения, информация о котором присутствовала в запросе.

Обмен сообщениями по распоряжению завершается, когда от сервера по данному распоряжению получен блок RESULT со статусом «Успешно» или «Отказано».

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

Распоряжение в запросах идентифицируется по уникальному на определенном временном интервале идентификатору, присвоенному распоряжению Адаптером, при создании первого блока типа OPERATION для данного распоряжения.

4.2.2. Выгрузка оплаты услуг

Для формирования запроса система отбирает все документы с определенными статусами относящиеся к e-port. Для каждого отобранного документа создается отдельный запрос содержащий один из блоков типа CHECK, OPERATION, CONFIRM и CANCEL.

Формируемые блоки запросов:

Статус документа	Тип блока запроса	Назначение блока запроса
Принят+	CHECK	Запрос в ПС для проверки возможности проведения платежа с указанными реквизитами и суммой
Принят+	OPERATION	Подача в ПС распоряжения с обязательным подтверждением.
Проверка ПС	OPERATION	Запрос в ПС статуса распоряжения.
Исполнен АБС	CONFIRM	Подача в ПС команды на подтверждение оплаты ранее поданного распоряжения.
Подтверждение ПС	CONFIRM	Запрос в ПС статуса распоряжения.
Отказан АБС 1	CANCEL	Подача в ПС команды на отмену оплаты ранее поданного распоряжения.
Отмена ПС	CANCEL	Запрос в ПС статуса распоряжения.

Блоки типа CHECK, OPERATION, CONFIRM и CANCEL имеют одинаковые атрибуты и заполняются аналогично:

id – Идентификатор операции (атрибут SavedDocRef из таблицы RetPUPayOneTime). В случае, когда распоряжение еще не было отправлено в ПС, данный атрибут заполняется идентификатором операции сформированным следующим порядком:

· Идентификатор операции должен быть уникален в пределах запросов Агента на интервале времени не менее 24-х дней.

· Для обеспечения выполнения этого Адаптер генерирует идентификаторы операции следующего вида: «NNNNNNNNN_YYMMDD_hhmm», где

o NNNNNNNNN – порядковый номер операции (атрибут LastOperNum, из таблицы ExtPays); непосредственно перед генерацией идентификатора увеличивается на единицу; сбрасывается, когда очередное число превышает указанное количество разрядов

o YY, MM, DD – текущая дата (год, месяц, день, соответственно)

o hh, mm – текущее время (часы, минуты, соответственно)

checked – всегда равно значению атрибута id (в запросе CHECK данный атрибут отсутствует).

product – Идентификатор услуги (атрибут PUID из таблицы RetPUPayOneTime).

value – Сумма документа (в запросе CHECK данный атрибут отсутствует).

· Если происходит оплата услуги, то используется значение атрибута Amount из таблицы RetPUPayOneTime, объединенное с тройкой символов кода валюты «RUR».

· Если услуга покупка пин-кода, то на каждую единицу пин-кода создаются отдельное распоряжение, где для атрибута value подставляется значение – 1.00QTY.

account – значения дополнительных реквизитов. Если услуга создана при обновлении из ПС (атрибут AutoUpdate из таблицы PUTypes равен еденице), то заполняется значениями атрибута FieldValue из таблицы RetPUPayOneTime. AddFields. В случае если пользователь не заполнил ни одного реквизита, поле account отсутствует.

Ptype – тип платежа (данный атрибут присутствует только в запросе OPERATION). Возможные значения:

0 – если платеж осуществляется наличными (для Системы ЧК на данный момент не актуально)

1 – если платеж осуществляется со счета или карты своего банка

2 – если платеж осуществляется с карты другого банка

total – сумма платежа (в RUR) вместе с комиссией (данный атрибут присутствует только в запросе OPERATION).

Примеры сформированных запросов (без заголовков):

CHECK

id=

product=4165

account=

OPERATION

id=122

checkid=122

product=4420

value=1.00QTY

account=

CONFIRM

id=123

checkid=123

product=4420

value=300RUR

account=

CANCEL

id=124

checkid=124

product=4420

value=1.00QTY

4.2.3. Обработка ответа на запрос

Успешность выполнения команды оценивается по блоку RESULT соответствующей команды в ответе сервера. В ответе обязательно присутствует блок RESULT для последнего запроса с блоком CHECK /OPERATION/CONFIRM/CANCEL.

Блок типа RESULT содержит следующие атрибуты:

Наименование	Тип	Содержание
id	VARCHAR(64)	Идентификатор распоряжения (сформированный в ЧК для запроса).
code	LONG	Код операции по распоряжению.
omsg	VARCHAR(1024)	Сообщение для разработчика, описывающее статус распоряжения.
cmsg	VARCHAR(1024)	Сообщение для клиента, описывающее статус распоряжения.
Следующие поля блок RESULT содержит только в случае успешного исполнения распоряжения (code=0..999):
pmsg	VARCHAR(64)	Текстовое сообщения для печати документа клиента; содержит PIN-код (для операции покупки PIN-кода).
card	CARD	ЧК не используется
pin	VARCHAR(10)	ЧК не используется

При получении в ответе от сервера блоков типа RESULT Адаптер анализирует коды состояния операций (поле code) и в зависимости от его значения изменяется (или не изменяет) статусы документов:

Текущий статус документа в ЧК	Возможные статусы	Установить статус документа
Значение поля code	Наименование статуса
Принят+	1000..1999	Отказано	Отказан ПС 1
2000..2999	Отложено	Проверка ПС
3000..3999	Требуется подтверждение	Проверен ПС
Проверка ПС	1000..1999	Отказано	Отказан ПС 1
2000..2999	Отложено	Статус не меняется
3000..3999	Требуется подтверждение	Проверен ПС
Исполнен АБС	0..999	Успешно	Исполнен
1000..1999	Отказано	Отказан ПС 2
2000..2999	Отложено	Подтверждение ПС
3000..3999	Требуется подтверждение	Статус не меняется
Подтверждение ПС	0..999	Успешно	Исполнен
1000..1999	Отказано	Отказан ПС 2
2000..2999	Отложено	Статус не меняется
Отказан АБС 1	1000..1999	Отказано	Отказан АБС 2
2000..2999	Отложено	Отмена ПС
3000..3999	Требуется подтверждение	Статус не меняется
Отмена ПС	1000..1999	Отказано	Отказан АБС 2
2000..2999	Отложено	Статус не меняется

В случае изменения статуса документа на исполнен, в поле RetPUPayOneTime. NoteFromBank копируется значение поля pmsg ответа сервера (может содержать PIN-код).

5. Описание обмена с сервером e-port

Данная глава носит ознакомительный характер.

Исходная информация: http://www. *****

5.1.1. Параметры протокола HTTP

5.1.1.1. MIME-тип сообщения и кодировка (заголовок "Content-Type")

Допускаются форматы text/plain (Простой текстовый формат), text/xml (XML-формат) и кодировки "KOI8-R" и "Windows-1251". При отправке запроса Агент сообщает об используемом формате сообщения и кодировке в HTTP-заголовке "Content-type". Ответ сервера всегда имеет тот же формат и кодировку, что и запрос Агента, и содержит соответствующий HTTP-заголовок.

Пример:

Content-Type: text/xml; charset=Windows-1251

5.1.1.2. Размер сообщения (заголовок "Content-Length")

Обязательный заголовок, содержит величину тела HTTP-сообщения. Максимально возможный объем запроса - 4 Кб, в случае превышения данной величины и в случае пустого запроса сервер откажет в приеме сообщения.

Пример:

Content-Lengt: 128

5.1.1.3. Аутентификация (заголовок "X-Eport-Auth")

Аутентификация запроса осуществляется сервером по значению обязательного HTTP-заголовка "X-Eport-Auth". Обязательным полем заголовка является номер точки Агента (поле "point").

Аутентификация осуществляется по ЭЦП и требуется наличие дополнительного параметра "sign", содержащего цифровую подпись сообщения. По умолчанию используется алгоритм ЭЦП RSA/MD5 с длиной ключа 1024 бит. Цифровая подпись формируется по телу HTTP-запроса.

ЭЦП сообщения представляет собой бинарную строку, которая при передаче кодируется с использованием алгоритма Base64 или преобразуется в строку шестнадцатеричных цифр. Способ кодирования указывается с помощью дополнительного поля заголовка "encoding", которое может принимать значения "base64" или "hex", в случае отсутствия заголовка используется значение по умолчанию "base64".

Примеры заголовка аутентификации по ЭЦП:

X-Eport-Auth: point=123; sign="4PLu8NTg7Ojr6P8wH"

X-Eport-Auth: point=123; sign="8o6+7iIMAuwC4g+MD"; encoding="base64"

X-Eport-Auth: point=123; sign="6FB4FD47E73E30EF12230E2D1"; encoding="hex"

5.1.1.4. Аутентификация ответа сервера

Ответ сервера всегда содержит HTTP-заголовок "X-Eport-Auth" с ЭЦП ответа (алгоритм RSA/MD5 с длиной ключа 1024 бит в кодировке "base64").

Пример заголовка ЭЦП сервера:

X-Eport-Auth: sign="2fWNjEVEhOzn/NZkBin0tS+3qnWea"

5.1.1.5. Версия справочника (заголовок "X-Eport-Version")

Сервер в каждом своем ответе публикует действующий номер справочника. Номер справочника содержится в поле заголовка "dir":

Пример:

X-Eport-Version: dir=1024

5.1.1.6. Списки альтернативных серверов (заголовки "X-Eport-Host")

Сервер e-port реализован в виде симметричного кластера, который представляет собой группу совершенно идентичных по функциональности серверов, доступных из интернет по различным адресам. В целях оперативного уведомления о доступности и загруженности серверов кластера, протоколом предусмотрена передача дополнительного HTTP-заголовка "X-Eport-Host". Для повышения надежности взаимодействия реализуется обработка этого заголовка.

Агент запрашивает действующий список адресов, добавив к любому из запросов протокола дополнительный заголовок:

X-Eport-Host: 0

При получении запроса сервер добавляет в ответ дополнительный HTTP-заголовок "X-Eport-Host", включающий в себя номер версии списка(числовой код) и действующий список адресов (параметр "list").

Пример:

X-Eport-Host: 458; list="dealer-m1.fe. *****;dealer-c1.fe. *****;

dealer-m2.fe. *****;dealer-c2.fe. *****;dealer-m3.fe. *****;

dealer-c3.fe. *****"

Агент запоминает полученный список и номер версии, и далее все запросы направляет по первому из перечисленных в списке адресов, дополняя каждый запрос заголовком "X-Eport-Host", в качестве значения указывая полученный номер версии. В случае недоступности сервера, в том числе сетевой сбой, значительное возрастание времени установки соединения, наличие HTTP-кодов кодов ответа 500 или 503, Агент переходит к использованию следующего адреса из списка, и все очередные запросы отправляет на этот адрес. При достижении конца списка Агент вновь переходит к первому адресу, то есть список используется "по кругу".

В случае, если список доступных адресов изменился, сервер с первым же ответом Агенту отправляет заголовок "X-Eport-Host" с новым номером версии и новым списком адресов. Агент, получив новый список, обрабатывает его описанным выше способом, то есть запоминает полученную информацию и переходит к использованию новых адресов.

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

5.1.2.1. Код статуса HTTP в ответе сервера

В случае успешной обработки запроса сервером ответ содержит стандартный код успешной обработки HTTP-запроса "200 OK" и тело HTTP-сообщения содержит результаты обработки операций. Если в процессе приема или обработки запроса возникли технические проблемы, код HTTP-ответа принимает иное значение, и тело HTTP-сообщения содержит текстовое описание причин отказа в формате "text/plain". Ситуацию, в которой ответ сервера не получен, или HTTP-код ответа сервера принимает значение, отличное от "200 OK", нельзя интерпретировать как отказ сервера по операциям запроса. Для уточнения результата обработки операций после разрешения проблем требуется произвести повторный запрос. О состоянии операции может свидетельствовать только ответ сервера с кодом "200 OK", содержащий сообщение RESULT по данной операции.

Коды ошибок при формировании запроса на стороне Агента:

400 "Bad Request" Неверный формат запроса или ошибки при попытке декомпресии тела сообщения

403 "Forbidden" Требуется SSL

405 "Method Not Allowed" Требуется метод POST

408 "Request Time-out" Тайм-аут на чтение запроса исчерпан, клиент передает данные слишком медленно

411 "Length Required" Требуется http-заголовок Content-Length

412 "Precondition Failed" Отcутствие или ошибки формата http-заголовков.

413 "Request Entity Too Large" Размер запроса превышает максимально допустимый

415 "Unsupported Media Type" Недопустимое значение http-заголовка Content-Type

501 "Method Not Implemented" Недопустимое значение http-заголовка Content-Encoding

401 "Authorization Required" - свидетельствует об отказе сервера в авторизации запроса. Необходимо исправить параметры или связаться со службой поддержки e-port для уточнения причин отказа, среди которых могут быть:

· ЭЦП неверна

· Неверно указан номер карты

· Неверно указан пин-код карты

· Неверно указан номер точки

· Точка заблокирована куратором

· Запрос не прошел контроль ограничений по ip-адресу или времени работы точки

503 "Service Temporarily Unavailable", 500 "Internal Server Error" свидетельствует о сбое или временной недоступности сервера.

5.1.2.2. Способы форматирования сообщений протокола

Значения атрибутов сообщения обрабатываются таким образом, чтобы исключить специальные символы, используемые в качестве разделителей в данном формате (text или xml).

Пары имя-значение, соответствующие каждому атрибуту сообщения, в порядке, указанном в перечне атрибутов сообщения, объединяются в строку сообщения вместе с именем сообщения, с использованием специальных разделителей.

Для асинхронного режима строки сообщений объединяются вместе.

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

5.1.2.2.1. Простой текстовый формат

В случае, если значение какого-либо атрибуты сообщения содержит символы конца строки, они заменяются на пары символов, состоящих из символа '\' (код ASCII 0x5C), и символа 'r' или 'n' соответственно. Имя и значение каждого атрибута сообщения объединяются в строку с символом-разделителем "равно". Имя сообщения и полученные строки атрибутов объединяются в строку с разделителем CLRF, при этом строки атрибутов следуют в порядке, указанном в списке атрибутов сообщения. В случае, если в пакетном режиме запрос содержит несколько сообщений, полученные строки объединяются с разделителем CLRF.

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

Пример запроса точки 123456 на проведение операции номер:

OPERATION

id=122

checkid=122

product=4420

value=1.00QTY

account=

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

RESULT

id=122

code=2000

omsg=Заявка принята к исполнению.

cmsg=Заявка принята к исполнению.

time= 20:00:26 +0300

5.1.2.2.2. XML-формат

В случае, если значение какого-либо атрибута сообщения содержит символы '<','>' или '&' (коды ASCII 0x3C, 0x3E, 0x26) они заменяются на последовательности символов '<','&rt;' и '&' соответственно. Затем каждое значение обрамляется парным XML-тэгом с именем, соответствующим имени атрибута. Полученные строки объединяются в одну строку в порядке, указанном в описании атрибутов сообщения и обрамляются парным XML-тэгом с именем, соответствующим имени сообщения. В случае, если в пакетном режиме запрос содержит несколько сообщений, полученные строки объединяются в произвольном порядке в одну строку. При объединении строк допускается добавление произвольного количества пробельных символов в качестве разделителей. Полученная строка обрамляется парным XML-тэгом с именем "PACKAGE", и в начале полученного запроса добавляется декларация XML

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

Пример запросов на проведение операции 122 и отмену операции номер 124:

<?xml version="1.0" ?>

</OPERATION>

</package>

<?xml version="1.0" ?>

</CANCEL>

</package>

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

<?XML version="1.0">

<omsg>Заявка успешно отменена по запросу Агента.</omsg>

<cmsg>Заявка успешно отменена по запросу Агента.</cmsg>

</RESULT>

</PACKAGE>

5.1.2.2.3. Формат справочника

Справочник представляет собой набор записей, состоящих из полей. Разделителем записей служит CLRF, разделителем полей - символ табуляции.

5.1.2.3. Расширения протокола

В ответы сервера могут быть добавлены односторонним образом дополнительные HTTP-заголовки и параметры ответа сервера о состоянии операции. Все дополнительные, не описанные в данном документе параметры и заголовки должны быть проигнорированы при обработке результата.

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

Также могут быть введены дополнительные алгоритмы способа аутентификации, алгоритмы формирования ЭЦП, дополнительные форматы сообщений и кодировки, типы объектов и поля справочника. Перечисленные изменения не влияют на работоспособность приложений Агента.

5.1.2.4. Пример HTTP-запроса

POST https://dealer. *****/some_url HTTP/1.0

Content-type: text/xml; charset=Windows-1251

Content-length: 373

X-Eport-Auth: point=123; sign="6FB4FD47E73E30EF12230E2D1"; encoding="hex"

<?xml version="1.0" ?>

</OPERATION>

</package>

Наименование	Описание
Rate	Текущий курс e-port
RateUpdadeDate	Дата обновления курса
SrvListVer	Версия списка серверов
SrvList	Список URL-адресов серверов
CurSrvIndex	Порядковый номер текущего сервера
RefVer	Версия справочника (используется при обновлении справочника «Виды услуг»)
CurRate	Курс системы RUR/EYE (= RUR/USD)
LastSession	Дата/время последнего запроса к ПС
LastOperNum	Счетчик операций. Содержит порядковый номер последней операции. Используется при формировании идентификатора операции (в блоке OPERATION запроса к ПС).
RequestInt	Минимальный интервал между запросами в миллисекундах, по умолчанию 5000
MaxLength	Максимальный размер сообщения в E-Port в байтах, по умолчанию 4096
MaxDocsPerRequest	Количество одновременно обрабатываемых документов
PointID	Номер точки агента
ConnectionTimeOut	Таймаут сокета в миллисекундах