Api логин сбербанк что это

Обновлено: 18.04.2024

Сервис авторизации СберБизнес ID построен на базе протокола OAuth 2.0, с использованием типа авторизации Authorization Code Flow и с дополнительными параметрами и значениями, определенными протоколом OpenID Connect. Авторизация с помощью СберБизнес ID позволяет Приложению Партнера получить информацию о клиенте банка и выполнять операции от имени клиента банка в системе СберБизнес. Доступ до информации клиента и возможность выполнения действий от его лица предоставляется только с согласия клиента.

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

Осуществлять безопасный вход с использованием двухфакторной аутентификации.

Осуществлять переход между Партнерскими приложениями, в которых реализован вход через СберБизнес ID, без повторного ввода логина и пароля.

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

Перед изучением раздела рекомендуется ознакомиться с используемой терминологией.

Процесс входа через СберБизнес ID представлен на схеме ниже.

Сценарий использования и возможности входа через СберБизнес ID:

На странице Приложения Партнера размещается кнопка «Войти по СберБизнес ID».

При нажатии на кнопку «Войти по СберБизнес ID» Приложение Партнера осуществляет перенаправления браузера пользователя на страницу авторизации СберБизнес ID. См. описание вызова в разделе Authorization code.

На странице авторизации СберБизнес ID Пользователь выполняет вход в СберБизнес ID и дает разрешение на доступ к ресурсам и сведениям Приложению Партнера (Согласие на передачу данных).

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

Приложение Партнера обращается к сервису СберБизнес ID и обменивает код авторизации на Access Token. См. описание обмена кода авторизации на токен в разделе Access Token, Refresh Token.

Используя Access Token, Приложение Партнера запрашивает информацию о клиенте. См. описание порядка получения информации о клиенте в разделе User-info.

После получения информации о клиенте Приложение Партнера создает новую учетную запись для пользователя и отображает клиенту страницу своего приложения.

Согласие на передачу данных (оферта) - это документ, который Банк запрашивает у Клиента и подтверждающий право Банка на передачу информации о Клиенте третьему лицу (Партнеру), выполнению операций третьим лицом (Партнером) от лица Клиента. Согласие (оферта) содержит информацию о том к каким данным, операциям и на какой срок предоставлен доступ Партнеру. При предоставлении Партнеру доступа к данным своих счетов клиент в явном виде указывает каждый счет, к которому предоставляет доступ.

Согласие запрашивается при обращении к сервису авторизации СберБизнес ID:

При первичном обращении пользователя к Партнерскому Приложению через сервис СберБизнес ID;

При повторном обращении, в случае если:

Истек срок действия предыдущего согласия;

Предыдущее согласие было отозвано пользователем;

Состав запрашиваемого согласия (scope) изменился относительно принятого ранее согласия и используется вторая версия авторизации /v2/oauth/authorize.

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

Если пользователь отзывает согласие, то все выданные токены (Access Token, Refresh Token) деактивируются.

Если Приложение Партнера использует устаревшую версию авторизации /v1/oauth/authorize и состав запрашиваемых разрешений в составе scope изменился, то для получения согласия от Пользователя с новыми разрешениями необходимо перейти на вторую версию авторизации /v2/oauth/authorize.

Требования к Приложению Партнера

Для обеспечения взаимодействия Приложения Партнера с сервисом СберБизнес ID:

Приложение Партнера должно выполнять проверки в соответствии с требованием спецификаций: OAuth 2.0, OpenIDConnect.

Кнопка входа в Приложение Партнера через СберБизнес ID должна отвечать требованиям дизайна пользовательского интерфейса.

Приложение Партнера должно пройти проверку службы безопасности на устойчивость к уязвимостям из перечня OWASP Top 10.

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

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

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

Взаимодействие с Сервисом осуществляется через функциональность, встроенную в автоматизированную систему Клиента (далее – АС Клиент), которая должна вызывать функции сервиса и обрабатывать результаты их работы.

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

Соблюдение приведенных ниже рекомендаций позволит Вам максимально безопасно взаимодействовать с сервисом SberBusinessAPI и свести риски работы через сеть Интернет к минимуму.

Схема взаимодействия

Взаимодействие АС Клиента с сервисом SberBusinessAPI рекомендуется осуществлять в соответствии со схемой:

При реализации схемы следует учесть следующие рекомендации:

Настройками внутреннего межсетевого экрана (Internal Firewall) доступ к серверу АС Клиента рекомендуется разрешить только для серверов и рабочих станций организации, необходимых для использования в производственном процессе:

• сервера контроллеров домена, обновлений системного и антивирусного ПО;
• АРМ администраторов сервера АС Клиента.

Подписание ЭД с использованием устройств VPN-Key-TLS/Rutoken TLS рекомендуется осуществлять в отдельном сегменте корпоративной сети.

Доступ рабочего места, предназначенного для подписания ЭД с использованием устройств VPN-Key-TLS/Rutoken TLS, к ресурсам и сервисам сети Интернет должен быть исключен.

Меры по защите от вредоносного ПО

На сервере АС Клиента необходимо:

• Использовать современное антивирусное программное обеспечение и следить за его регулярным обновлением;
• Регулярно выполнять антивирусную проверку для своевременного обнаружения вредоносных программ;
• Своевременно устанавливать обновления операционной системы серверов и АРМ администратора, рекомендуемые компанией-производителем в целях устранения выявленных уязвимостей ОС;
• Использовать дополнительное программное обеспечение, позволяющее повысить уровень защиты компьютеров – персональные межсетевые экраны, программы поиска шпионских компонент, программы защиты от «спам»- рассылок и пр.;
• Обеспечить отсутствие несанкционированно установленных программ удаленного доступа (TeamViewer, BeTwin, RAdmin и др.), программ работы с вирусоопасными ресурсами и сервисами сети Интернет, включая почтовые клиенты;
• Исключить установку, полученного из не заслуживающих доверия источников, а также нелицензионного и свободно-распространяемого ПО на сервере с системой. Обращаем Ваше внимание, что сотрудники ПАО «Сбербанк» не рассылают дистрибутивы ПО по электронной почте.

Меры, направленные на защиту от копирования ключевой и парольной информации

Client_Secret – это конфиденциальная информация. Ни при каких обстоятельствах не раскрывайте эти данные никому, включая сотрудников Банка.

В случае компрометации Client_Secret необходимо незамедлительно выполнить его блокировку в соответствии с п.4.2.3 Соглашения.

При доступе АС Клиента к функциям SberBusinessAPI хранение Client_Secret необходимо осуществлять в ключевом хранилище. Настройками безопасности ОС доступ к ключевому хранилищу рекомендуется предоставлять только для учетной записи АС.

Процедуру замены Client_Secret необходимо проводить в автоматизированном режиме средствами АС без вмешательства пользователей.

В период, когда Система не используется, необходимо отключать носители с ключами ЭП от сервера, и убирать в места хранения (сейф, и т.п.).

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

ПИН-коды доступа устройств «VPN-Key-TLS/Rutoken TLS» - это конфиденциальная информация. Ни при каких обстоятельствах не раскрывайте эти данные никому, включая сотрудников Банка.

Меры, направленные на защиту от выполнения несанкционированных списаний

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

В случае неожиданного выхода из строя серверов с модулем подписания с использованием устройств VPN-Key-TLS/Rutoken TLS необходимо прекратить эксплуатацию данных серверов, отключив их от всех видов сетей, включая локальную корпоративную сеть, срочно запросить выписку по счету непосредственно в Банке. При обнаружении несанкционированных платежных операций написать заявление в Банк, а также обратиться с соответствующим заявлением в правоохранительные органы. Работоспособность скомпрометированных серверов не восстанавливать до проведения технической экспертизы. Подписание электронных документов осуществлять с использованием устройств VPN-Key-TLS/Rutoken TLS на других серверах. При этом обязательно произвести смену ключей ЭП.

Меры по поддержанию уровня информационной безопасности

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

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

SberBusinessAPI включает в себя:

Сервис авторизации СберБизнес ID - сервис, позволяющий идентифицировать и аутентифицировать клиента c помощью учетной записи СберБизнес, предоставлять права на получение информации о клиенте и выполнение операций от лица данного клиента в ресурсной системе.

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

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

Терминология

Пользователь партнера - пользователь системы СберБизнес, организации, заключившей договор с банком на использование SberBusiness API.

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

Client ID - уникальный идентификатор приложения партнера.

Client secret - пароль приложения партнера.

Scope - набор атрибутов (claim) и операций по которым происходит обмен данными.

Access Token - ключ доступа для обмена данными с банком, предоставляемый Сервисом авторизации СберБизнес ID.

Варианты интеграции

SberBusinessAPI поддерживает три основных сценария работы с внешними приложениями, системами и сервисами клиентов и партнеров:

Прямая Интеграция (Host-2-Host) - обмен информацией между одной организацией партнера и системами банка.

Интеграция для холдингов (Holding) - обмен информацией между группой компаний партнера и системами банка.

Интеграция для партнеров (B2B Saas) - уникальные платежные решения, позволяющие партнерам автоматизировать и упростить процессы предоставления своих сервисов для их клиентов.

Как подключить

• ИНН;
• Название организации;
• Сайт организации;
• Контакты для обратной связи (или контакты Вашего клиентского менеджера).

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

В ответ на направленную заявку будет передана вся необходимая для подключения к SberBusinessAPI информация, в том числе:

Информация о возможностях SberBusinessAPI;

Помощь в выборе подходящего вида интеграции (H2H, Holding, B2B SaaS);

Дальнейшие шаги, которые необходимо выполнить для подключения и получения доступа в Личный кабинет SberBusinessAPI;

Информация о технической поддержке;

Данные для доступа к тестовой среде.

В дальнейшем в рамках подключения потребуется:

Установить цепочку доверенных TLS сертификатов.

Реализовать взаимодействие со СберБизнес ID для получения Access Token.

При необходимости настроить работу с криптографией и ЭП.

Провести тестирование интеграции совместно со специалистами Банка.

Зарегистрировать промышленный TLS-сертификат, сформированный по инструкции или в личном кабинете.

Начало работы с сервисом

Интеграция Host-2-Host

Подключите услугу SberBusinessAPI в Интернет-банке СберБизнес (СББОЛ) по инструкции. Для тестирования подготовьте TLS или скачайте TLS, затем установите готовый тестовый сертификат (пароль для установки testtest) и цепочку тестовых TLS-сертификатов, после чего вы получите доступ к тестовому полигону.

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

Код авторизации SMS 11111 для всех операций.

Далее по инструкции перейдите в раздел «Все продукты и услуги», выберите SberBusinessAPI.

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

Интеграция Holding и B2B Saas

Для начала работы с сервисом:

• Сформируйте web-ссылку и получите код авторизации.
• После получения кода авторизации получите access и refresh токены.
• Обновите параметр client_secret, используя ресурс /v1/change-client-secret.

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

Для отладки выполнения данных операций вы можете использовать тестовый swagger.

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

Определяем термины

Во-первых, давайте определимся с некоторыми ключевыми терминами:

• Аутентификация: подтверждение правильности личности
• Авторизация: разрешение определенного действия

API может аутентифицировать, но не разрешит делать определенный запрос.

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

Последствия нехватки безопасности API

Почему даже API-интерфейсы нуждаются в аутентификации? Для API, которые предназначены только для чтения, иногда пользователям не нужны ключи. Но большинство коммерческих API требуют авторизации в виде ключей API или других методов. Если нет никакой защиты API, пользователи могут совершать неограниченное количество запросов API без какой-либо регистрации. Разрешение неограниченных запросов усложнит модель дохода для вашего API.

Вдобавок, без аутентификации не было бы простого способа связать запросы с конкретными данными пользователя. И не было бы способа защиты от запросов от злонамеренных пользователей, которые могут удалить данные другого пользователя (например, путем удаления запросов DELETE для учетной записи другого пользователя).

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

В целом, аутентификация и авторизация с помощью API служат следующим целям:

Разные виды авторизации

Существует несколько методов авторизации. Ниже рассмотрим несколько вариантов авторизации, которые встречаются чаще всего:

API ключ

Большинство API требуют авторизации ключом API, чтобы использовать API. Ключ API представляет собой длинную строку, которую обычно включают либо в URL запроса, либо в заголовок запроса. Ключ API в основном служит способом идентификации лица, выполняющего запрос API (аутентифицируя для использования API). Ключ API также может быть связан с конкретным приложением, которое регистрируется.

Ключи APK используют строку в свойстве заголовка для авторизации запросов

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

Basic Auth

Другой тип авторизации называется Basic Auth. С помощью этого метода отправитель помещает пару имя пользователя:пароль в заголовок запроса. Имя пользователя и пароль кодируются с помощью Base64, который представляет собой метод кодирования, который преобразует имя пользователя и пароль в набор из 64 символов для обеспечения безопасной передачи. Вот пример Basic Auth в заголовке запроса:

В Postman можно настроить базовую авторизацию, щелкнув вкладку Authorization, выбрав Basic Auth в раскрывающемся списке и введя имя пользователя и пароль справа от двоеточия в каждой строке. На вкладке Заголовки будет показана пара ключ-значение, выглядящая следующим образом:

Postman обрабатывает кодировку Base64 автоматически, при вводе имени пользователя и пароля с выбранным Basic Auth.

Сервер API (получатель), получая запрос, принимает те же системные свойства (отметка времени запроса плюс идентификатор учетной записи) и использует секретный ключ (который известен только запрашивающей стороне и серверу API) и SHA для генерации одной и той же строки. Если строка соответствует подписи в заголовке запроса, запрос принимается. Если строки не совпадают, запрос отклоняется.

Вот диаграмма, отображающая процесс авторизации HMAC:

Важным моментом является то, что секретный ключ (критический для восстановления хэша) известен только отправителю и получателю. Секретный ключ не включается в запрос. Безопасность HMAC используется, когда нужно убедиться, что запрос является подлинным и не может быть подделан.

OAuth 2.0

Одним из популярных методов аутентификации и авторизации пользователей является OAuth 2.0. Такой подход опирается на сервер аутентификации для связи с сервером API для предоставления доступа. Понять, что используется метод OAuth 2.0, можно когда предлагается войти в систему при помощи сторонних сервисов, как Twitter, Google или Facebook.

окно входа в систему, использующую Oauth2.0

Существует несколько разновидностей OAuth, а именно «one-legged OAuth» и «three-legged OAuth». One-legged OAuth используется, когда нет конфиденциальных данных для защиты. Например, в том случае, если просто получаем общую информацию только для чтения.

Three-legged OAuth используется, когда нужно защитить конфиденциальные данные. В этом сценарии взаимодействуют три группы:

• сервер аутентификации;
• сервер API;
• пользователь или приложение.

Вот базовый процесс Oauth2.0:

Сначала пользовательское приложение отправляет ключ приложения и секретные данные на страницу входа в систему на сервере аутентификации. Если аутентификация пройдена, сервер аутентификации возвращает пользователю токен доступа (авторизации).

Токен доступа (авторизации) упакован в параметр запроса в перенаправлении ответа (302) на запрос. Перенаправление направляет запрос пользователя обратно на сервер ресурсов (сервер API).

Затем пользователь отправляет запрос на сервер ресурсов (сервер API). Токен доступа (авторизации) добавляется в заголовок запроса API со словом Bearer , за которым следует строка токена. Сервер API проверяет токен доступа (авторизации) в запросе пользователя и решает, аутентифицировать ли пользователя.

Токены доступа (авторизации) не только обеспечивают аутентификацию для запрашивающей стороны, но и определяют права пользователя на использование API. Кроме того, токены доступа (авторизации) обычно истекают через некоторое время и требуют от пользователя повторного входа в систему. Для получения дополнительной информации об OAuth 2.0 можно посмотреть ресурсы:

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

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

Тем не менее нужно объяснить необходимую информацию:

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

Поскольку раздел API ключей важен, и нужен разработчикам до того, как они начнут использовать API, этот раздел должен быть в начале руководства.

Образцы разделов авторизации

Ниже приведены несколько примеров разделов авторизации в документации API.

SendGrid

API ключ SendGrid

SendGrid предлагает подробное объяснение ключей API, начиная с основ, поясняя: «Что такое ключи API?». Контекстно раздел ключей API появляется вместе с другими разделами по управлению учетными записями.

Twitter

авторизация Twitter

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

Amazon Web Services

авторизация Amazon

Amazon использует HMAC. Процесс достаточно сложный, чтобы включить полноценную диаграмму, показать шаги, которые должны выполнить пользователи.

Dropbox

Авторизация в Dropbox

Как и Twitter, Dropbox также использует OAuth 2.0. Их документация включает в себя не одну, а две диаграммы и подробное объяснение процесса.

👨‍💻 Практическое занятие: Авторизация

В своем найденном опен-сорс проекте найдем информацию об авторизации для запросов к API. Ответьте на следующие вопросы:

Много кто пользуется приложением Сбербанк Онлайн, но немногие знают, как оно работает. Настало время приоткрыть завесу тайны – в этой статье мы расскажем о некоторых подходах, которые используем в разработке.


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

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

О чем пойдет речь

Мы расскажем, как в мобильном и веб приложениях Сбербанк Онлайн работают платежные сценарии, а именно про API между приложениями и сервер-сайдом.

Почему фокус на API? Все просто – это фактически единственный мостик, который соединяет клиентские приложения и бэкенд. Если проект небольшой, то мы можем легко менять API и переписывать под него приложения. Но если проект масштабный (такой, как у нас), то даже небольшие изменения API требуют вовлечения большого количества ресурсов как на фронте, так и на бэкенде, и становятся очень дорогими. И второй момент – чем раньше мы зафиксировали API, тем раньше фронтальные и бэковые команды могут начинать разработку. Им просто надо будет сойтись в одну точку.

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

Специфика и мотивация

Приложения большие. Когда мы писали эту статью, приложение Сбербанк Онлайн на Android занимало около 800 000 строк кода, на iOS – 500 000 строк кода. И это только наш код, без подключаемых библиотек.

Обратная совместимость и много пользователей. MAU – 32 млн активных пользователей мобильного приложения. И если мы не сделаем обратную совместимость на уровне API, очень многим пользователям по всей стране придется качать приложения заново. Это очень нехорошо. Кстати, это одна из причин, почему у нас так много кода.

Сбербанк Онлайн разрабатывает много небольших команд. Вы, наверное, слышали про Agile в Сбербанке. Это правда, мы работаем по Agile в командах по 9 человек.

Приложение банковское: несмотря на то, что функциональность банковских приложений растет очень быстро, основное, что происходит в дистанционном банкинге – это последовательный процесс (обработка клиентских заявок). Такие процессы мы называем workflow. Заявки эти могут быть разного рода и обрабатываются они огромным количеством взаимосвязанных сервисов в периметре банка.

Два типа команд. Есть платформенные – они отвечают за разработку ядра приложения. И есть фичёвые команды – они создают прикладной функционал для конечных пользователей, используя архитектуру и инструменты, которые даёт платформа.

Омниканальность. Крайне важная история. Чтобы не разрабатывать бэк несколько раз – отдельно для мобильных приложений и отдельно, например, для веб-версии и банкоматов, нужно сделать так, чтобы API был максимально схожим для всех каналов (как минимум должна быть одинаковой структура ответа).

Мобильное приложение

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

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

Лучший клиентский опыт: мы выбрали для себя основную технологию разработки мобильных приложений – разработка на нативных языках. Только так можно получить лучший клиентский опыт.

Если обобщить все эти требования – приложения должны разрабатываться на нативных языках, иметь повторно используемые компоненты внутри себя, но при этом вся бизнес-логика должна управляться со стороны сервера.

Как делать не стали

После того как мы обозначили граничные условия, расскажем, какие существующие решения мы анализировали.

Программирование на JSON

Логику проще описать императивно кодом, чем выдумывать (и изучать!) новый декларативный язык, который всегда будет ограничен сильнее, чем родной язык платформы. Кроме этого, надо предусмотреть песочницу, обработку ошибок, какой-то этап пилотирования – псевдокод должен постепенно распространяться на пользовательские устройства и при любых сбоях откатываться назад. Всё это усложняет разработку без ощутимых преимуществ.

Не используем описание стилей компонентов, поскольку они могут разниться от форм-фактора, платформы и даже режима работы (портретная/ландшафтная ориентация, responsive в web). Декларации стилей в конечной реализации всегда будут качественнее, ближе к реальности и корректнее работать с краевыми случаями. Кроме этого, бывает, что компоненты со схожей логикой принципиально по-разному работают на разных устройствах: например, ввод номера телефона – с телефонной книгой на мобильном устройстве и без неё в вебе.

Фиксация модели данных в интерфейсе приложения

Этот способ еще называется «прибить гвоздями». Смысл в том, что интерфейс приложения строится на уникальных идентификаторах объектов, которые передаются с сервера. В такой схеме любые изменения на стороне сервера приводят к переработкам клиентской части. Невозможно повторно использовать код. Сложно поддерживать.
Единственное, почему стоит выбирать такой способ на своем проекте, – уверенность на 99%, что API не будет меняться. Ну или если проект совсем небольшой и проектировать API дороже, чем быстро переделать пользовательский интерфейс под изменения в API.

Добавляем к каждому объекту признак стиля. UI приложений строим на основании этого признака. Стилей ограниченное число, поэтому появляется возможность строить интерфейс динамически. Но с увеличением функциональности UI приходится увеличивать количество стилей.
В этом варианте становится возможно управлять отображением отдельных элементов, но повышается сложность реализации связанности между разными полями. И главное – с ростом вариативности UI у вас будет постоянная необходимость расширять протокол API.

У JSON API детально описаны рекомендации по структурированию данных и описанию взаимосвязей между ними, но нет ничего, что могло бы описывать представление. Наша задача затрагивает в том числе визуальное расширение – добавление новых полей ввода, так что такой вариант нам не подходит.

Web Components / React Components API

Концепция веб-компонентов, которая в том числе значительно повлияла на API компонентов React, нам подходит уже намного лучше: с одной стороны, у нас есть контроль за отображением, с другой стороны – есть возможность привязывать данные к элементам UI.
К сожалению, всё слишком сильно завязано на HTML + CSS + JS. Напрямую не используешь, но запомним – потом пригодится.

Как решили делать

UI-контейнеры

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

Мы выбрали именно этот подход. Сначала мы опишем протокол API, а потом – как устроены фрэймворки внутри мобильных и веб-приложений.

Чтобы было понятнее, рассмотрим API на примере простого процесса, например, перевод между своими счетами. Как добираемся до точки входа, не рассматриваем – это не процесс и для этого есть свой API (о нем мы тоже как-нибудь расскажем). Итого, процесс у нас начинается с точки входа:

Транспорт данных

Для начала договоримся об основных принципах – как передаём данные. За основу возьмём самый простой подход – пары «ключ-значение». Ключом пусть будет строка из букв латинского алфавита, значение – тоже строки, но уже произвольные.

Формы для заполнения бывают сложные, с вложенными элементами и подразделами, значит, надо допускать вложенность. Можно именовать ключи в формате camelCase, но они могут быть плохо читаемым (например, в логах) или даже «портиться» в системах, нечувствительных к регистру. Нужно ввести разделитель.

Самый очевидный разделитель – точка – во многих языках используется для доступа к свойствам объекта. При неаккуратном использовании ключи с таким разделителем будут создавать словари (или объекты), в которых возможны коллизии. Например, “foo.bar” = “foobar” и “foo.bar.baz” = “foobarbaz” в javascript может повлечь перезапись свойства “bar” объекта “foo” со строки на объект. В конце концов, договорились на двоеточии: с одной стороны, явное визуальное разделение и семантическое отражение вложенности, с другой стороны, достаточно безопасно для всех используемых языков.

Что делать с повторяемыми полями? Вводим дополнительное правило: между парой разделителей могут быть либо латинские буквы, либо цифры. Получаются конструкции вида: children:5:name:first.

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

Решение: значение – либо строка, либо список строк. Так решение выглядит типовым, но в то же время накладные расходы оказываются незначительными.

Шаг – это состояние процесса. Первый шаг у нас – выбор счета списания и счета зачисления и ввод суммы.

UI на этой картинке не видно, потому что шаг – это про серверную логику, а не про презентационную. Есть два подхода к работе с шагами: можно передавать с сервера только разницу (нарастающий итог в клиентском приложении) или каждый шаг целиком (нарастающий итог на сервере).

Анализ требований показал, что в ходе процесса экран может формироваться по-разному на разных шагах (ветвление процессов), поэтому вместо добавления управляющих команд для преобразования уже переданных сущностей проще каждый шаг передавать полностью таким, каким его должен увидеть пользователь.

Из дополнительных плюсов: при возврате к редактированию не нужно проигрывать весь сценарий или передавать дополнительный параметр “отдай всё”. При старте шага клиентское приложение сразу же получает всю нужную информацию для построения экранов.

Экраны

Экран – это разделение процесса на этапы в клиентском приложении. Как правило, экраны используются, чтобы форма была проще для восприятия. В нашем случае всё просто: один шаг – один экран.

Для экранов мы ввели два правила:

1. переход между экранами может быть только линейным, без ветвлений;
2. переход между экранами не требует взаимодействий с бэкэндом.

UI компоненты (блоки)

UI компонент – независимый компонент, который реализует клиентскую логику и наполняет документ данными. По сути, это ассоциация между управляющей командой в протоколе и куском кода и разметки в приложении. На первом экране три компонента:

1. Счет списания
2. Тот же компонент для счета зачисления
3. Сумма перевода

Поля – это атомарные компоненты, которые выступают транспортом для отдельных элементов данных и обрабатывают пользовательский ввод в случае деградации блока. Типов полей ограниченное число и все они поддерживаются на уровне фрэймворка: text, checkbox, select, multiselect.

Это значит, что любая версия приложения может отрисовать интерфейс, опираясь только на типы полей.

Поля в UI-компонентах из нашего примера:

1. Поле со ссылкой на справочник в счете списания и счете зачисления. Почему ссылка на статический справочник? Потому что счет мы выбираем из списка карт (счетов), без лишнего обращения к серверу.

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

Таким образом, формат для полей имеет такую структуру:

События

Так как приложения ничего не знают о процессе, логично, чтобы события (кнопки, которые видит пользователь) тоже были частью ответа от сервера.

События мы разделили на два типа.

1) Основные – они есть почти на каждом экране в привычных местах для пользователя. Как пример, это события «назад» и «продолжить». Первое осуществляет переход на шаг назад, а второе собирает заполненные данные с клиентской формы и отправляет их на сервер вместе с командой «Перейти на следующий шаг».

2) И специальные – для нестандартных действий, которые мы заранее спрогнозировать не можем, да и смысла закладывать их в часть движка нет, так как они редко используются.
В нашем случае на экране только основные события – «продолжить» и «назад». Они реализованы на уровне платформы.

У всех событий есть ряд атрибутов, такие как сам тип события, title и признак видимости. И никакого UI на сервер-сайде вроде размера кнопки, положения и цвета. Эта логика реализуется на фронте.

Справочники

Со справочниками все стандартно. Если он небольшой, то мы его присылаем полностью в ответе от сервера и называем статическим. Сделано это для того, чтобы минимизировать количество запросов к сервер-сайду и время отклика на действие пользователя в интерфейсе. Чтобы его отобразить в форме на экране, добавляем поле с типом – selectList, одно из свойств которого – ссылка на статический справочник.

Если справочник большой, то он реализуется в виде отдельного rest-сервиса. В интерфейсе это выглядит как текстовое поле, по мере заполнения которого возвращается список возможных вариантов из справочника.

Ошибки валидации на клиенте и сервере

Примерно так выглядит структура ответа:

Фрэймворки

Теперь немного о том, как с этим протоколом работают фрэймворки внутри приложений. Условно фрэймворки можно разделить на две основные части: workflow engine + обработчик UI-контейнеров. Такое разделение вызвано не только архитектурой приложений, но и организационной структурой. Движок разрабатывают и поддерживают платформенные команды, а UI-контейнеры фактически являются точками расширения и их программируют фичёвые команды. Таким образом, большему количеству команд не нужно вносить изменения в ядро.

Workflow engine

Движок внутри приложений (веб и мобильного) знает, что начался процесс работы с документом и что согласно протоколу ему придёт ряд атрибутов: шаги, экраны, UI-контейнеры и типы полей. На этих данных рисуется базовый интерфейс – нижнее и верхнее меню, основные кнопки, UI на простых типах полей, если они используются.

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

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

Как работают UI-контейнеры?

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

Поэтому нужны были точки расширения. Этими точками расширения стали UI-компоненты – это нативная реализация кода в самих приложениях, который идентифицируется движком по названию. По сути, это группировка поля/нескольких полей в логический блок, который может отображать кастомный UI. При этом модель данных протокола используются только для транспорта данных на бэкенд, весь UX и UI реализуется на стороне приложения.

Два режима работы фрэймворка

Когда движок парсит модель данных, он сравнивает список имен UI-контейнеров с реестром, который хранится внутри приложения. Если приложение не находит имени компоненты, то интерфейс строится на простых типах полей. Процесс будет полностью рабочим, но на стандартных UI-элементах.

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

И тут мы получаем одно из основных преимуществ движка – доставить пользователю изменения без обновления приложения. В сборке есть маппинг имен компонентов на классы, в которых запрограммирован UI этих компонентов и пользовательский интерфейс строится на нем.

Каких правил мы стараемся придерживаться при работе с UI-компонентами:

• Поддерживать работу функционала в режиме списка простых типов полей. У любого прикладного проекта есть соблазн превратить динамический протокол в статический. Поэтому мы всех просим сначала разработать функционал на типовом UI-контейнере, а потом обогащать UX/UI добавлением кастомных контейнеров на этой модели данных. Это не только позволит в будущем обновлять процессы на старых сборках, но и автоматически поддерживает логическую целостность API.
• Не менять модель данных (JSON) для UI-контейнера, если он уже готов (проходит финальное тестирование или уже в продакшене). Так как логика на PL жестко связана с моделью данных, её изменение сломает функционал на версиях мобильного приложения, которые не обновляются. Тем не менее, модель можно расширять при условии сохранения обратной совместимости.
• Называть свой UI-компонент системным именем. Так как имя UI-компонента – обязательный атрибут протокола и должен быть минимум один на каждом экране, мы ввели специальное системное имя, которые реализует простой список полей.
• Не реализовывать бизнес-логику на UI-компонентах. Логику необходимо реализовывать на сервере, почему – писали выше.

Coming soon…

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

Пишите в комментариях, что непонятно, что интересно – постараемся писать меньше, но чаще и в цель. У нас много интересных вызовов, и поэтому много материала.

Читайте также:

  
• Кому принадлежит банк дом рф
  
• Управление экономической безопасностью коммерческого банка в условиях финансового кризиса
  
• Что такое банковская система какие элементы ее составляют и как они структурируются по уровням
  
• Как позвонить за счет собеседника тинькофф
  
• С каким банком у контур бухгалтерии нет интеграции