Настройки сервиса вызова API
В данном разделе указаны доработки, которые необходимо выполнить на стороне вашего сервиса вызова API. Выполните их после того, как закончите подключение API на Sber API Registry (см. раздел Создать подписку)
Базовая схема взаимодействия при вызове API
Вызов API осуществляется согласно спецификации Oauth 2.0, который предполагает первичное получение токена, разрешающего выполнить непосредственный запрос API (access_token).
Sber API Registry обеспечивает защиту от несанкционированного доступа к API, и в случае успешных проверок самостоятельно маршрутизирует запрос API на сторону поставщика. В числе проверок:
1.Добавьте ClientId и ClientSecret в Ваш сервис вызова API.
2. Загрузите полученный контейнер с сертификатом в хранилище сертификатов.
При необходимости, контейнер можно распаковать для импорта клиентских и корневых сертификатов в Keystore и Truststore вашего хранилища.
Для этого можно воспользоваться командой:
После выполнения команды вы получите 3 файла, которые можно загружать в ваши хранилища:
Проверить информацию, содержащуюся в извлеченных сертификатах можно по команде:
Внутри файла log.txt будет представлено содержание файла сертификата.
3. Доработайте Ваш сервис вызова API, встроив в него сертификат.
4. Доработайте Ваш сервис вызова API, встроив в него сценарий получения access_token.
Новый токен нужно получать для каждого нового запроса к API. Срок жизни токена составляет 60 сек.
Если вы не можете понять какой тип токена нужно получать, уточните у Поставщика вашего API по контактам, указанным в карточке продукта.
История одного API: как мы превратили Франкенштейна в красавчика
Что нужно, чтобы построить экосистему небанковских сервисов, да и вообще любую подобную экосистему? Мастер-система хранения и обработки данных, а также API. В этом посте мы разберем две версии созданного нами API — первую и удачную — и подробно остановимся на том, в чем их важные отличия друг от друга.
Для создания экосистемы небанковских сервисов был выбран ключевой продукт дивизиона «Цифровой Корпоративный Банк» Сбербанка — интернет-банк для корпоративных клиентов Сбербанк Бизнес Онлайн. Соответственно, fintech API для экосистемы небанковских сервисов тоже делали на его основе.
Первую версию fintech API запустили в 2016 году. Создавалась она с оглядкой на другие наши API нашего банка, по классическим рецептам API крупных финансовых организаций. Вот основные ингредиенты:
Результаты интеграций оказались далеки от желаемых. От API современных нефинансовых сервисов партнеры ждали совсем не того, что принято в области разработки классических банковских продуктов. Хотели получить что-нибудь подобное API современных интернет-гигантов: Facebook, Google, Yandex.
А в итоге столкнулись с классическим API банка — тяжелым, малопонятным, требующим высокой и специфической квалификации, понимания тонкостей рабочих процессов, реализации избыточных требований безопасности… в общем, множества вещей, которые приводят к нарушению всех возможных дедлайнов по интеграции.
Мы проанализировали этот опыт и решили сделать новую версию fintech API с чистого листа. Чтобы получить максимальный win-win со сторонними нефинансовыми сервисами, важнейшие требования изложили заранее:
Что изменилось по факту
Чтобы оценить разницу между двумя версиями API, сравним реализации трех его ключевых компонентов: авторизации, реализации рублевого платежного поручения и электронной подписи.
В первой версии API для авторизации партнеру требовались логин и пароль, сертификат и AccessToken, полученный в результате OAUTH-аутентификации обратившегося клиента:
В API 2.0 авторизация стала гораздо компактнее. Для доступа к сервисам нужен только AccessToken, полученный при OAUTH-аутентификации клиента:
В API 1.0 работа с рублевым платежным поручением также была основана на SOAP:
В API 2.0 аналогичным образом все стало гораздо проще и понятнее:
Электронную подпись мы также облегчили. Вот как все было в API 1.0.
Так выглядел запрос
Вот список атрибутов
И вот готовая подпись
В версии API 2.0 через JSON реализовали все проще:
Сам запрос
Подпись в результате
Итоги
Пилотные запуски fintech API 2.0 показали, что дела пошли значительно лучше. Время интеграции с продуктами партнеров — от старта работ до момента выпуска в промышленную эксплуатацию — сократилось более чем в 3 раза. На порядок сократилось количество вопросов нашей службе сопровождения, и что самое ценное, снизилась сложность этих вопросов. Наконец, на целых два порядка сократилось количество жалоб на сложность и непредсказуемость работы API. В общем, мы сделали это. Если есть вопросы — добро пожаловать в комментарии, с удовольствием расскажем подробности.
Материал подготовил Андрей Хохлов, руководитель проектов дивизиона «Цифровой Корпоративный Банк» Сбербанка
Встроенный банк: зачем бизнесу Fintech API Сбербанка
Крупные компании пользуются десятками разных банковских услуг: зарплатным проектом, валютными переводами и конвертациями, кредитами, аналитикой, брокерскими услугами, расчетами с клиентами. Все они так или иначе связаны с основной деятельностью компании, процессы которой поддерживаются в собственной учетной системе.
Сбербанк одним из первых в России позволил компаниям в разы упростить взаимодействие с банком.
Технология Fintech API позволяет клиентам получить доступ к банковским услугам в собственной IT-инфраструктуре и тем самым упростить и автоматизировать взаимодействие.
Как работает API
Что такое Fintech API и чем он полезен бизнесу? Это легкий в использовании, защищенный и быстрый интерфейс доступа к инфраструктуре банка. Фактически любой продукт банка доступен в учетной системе компании. Сотрудник клиента отправляет распоряжение в банк, банк его обрабатывает и направляет ответ в стандартном формате, например в формате выписки, или исполняет команду внутри своей системы, например переводит сотрудникам зарплату.
Описание методов Fintech API публично доступно и задокументировано. Разработчику на стороне клиента не нужно разбираться в хитросплетениях банковской цифровой инфраструктуры, ему достаточно универсального набора методов, опубликованных в Fintech API банка, и лаконичной инструкции по его использованию.
«Fintech API Сбербанка — одно из наиболее развитых решений на отечественном рынке по нескольким показателям: по количеству продуктовых методов, по числу возможностей подключения, по скорости работы, по количеству интегрированных продуктов, услуг, сервисов и по количеству клиентов. Сегодня корпоративным клиентам Сбербанка доступны такие возможности, как вход через Сбербанк Бизнес Онлайн или оплата через Сбербанк Бизнес Онлайн, автоматизация работы с зарплатным проектом, рублевыми и валютными платежами, валютным контролем, реестрами поставщиков услуг — и все это благодаря технологиям, разработанным нашими специалистами»
Что может Fintech API Сбербанка
Изначальный проект реализации API был выполнен по всем канонам создания банковского ПО, но его структура получилась тяжелой, требующей от пользователя высокой и специфической квалификации, с чрезмерными требованиями безопасности. Тогда Сбербанк решил создать API, который ориентировался бы на опыт технологических компаний: Apple, Amazon, Microsoft и Google. Получившееся решение вышло простым, надежным и универсальным.
Fintech API поддерживает 18 групп методов, которые можно условно объединить в основные направления:
1. Выставление и оплата счетов. Платежные поручения формируются по запросу и уже заполненными. Минимизируются трудозатраты бухгалтерии и снижается вероятность ошибки.
2. Информация по счетам и операциям. Получение выписки устроено не сложнее, чем для клиентов-физлиц, но Fintech API справится и с более сложными запросами, например предоставит отчет из сервиса «Бизнес-аналитика».
3. Организация зарплатного проекта. Позволяет автоматизировать работу с зарплатными ведомостями, а также выпуск зарплатных карт. Бухгалтерам будет проще составить документы и передать их банку, а значит, они смогут работать более продуктивно.
4. Международные платежи. Решение позволяет автоматизировать операции с валютой, в том числе переводить деньги, конвертировать их в другие валюты и осуществлять валютный контроль. Возможности API позволяют решить большинство задач, связанных с внешнеэкономической деятельностью и соблюдением отраслевых законов.
Кроме того, Fintech API Сбербанка дает клиентам ряд важных преимуществ, которые не связаны напрямую с бизнес-процессами, но значительно упрощают взаимодействие с банком. Первое из них — единая авторизация во всех сервисах Сбербанка — «Сбер Бизнес ID» для юридических лиц. Достаточно один раз авторизоваться, чтобы пользоваться всеми продуктами в рамках одной учетной записи. Сервисы не только распознают учетную запись клиента, но и обмениваются друг с другом информацией, например можно подставить в платежное поручение (один сервис) данные контрагента из базы Сбербанка (другой сервис). За счет этого Fintech API помогает создать по-настоящему бесшовный переход между продуктами в рамках экосистемы Сбербанка.
Второе важное преимущество — удобное получение согласия клиента на подключение к Fintech API, доступ к банковской тайне и персональным данным. Оно оформляется при первом переходе клиента к сервису и имеет юридическую силу. При этом у клиента остаются широкие возможности по управлению выданными разрешениями: в любой момент он может отозвать их или изменить конфигурацию для того или иного продукта.
Важное преимущество для интеграции — легкая, удобная для чтения документация (в отличие от распространенных в банковской сфере pdf-инструкций на сотни листов). Сбербанк предоставляет возможность для моделирования бизнес-процессов и получения тестовых результатов в условиях, приближенных к промышленной эксплуатации.
Как API Сбербанка помогает бизнесу автоматизировать финансы
В мае 2020 года к сервису подключился продовольственный холдинг «Черкизово». По словам руководителя ЕРЦ компании Аркадия Саркисова, интеграция со Сбербанком позволит компании объединить около 40 открытых счетов в одном окне. При этом процесс подключения к Fintech API прошел без накладок и в максимально сжатые сроки, отметил Саркисов. Холдинг «Черкизово» подключился за два дня, это рекорд по интеграции компании такого масштаба, отметила директор дивизиона «Цифровой корпоративный банк» Сбербанка Анна Лоевская.
В марте 2020 года к системе Сбербанка через платформу «Транзит 2.0» Национального расчетного депозитария Московской биржи подключились «Россети». Благодаря этому компания намерена повысить скорость, надежность, безопасность и прозрачность расчетных операций и финансовых процессов.
Что делать, если нет собственной разработки
Организации, у которых нет собственного IT-подразделения, также могут воспользоваться преимуществами Fintech API. Сбербанк предлагает таким компаниям транспортный модуль «СберИнтеграция». Он устанавливается прямо на учетную систему клиента и не требует дополнительной разработки, настройка бесплатная и занимает примерно один день. Клиент получит доступ ко всем функциям эффективного b2b-портала: рублевым и валютным выпискам, платежным поручениям, зарплатам и валютному контролю. Еще одно важное преимущество «СберИнтеграции» — упрощенный доступ к получению кредитов для компании.
Результаты
Fintech API ежедневно обрабатывает более 4 млн технических запросов. Ежедневно больше 60 000 уникальных клиентов используют продукты, сервисы и услуги, интегрированные через Fintech API. Обработка запроса занимает всего 0,2 секунды.
Решение Сбербанка поможет автоматизировать большинство финансовых операций, ускорить процессы, избежать ошибок и сэкономить человеческие ресурсы. Fintech API Сбербанка удостоено многих международных наград. На данный момент это одно из самых продвинутых банковских решений для бизнеса в России и за ее пределами.
Подключение метода оплаты Сбербанк-Эквайринг
В данной статье рассмотрим:
Сбербанк – крупнейший в России банк-эквайер, с многолетним опытом работы на рынке эквайринговых услуг, собственный процессинговым центром, и командой высококвалифицированных специалистов. Банк предоставляет услуги эквайринга на высоком уровне, их отличает минимальная стоимость. При этом исключается возможность утечки конфиденциальной информации.
В настоящий момент сервис Сбербанк предлагает решение касательно 54-ФЗ для интернет-магазинов, осуществляя отправку фискальных данных из интернет-магазина в облачные кассы.
Для этого необходимо:
1) Обратиться к своему клиентскому менеджеру или в службу поддержки на support_ecomm@sberbank.ru
2) В личном кабинете АТОЛ Онлайн можно взять кассу в аренду, приобрести фискальный накопитель, дистанционно оформить соответствующие договоры и получить сервис по регистрации ККТ/ФН в ФНС.
Рассмотрим как подключить и настроить интернет-эквайринг от Сбербанка в интернет-магазине на платформе ADVANTSHOP.
Первое, что необходимо сделать, это отправить заявку на подключение в Сбербанк эквайринг, заключить договор и зарегистрироваться. Перейдите на сайт https://www.sberbank.ru/help/business/sbbol/100074 и нажмите на кнопку «Интернет-банк СберБизнес» (рис.1)
Рисунок 1.
Откроется окно, где необходимо зарегистрироваться, и затем Ваc переведет на страницу Создание СберБизнес ID, где необходимо ввести Ваш номер телефона, который будет Вашим логином в интернет банке (рис.2).
Рисунок 2.
Далее выполните все необходимые настройки, а именно оформите заявку, заполните заявление и отправьте данное заявление в банк согласно инструкции на стороне банка.
После чего с Вами связываются, Вы заключаете договор, обговариваете условия сотрудничества и предоставляются доступ в личный кабинет.
способы оплаты и нажмите на кнопку “Добавить способ оплаты”» src=»https://www.advantshop.net/help/pages/files/100/sberbank/sberbank-100-30.JPG» style=»border: 1px solid gray;»/>
Рисунок 3.
Далее нажмите «Добавить способ оплаты». Во всплывающем окне, введите название и выберите из выпадающего списка модуль «Сбербанк-Эквайринг» (рис.4)
Рисунок 4.
Поставьте активность метода оплаты, и заполните поля настроек (рис.5)
Рисунок 5.
Все данные для заполнения полей Сбербанк высылает Вам на почту:
Сначала будут высланы тестовые данные, после проведения тестовых настроек и тестового платежа, сбербанк вышлет боевые настройки.
После проделанных шагов, проведите тестовый платеж.
Поставьте галочку в строке «Тестовый режим», проверьте оплату на товаре ценой в 1-5 рублей, используя тестовую карту, которую предоставляет Сбербанк (указана в документации).
Если оплата проходит корректно, свяжитесь со Сбербанком; служба поддержки Сбербанка сообщит Вам «боевые» настройки (логин, пароль, имя мерчанта), которые Вам нужно будет указать в настройках метода на стороне магазина (вместо тестовых настроек).
После этого отключите галочку «Тестовый режим».
Далее необходимо написать на почту support_ecomm@sberbank.ru просьбу о том, чтобы для вашего мерчанта на стороне Сбербанка прописали уведомления в случае успешного платежа или ошибки.
Эти URL указаны в настройках метода оплаты «Сбербанк» на стороне магазина:
Если у вас кириллический домен, то в настройках магазина (пункт меню «Настройки->Общие настройки», поле «URL Магазина») и при регистрации в сбербанке, укажите домен в punycode, для конвертации домена можете использовать любой сервис, например: https://www.punycoder.com/.
Также обратите внимание, в магазине обязательно должны прописаны ваши реквизиты, номер телефона, описание метода оплаты сбербанк. И сбербанк эквайринг не заключит договор, если продаете товары 18+.
Готово. Мы рассмотрели подключение платежного модуля Сбербанк-Эквайринг. Ниже рассмотрим типовые ошибки и пути их решения.
Типовые ошибки и их решение:
Решение: Вам необходимо указать корректные настройки метода оплаты в полях «Логин», «Пароль» и «Имя мерчанта». Пожалуйста, убедитесь, что вы корректно сменили временный пароль, присланный вам Сбербанком изначально.
Производить смену временных паролей на стороне Сбербанка необходимо как для логина вида login-api, так и для логина вида login-operator.
Решение: для проведения тестового платежа необходимо использовать тестовую карту Сбербанка. Данные тестовой карты указаны в технической документации Сбербанка.
Как работают приложения Сбербанк Онлайн: Workflow 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. Напрямую не используешь, но запомним – потом пригодится.
Как решили делать
Объекты упаковываются в контейнеры, презентационную логику приложения строим на этих контейнерах. Основное преимущество – можем группировать несколько простых объектов в один контейнер. Это дает свободу в программировании UX/UI на клиенте, например, можем управлять скрытием/отображением одного поля при заполнении данных в другом. При этом базовых типов объектов – ограниченное число, и весь бизнес-транспорт реализуется на них.
Мы выбрали именно этот подход. Сначала мы опишем протокол API, а потом – как устроены фрэймворки внутри мобильных и веб-приложений.
Чтобы было понятнее, рассмотрим API на примере простого процесса, например, перевод между своими счетами. Как добираемся до точки входа, не рассматриваем – это не процесс и для этого есть свой API (о нем мы тоже как-нибудь расскажем). Итого, процесс у нас начинается с точки входа: 
Транспорт данных
Для начала договоримся об основных принципах – как передаём данные. За основу возьмём самый простой подход – пары «ключ-значение». Ключом пусть будет строка из букв латинского алфавита, значение – тоже строки, но уже произвольные.
Формы для заполнения бывают сложные, с вложенными элементами и подразделами, значит, надо допускать вложенность. Можно именовать ключи в формате camelCase, но они могут быть плохо читаемым (например, в логах) или даже «портиться» в системах, нечувствительных к регистру. Нужно ввести разделитель.
Самый очевидный разделитель – точка – во многих языках используется для доступа к свойствам объекта. При неаккуратном использовании ключи с таким разделителем будут создавать словари (или объекты), в которых возможны коллизии. Например, “foo.bar” = “foobar” и “foo.bar.baz” = “foobarbaz” в javascript может повлечь перезапись свойства “bar” объекта “foo” со строки на объект. В конце концов, договорились на двоеточии: с одной стороны, явное визуальное разделение и семантическое отражение вложенности, с другой стороны, достаточно безопасно для всех используемых языков.
Что делать с повторяемыми полями? Вводим дополнительное правило: между парой разделителей могут быть либо латинские буквы, либо цифры. Получаются конструкции вида: children:5:name:first.
Пожив некоторое время с такой структурой, обнаруживаем ограничение: множественный выбор оказывается нетривиальным в реализации и требует дополнительных ухищрений на бэкэнде, чтобы держать высокую нагрузку.
Решение: значение – либо строка, либо список строк. Так решение выглядит типовым, но в то же время накладные расходы оказываются незначительными.
Шаг – это состояние процесса. Первый шаг у нас – выбор счета списания и счета зачисления и ввод суммы. 
UI на этой картинке не видно, потому что шаг – это про серверную логику, а не про презентационную. Есть два подхода к работе с шагами: можно передавать с сервера только разницу (нарастающий итог в клиентском приложении) или каждый шаг целиком (нарастающий итог на сервере).
Анализ требований показал, что в ходе процесса экран может формироваться по-разному на разных шагах (ветвление процессов), поэтому вместо добавления управляющих команд для преобразования уже переданных сущностей проще каждый шаг передавать полностью таким, каким его должен увидеть пользователь.
Из дополнительных плюсов: при возврате к редактированию не нужно проигрывать весь сценарий или передавать дополнительный параметр “отдай всё”. При старте шага клиентское приложение сразу же получает всю нужную информацию для построения экранов.
Экраны
Экран – это разделение процесса на этапы в клиентском приложении. Как правило, экраны используются, чтобы форма была проще для восприятия. В нашем случае всё просто: один шаг – один экран. 
Для экранов мы ввели два правила:
UI компоненты (блоки)
UI компонент – независимый компонент, который реализует клиентскую логику и наполняет документ данными. По сути, это ассоциация между управляющей командой в протоколе и куском кода и разметки в приложении. На первом экране три компонента:
Поля – это атомарные компоненты, которые выступают транспортом для отдельных элементов данных и обрабатывают пользовательский ввод в случае деградации блока. Типов полей ограниченное число и все они поддерживаются на уровне фрэймворка: 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-компонентами:
Coming soon…
Мы очень старались писать лаконично, но это первая техническая статья про платформу Сбербанк Онлайн и она должна была многое охватить.
Пишите в комментариях, что непонятно, что интересно – постараемся писать меньше, но чаще и в цель. У нас много интересных вызовов, и поэтому много материала.
