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

Протокол обмена со службой обработки запросов
Загрузка таблиц базы данных
Формат запроса
Для загрузки таблиц базы данных выполняется http-запрос типа GET, содержащий строку
параметров в следующем виде:
name=имя_таблицы&date1=DDMMYY&date2=DDMMYY
, где:
 date1, date2 – даты начала и окончания периода в формате ДДММГГ. Период используется
сервером при возврате документов или хранилищ, в которых присутствует реквизит
"ДатаВремя";
 name - список запрашиваемых объектов. Значение параметра
o может состоять только из имени запрашиваемого объекта, например: name=Клиенты.
Будут возвращены справочники, документы или хранилища с данным именем;
o может содержать имя и тип запрашиваемого объекта, разделенные знаком ";",
например:
name=Клиенты;1
o
Тип объекта может принимать следующие значения:
 "1", "справочник", "datadirectory" - для справочников;
 "2", "документ", "document" - для документов;
 "3", "хранилище", "storage" - для хранилища.
Будут возвращены записи объекта соответствующего типа, если он присутствует в
конфигурации;
может содержать несколько имен запрашиваемых объектов, с указанием типа или без,
разделенных знаком ";", например:
name=Клиенты;1;СписаниеДенегСоСчета;ОплатаУслуг;3;БанковскиеТра
нзакции
Ответ будет содержать данные всех найденных объектов.
Формат ответа
В ответе на запрос сервер возвращает данные в формате XML 1.0, используемая кодировка
Windows-1251. Ответ сервера имеет следующую структуру:
<?xml version="1.0" encoding="windows-1251"?>
<PayserviceData>
<Таблица1>
<Record>
<Поле1>Значение</Поле1>
<Поле2>Значение</Поле2>
...
<ПолеN>Значение</ПолеN>
</Record>
<Record> ... </Record>
...
<Record> ... </Record>
</Таблица1>
<Таблица2> ... </Таблица2>
...
<ТаблицаN> ... </ТаблицаN>
</PayserviceData>
Данные запрашиваемых объектов содержатся в тегах "Таблица1" ... "ТаблицаN" в виде записей, имя
тега соответствует имени объекта1 (за исключением документов). Если указанный в запросе объект не был
найден, соответствующего тега в ответе не будет. Каждая запись содержит значения реквизитов объекта в
дочерних тегах "Поле1" ... "ПолеN"2.
Данные каждого типа документов передаются в двух частях - значения реквизитов и значения
табличной части документа, т.е., для каждого типа документов в ответе будет два тэга типа "Таблица":
1. Имя_документа_Header, содержащий значения реквизитов;
2. Имя_документа_Table, содержащий значения табличных частей.
Взаимодействие с сервером авторизации
Взаимодействие клиента с сервером авторизации осуществляется через протокол http. Запросы
доставляются методом POST. Тело запроса (и ответ сервера) представляет собой XML-документ заданного
формата.
В настоящий момент используются четыре вида запроса:
1.
2.
3.
4.
5.
6.
Начисление денег на счет клиента. Запрос этого типа используется для (пред-)оплаты
различного вида услуг - сотовой связи, доступа в интернет, коммунальных услуг и т.п. При
успешном выполнении запроса ответ сервера может содержать строки чека.
Оплата чека. Запрос используется для оплаты покупки (или части покупки) картой
международной или внутренней платежной системы. Формат запроса предоставляет
возможность выполнения аутентификации клиента по подписи или PIN-коду. Ответ сервера
помимо стандартных значений результата выполнения операции может содержать строки чека и
дополнительную информацию при отказе в авторизации.
Отмена оплаты (возврат покупки). Отмена уже проведенной транзакции оплаты. Может
использоваться при возврате покупки или при отмене чека, часть суммы которого уже оплачена
платежной картой.
Получение информации о карте. Запрос используется только для внутренних карт. В ответе
содержится баланс (только для платежных карт) и список скидок с текущими процентами. Если
в запросе не указан номер карты и точка приема карт, то возвращаются все скидки.
Обновление накопленной суммы клиента. Запрос используется только для внутренних карт.
Выполняется для авторизации и обновления накопленных сумм по дисконтной карте. Формат
запроса предоставляет возможность выполнения аутентификации клиента по подписи или PINкоду. Ответ сервера помимо стандартных значений результата выполнения операции может
содержать строки чека и дополнительную информацию при отказе в авторизации.
Отмена обновления накопленной суммы клиента. Отмена уже проведенной транзакции
обновления накопленной суммы. Может использоваться при возврате покупки, совершенной со
скидкой, для уменьшения накопленных сумм по дисконтной карте.
Структура запроса для сервера авторизации
<?xml version="1.0" encoding="windows-1251" ?>
<request type="тип запроса" account="счет">
<параметр>значение</параметр>
<параметр>значение</параметр>
...
<параметр>значение</параметр>
</request>
Запрос к серверу авторизации содержит обязательные и опциональные параметры. Обязательные
параметры передаются в атрибутах тега "request", их набор постоянен для всех запросов. Опциональные
параметры передаются в дочерних тегах, их набор определятся типом запроса.
Обязательные параметры запроса:
1
2
Если имя объекта содержит пробелы, они будут заменены символом "_".
Если имя реквизита содержит пробелы, они будут заменены символом "_".


type – тип запроса, соответствует типу транзакции в хранилище банковских транзакций. Может
принимать следующие значения:
o "charging" – начисление денег на счет (тип транзакции 0)
o "payment" – оплата (тип транзакции 1)
o "cancel_payment" – отмена оплаты (тип транзакции 2)
o "info" – информация по карте - только для карт ВПС (тип транзакции 3)
o "update_storage" – обновление накопленной суммы клиента (тип транзакции 4)
o "cancel_update" – отмена обновления накопленной суммы клиента (тип транзакции 5)
account – счет (номер телефона, контракт, PAN карты и т.п.). При запросе типа "info" может
быть пустым или отсутствовать.
Опциональные параметры запроса:
 pointId – идентификатор точки приема или магазина (строка);
 posId – номер кассы (число);
 amount – вносимая сумма (в МДЕ). Сумма должна включать процент комиссии (если он есть);
 advInfo – дополнительная информация при использовании платежной карты (строка);
 receiptId – уникальный для терминала идентификатор чека (строка);
 cardId – идентификатор типа карты либо идентификатор оператора (строка до 7-ми символов).
Если отсутствует в запросе, то используется внутренняя платежная система;
 tapeWidth – ширина чековой ленты в символах (число). Если присутствует в запросе, то в ответе
возвращаются строки чека;
 PIN – пин-блок (строка). Использование в запросе определяется типом авторизации для
текущей карты;
 originalReceiptId - идентификатор отменяемого чека (строка);
 ownerId – идентификатор юр. лица, которому перечисляются деньги при оплате банковской
картой (строка).
Суммарная длина pointId, posId и receiptId не должна превышать 50 символов.
Использование опциональных параметров в различных видах запросов:
Типы запросов
charging
payment
cancel_payment
info
update_storage
cancel_update
pointId
I
M
M
O
M
M
posId
M
M
M
I
M
M
amount
M
M
M
I
M
M
advInfo
I
O
O
I
I
I
receiptId
M
M
M
I
M
M
Параметры
cardId tapeWidth
M
O
O
O
O
O
I
I
I
I
I
I
PIN
I
O
I
I
O
I
originalReceiptId
I
I
M
I
I
M
ownerId
I
O
O
I
I
I
Обозначения:
 M – параметр должен обязательно присутствовать в запросе;
 O – параметр может отсутствовать при определенных условиях;
 I – параметр не должен присутствовать в запросе. Даже если параметр присутствует, он будет
проигнорирован сервером.
Структура ответа сервера авторизации
<?xml version="1.0" encoding="windows-1251" ?>
<response errorCode="код ошибки" statusCode="статус запроса">
<параметр>значение</параметр>
<параметр>значение</параметр>
...
<discount attribute="атрибут скидки">процент скидки</discount>
</response>
Ответ сервера авторизации аналогично запросу содержит обязательные и опциональные параметры.
Обязательные параметры передаются в атрибутах тега "response", опциональные - в дочерних тегах, их
набор определятся типом выполненного запроса.
Обязательные параметры ответа:
 errorCode – код ошибки сервера авторизации. При отсутствии ошибки содержит значение "0";

statusCode – код статуса, полученный от процессинга. При удачной обработке запроса
процессингом всегда содержит "0".
Опциональные параметры ответа:
 errorMessage – расшифровка кода ошибки сервера авторизации;
 statusMessage – расшифровка кода статуса процессинга. В большинстве случаев содержит
сообщение, полученное от процессингового центра;
 balance – баланс платежной карты в МДЕ. Возвращается при успешной обработке запроса
"Информация по карте";
 credit – кредитный лимит платежной карты в МДЕ. Возвращается при успешной обработке
запроса "Информация по карте";
 discount – скидка по карте3. Возвращается при успешной обработке запроса "Информация по
карте". Содержит информацию о скидке, применимой к данной карте в виде
<discount name="название скидки" attribute="атрибут скидки">процент скидки</discount>
Процент скидки может быть отрицательным, в таком случае следует считать это наценкой;
 client – ФИО клиента-владельца карты. Возвращается при успешной обработке запроса
"Информация по карте";
 storageAmount – сумма накоплений клиента дисконтной системы в МДЕ. Возвращается при
успешной обработке запроса "Информация по карте";
 declineType – тип отказа в авторизации. Возвращается при выполнении запросов "Оплата" или
"Отмена оплаты" в случае отказа в авторизации. Может принимать следующие значения:
o "None" – нет отказа;
o "Declined" - отказ без изъятия карты;
o "Pickup" - отказ с изъятием карты.
 receiptLine – строка чека4. Возвращается при наличии параметра "tapeWidth" в запросе.
Содержит одну строку сформированного сервером чека.
Использование запроса «Получение информации о карте»
Как было сказано выше, запрос этого типа может использоваться только для внутренних карт.
Информация, возвращаемая в ответе на запрос, содержит различные наборы данных в зависимости от
комбинации переданных в запросе параметров:
 Точка приема карт (опциональный параметр запроса pointId);
 Номер карты (обязательный параметр запроса account5).
Полное описание ответов платежно-дисконтного сервера в различных ситуациях на запрос типа info
представлено ниже.
Запрос по номеру карты и точке приема карт (содержит account и pointId)
Ответ на запрос выглядит следующим образом:
 Параметр client содержит Ф.И.О. клиента;
 Параметр balance содержит значение баланса карты;
 Параметр credit содержит значение кредитного лимита карты;
 Если карта является дисконтной (для нее указана группа скидок), то:
o если группа скидок содержит фиксированную скидку, то параметр discount содержит
информацию об этой скидке, параметр storageAmount содержит суммарное накопление
по этой карте;
o иначе, если группа скидок содержит списки условий для указанной точки, то параметр
discount содержит информацию о скидке, рассчитанной из этих условий, параметр
storageAmount содержит накопление по этой карте в указанной точке;
o иначе, если группа скидок содержит список условий, общий для всех точек, то
параметр discount содержит информацию о скидке, рассчитанной из этих условий,
параметр storageAmount содержит суммарное накопление по этой карте;
o иначе, (группа скидок не содержит списка условий для указанной точки и не содержит
списка условий, общего для всех точек), параметр storageAmount содержит 0,
параметры discount отсутствуют в ответе.
Общий запрос по номеру карты (содержит только account)
Ответ может содержать несколько тегов с таким именем либо не содержать их вообще.
Ответ может содержать несколько тегов с таким именем либо не содержать их вообще.
5
В этом типе запроса обязательный параметр account может не передаваться.
3
4
Ответ на запрос выглядит следующим образом:
 Параметр client содержит Ф.И.О. клиента;
 Параметр balance содержит значение баланса карты;
 Параметр credit содержит значение кредитного лимита карты;
 Если карта является дисконтной (для нее указана группа скидок), то:
o параметр storageAmount содержит суммарное накопление по этой карте;
o если группа скидок содержит фиксированную скидку, то параметр discount содержит
информацию об этой скидке;
o иначе, список параметров discount содержит информацию о скидках, рассчитанных для
всех списков условий этой группы скидок.
Общий запрос по точке приема карт (содержит только pointId)
Ответ на запрос выглядит следующим образом:
 Параметр client пустой;
 Параметр balance содержит 0;
 Параметр credit содержит 0;
 Список параметров discount содержит информацию обо всех скидках, которые могут
применяться в указанной точке:
o фиксированные скидки;
o скидки, содержащиеся в списках условий, общих для всех точек;
o скидки, содержащиеся в списках условий, действующих только в указанной точке;
Общий запрос по скидкам (не содержит параметров)
Ответ на запрос выглядит следующим образом:
 Параметр client пустой;
 Параметр balance содержит 0;
 Параметр credit содержит 0;
 Параметр storageAmount содержит 0;
 Список параметров discount содержит информацию обо всех скидках, существующих в
дисконтной системе.