Хрестоматийное api



страница1/3
Дата08.11.2016
Размер0.63 Mb.
Просмотров282
Скачиваний0
  1   2   3
Хрестоматийное API

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

версия 1.0


  1. Требования к оформлению сообщений

Запросы к серверу должны отправляться методом POST. При этом User-Agent Header`а должен быть равным “Mobile Device”. Приложение на мобильном устройстве должно поддерживать cookies.

  1. Сервер

Все обращения должны идти к хосту http://hackaton.sberbank.ru/mobile/

На каждый запрос от клиента сервер формирует XML подобный ответ. В каждом ответе обязательно приходит статус ответа, по которому клиент может определить наличие ошибки в ответе.



    1. Статусы ошибок

Код статуса

Значение

0

Ответ полностью успешный и не содержит ни одной ошибки.

1

Ответ содержит ошибки, которые необходимо отобразить пользователю, так как они, скорее всего, вызваны его действиями, и он может их исправить. Сообщение может быть разобрано. Текст, пришедший в тегах < message> нужно показывать пользователю.

2

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

3

Текущая сессия недоступна. Необходимо повторить процесс аутентификации. Теги < message> игнорируется.

4

Сообщение содержит ошибки, однако может быть разобрано. Может придти только для групповых операций (например, Получение списка продуктов). Текст, пришедший в тегах < message> нужно показывать пользователю.

5

Доступ запрещен. Доступ к функционалу или запрашиваемым данным запрещен. Текст, пришедший в теге message, является системным.

6

Работа с приложением запрещена. В теге содержится причина запрета, которую нужно отобразить клиенту.

7

mGUID заблокирован. Приложение требуется зарегистрировать снова.

Текст, пришедший в теге игнорируется.



8

Технологический перерыв. Вход или регистрация клиента запрещены. Текст, пришедший в тегах < message> нужно показывать пользователю.



    1. Типы данных

Money

Тип для денежной единицы.




amount

string(1-32)

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

REGEXP: ^(\+|-|)(\d{1,})(\.\d{1,}|)

Пример: -109980,59

Пример: -1000.11



Да




currency

Currency

Валюта

Да

Currency

Валюта




code

string(3)

Буквенный код валюты ISO

Да




name

string(1-16)

Символ валюты. Для отображения пользователю.

Да

Page – набор полей с произвольными параметрами

fields




Массив полей с деталями платежа

Да




field




Набор параметров поля

Да







id

integer

Идентификатор поля










type

Integer

Тип поля:

1 – Однострочное поле ввода

2 – Многострочная область ввода

3 – Поле является суммой

4 – Чекбокс

5 – Выпадающий список

6 – Источник списания


Да







text

string

Значение поля (только для текстовых полей)

Нет







amount

Money

Сумма в валюте. Присутствует только если указан соответствующий тип поля

Нет







header

String

Наименование поля

Да







required

boolean

Указывает на то, что поле обязательно к заполнению










editable

boolean

Редактируемость поля










default

string

Массив ключей активных элементов по умолчанию, разделенных запятыми. Например «1, 2, 4»

Нет







source




Источник списания

Нет










type

Integer

1 – Карта

2 – вклад

3 – Цель

4 - ОМС


Да










sourceID

Integer

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

Да



  1. Описание методов

    1. Регистрация

Шаг 1. Отправка логина

Запрос: registerApp.php

Параметры:

Элемент сообщения

Тип

Комментарий

Обязательность

action

string

Константа со значением «reg»

Да

login

string

Логин клиента

Да

platform

string

Мобильная платформа. Возможны значения:

- “iOS”


- “Android”

- “WinPhone”

- “Blackberry”

- “Tizen”

- “Other”


Да

deviceName

string

Модель устройства

Да

devID

string

Уникальный идентификатор устройства

Да

Ответ:

Элемент сообщения

Тип

Комментарий

Обязательность

status

integer

Статус ответа

Да

loginCompleted

boolean

Признак завершения стадии логина

Да

mGUID

String

Уникальный идентификатор зарегистрированного приложения. Его нужно зашифровать и сохранить в приложении.




message

String

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

Нет

Шаг 2. Подтверждение регистрации СМС-паролем

Запрос: registerApp.php

Параметры:

Элемент сообщения

Тип

Комментарий

Обязательность

action

string

Константа со значением «confirm»

Да

mGUID

string

Уникальный идентификатор приложения (получен на шаге регистрации мобильного приложения)

Да

smsPassword

string

Пароль из SMS-сообщения

Да

Ответ:

Элемент сообщения

Тип

Комментарий

Обязательность

status

integer

Статус ответа

Да

loginCompleted

boolean

Признак завершения стадии логина

Да

message

String

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

Нет

Шаг 3. Установка пароля на вход

Запрос: registerApp.php

Параметры:

Элемент сообщения

Тип

Комментарий

Обязательность

action

string

Константа со значением «setCode»

Да

mGUID

string

Уникальный идентификатор приложения (получен на шаге регистрации мобильного приложения)

Да

password

string

Пароль на вход в приложения (PIN-код)

Да

Ответ:

Элемент сообщения

Тип

Комментарий

Обязательность

status

integer

Статус ответа

Да

loginCompleted

boolean

Признак завершения стадии логина

Да

message

String

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

Нет



    1. Авторизация

Запрос: login.php

Параметры:



Элемент сообщения

Тип

Комментарий

Обязательность

mGUID

string

Уникальный идентификатор приложения (получен на шаге регистрации мобильного приложения)

Да

password

string

Пароль на вход в приложения (PIN-код)

Да

Ответ:

Элемент сообщения

Тип

Комментарий

Обязательность

status

integer

Статус ответа

Да

loginCompleted

boolean

Признак завершения стадии логина

Да

message

String

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

Нет



    1. Получение списка банковских продуктов

Запрос: productList.php

Параметры:



Элемент сообщения

Тип

Комментарий

Обязательность

products

string

Массив констант, указывающих какие продукты необходимо вернуть. Возможные значения:

- cards


- accounts

- loans


- OMS

- targets



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

Нет

Ответ:

Элемент сообщения

Тип

Комментарий

Обязательность

status

integer

Статус ответа

Да

cards

Карты

Нет




card

нет




id

integer

Id карты

да

Account

Integer

Номер счета карты

Да

name

string(1-128)

Имя (алиас) карты

Да

description

string(1-32)

Описание карты (Visa Classic, MasterCard, Maestro и т.д.)

нет

number

string(1-32)

Номер карты. Маскированный номер карты, к примеру 7565 13** **** 1598

Да

isMain

boolean

Признак основной карты

Нет

type




Тип карты (дебетовая, кредитная, овердрафтная)

нет

availableLimit




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

нет

state




Статуса карты (открытая, закрытая и т.д)

Да

accounts

Счета/вклады

Нет




account

нет




id

integer

id вклада

Нет

name

String(1-128)

Название

Да

rate

string

Процентная ставка

Нет

closeDate

Date (dd.mm.yyyy)

Дата окончания

Нет

smsName

string

Алиас для sms-шаблонов

Нет

number

string(1-32)

Номер вклада

Нет

balance

Money

Баланс вклада (остаток)

нет

target

Информация о цели

Нет




name

string

Название

Да

comment

string

Комментарий

Нет

date

Date (dd.mm.yyyy)

Дата достижения

да

amount

Money

Сумма цели в рублях

Да

loans

Кредиты

Нет




loan

Нет




id

integer

Id кредита

Да

name

string(1-128)

Название кредита

Да

amount

Money

Сумма кредита

Нет

rate

string

Процентная ставка

Нет

balanceAmount

Money

Общий остаток по кредиту

Нет

nextPayAmount

Money

Рекомендованный платеж

Нет

nextPayDate

Date (dd.mm.yyyy)

Граничная дата следующего платежа

Нет

imaccounts

Обезличенные металлические счета(ОМС)

Нет




ima

Нет




id

integer

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

Да

name

string

Наименование ОМС

Да

number

string

Номер счета

Да

openDate

Date (dd.mm.yyyy)

Дата открытия ОМС

Нет

closeDate

Date (dd.mm.yyyy)

Дата закрытия ОМС

нет

balance

Money

Баланс

Нет

currency

string

Тип счёта ОМС

Нет



    1. Получение баллов «Спасибо»

Запрос без параметров: productList.php

Ответ:


Элемент сообщения

Тип

Комментарий

Обязательность

status

integer

Статус ответа

Да

balance

string

Признак завершения стадии логина

Нет

Может отсутствовать в случае ошибки





    1. История операций

Запрос: /payments/history.php

Элемент сообщения

Тип

Комментарий

Обязательность

from

Date (dd.mm.yyyy)

Дата начала построения списка операций

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

Нет

to

Date (dd.mm.yyyy)

Дата окончания построения списка операций

Нет

paginationSize

integer

Размер результирующей выборки. При отсутствии данного параметра вернутся все результаты соответствующие запросу.

Нет

paginationOffset

integer

Смещение относительно начала выборки. По умолчанию равно нулю.

Нет

Ответ:

Элемент сообщения

Тип

Комментарий

Обязательность

status

integer

Статус ответа

Да

operations




Нет




operation

Нет




id

integer

Идентификатор платежа

Да

state




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

Да

date

Date (dd.mm.yyyy)

Дата операции

Да

from

string(1-128)

Откуда

Нет

to

string(1-128)

Куда

Нет

description

string(1-128)

Описание операции

Да

operationAmount

Money

Количество средств по операции

Нет

copyable

boolean

Признак того, что данный платеж можно повторить.

Да

templatable

boolean

Признак того, что по данному платежу можно создать шаблон

Да

type

string

Тип операции

Да




servicePayment

Оплата услуг

jurPayment

Перевод организации.

payment

Перевод в другой банк частному лицу




paymentToClient

Перевод клиенту Сбербанка




Mobile

Платежи в пользу мобильных операторов




e-money

Платежи на электронные кошельки

form

string

Форма платежа.

Да



    1. Предложения банка

Запрос без параметров: /loanOffer/show.do

Ответ:


Элемент сообщения

Тип

Комментарий

Обязательность

status

integer

Статус ответа

Да

offerInfoData

Данные по предодобренным предложениям

Нет





loanOffers

Список предодобренных кредитов

Нет




loanOffer




Нет




name

string

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

Да

procantRate

string

Процентная ставка

Да

maxDuration




Максимальный период

Да

maxLimitAmount

string

Максимальная сумма

Да

currency

string

Валюта

Да

loanCardOffers

Список предодобренных кредитных карт

Нет




loanCardOffer




Нет




name

string

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

Да

maxLimitAmount

string

Максимальная сумма

Да

currency

Currency

Валюта

Да

offerType

integer

Тип предложения

Да




1

Предложение на открытие новой кредитной карты

2

Предложение на увеличение кредитного лимита

3

Предложение по изменению вида карты и лимита

newCardType

string

Тип кредитной карты. К примеру “Visa”

Нет

Примечание:

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

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


    1. Рекламные блоки

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

Запрос без параметров: advertising.php

Ответ:

Элемент сообщения

Тип

Комментарий

Обязательность

status

integer

Статус ответа

Да

banners

Список баннеров

Нет




banner




Нет




icon

string

Ссылка на иконку для баннера

Нет

text

String

Текст для баннера

Да

url

String

url для перехода по клику на баннер

Нет

time

Integer

Время показа временного баннера в секундах

Нет

type

integer

Тип баннера

Да







1

Временный баннер







2

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






    1. Анализ личных финансов. Справочник категорий

Справочник содержит как системные, так и добавленные клиентом категории.

Запрос: /category/list.php



Элемент сообщения

Тип

Комментарий

Обязательность

operation

string

Константа со значением «filter»

Да

incomeType

string

Тип категорий

Да




income

Доходные категории

outcome

Расходые категории

paginationSize

integer

Размер результирующей выборки. При отсутствии данного параметра вернутся все результаты соответствующие запросу.

Нет

paginationOffset

integer

Смещение относительно начала выборки. По умолчанию равно нулю.

Нет

Ответ:

Элемент сообщения

Тип

Комментарий

Обязательность

status

integer

Статус ответа

Да

categories

Список категорий

Нет





category

категория

Нет




id

integer

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

Да

name

string

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

Да

incomeType

string

Тип дохода.

да




income

Доходная категория

outcome

Расходная категория

canEdit

boolean

возможность редактирования/удаления категории

если false – то это системная категория и ее редактирование/удаление недоступно

Да



    1. Поделитесь с Вашими друзьями:
  1   2   3


База данных защищена авторским правом ©nethash.ru 2019
обратиться к администрации

войти | регистрация
    Главная страница


загрузить материал