История одного API: как мы превратили Франкенштейна в красавчика

Что нужно, чтобы построить экосистему небанковских сервисов, да и вообще любую подобную экосистему? Мастер-система хранения и обработки данных, а также API. В этом посте мы разберем две версии созданного нами API — первую и удачную — и подробно остановимся на том, в чем их важные отличия друг от друга.

Для создания экосистемы небанковских сервисов был выбран наш ключевой платформенный продукт — интернет-банк для корпоративных клиентов Сбербанк Бизнес Онлайн. Соответственно, API для экосистемы небанковских сервисов тоже делали на его основе.

Первую версию API запустили в 2016 году. Создавалась она с оглядкой на другие наши API, по классическим рецептам API крупных финансовых организаций. Вот основные ингредиенты:

• Протокол SOAP для передачи данных
• XML-формат
• Электронная подпись всех запросов
• Асинхронный режим работы
• Обязательный hardware-VPN для организации защищенного канала
• Проприетарная система аутентификации и авторизации
• Исторически сложившиеся форматы для передачи финансовой информации (например, формат 1С direct banking)

Мы сделали такое решение и начали пилотные интеграции с несколькими неклассическими банковскими сервисами: интернет-магазином «Эвотор», системой управления финансами «Бизнес-аналитика», облачной бухгалтерией «МоеДело» и другими.

Результаты интеграций оказались далеки от желаемых. От API современных нефинансовых сервисов партнеры ждали совсем не того, что принято в области разработки классических банковских продуктов. Хотели получить что-нибудь подобное API современных интернет-гигантов: Facebook, Google, Yandex.

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

Мы проанализировали этот опыт и решили сделать новую версию API с чистого листа. Чтобы получить максимальный win-win со сторонними нефинансовыми сервисами, важнейшие требования изложили заранее:

• Никаких универсальных и тяжелых форматов, которые учитывают малейшие нюансы. Будем проще!
• API должен подходить максимально широкому кругу потенциальных партнеров, предлагающих нефинансовые продукты клиентам Сбербанка. Вплоть до внедрения в умные холодильники — с чем черт не шутит.
• API нужно проектировать с помощью практик и способов, которые используются при создании визуальных интерфейсов. Для этого нужно выявить и проанализировать UX-схемы использования API. Следовать классическим канонам точно не стоит.
• Нужно избавиться от многотомных описаний, чтобы разработчики могли достичь быстрого результата. С помощью песочницы для тестовых испытаний нужно получать первые положительные результаты уже за час.
• Максимально отказываемся от проприетарных решений, привязанных к определенной платформе. Все должно быть кроссплатформенным и не ограничивать партнера в используемой инфраструктуре и среде разработки.
• Партнерам не должно мешать то, чем они не занимаются — сложные структуры данных, механизмы компонентов банковской платформы, особенности работы наших legacy-систем. Скрываем и не забиваем им головы.

С этим списком мы перешли к реализации и выбрали решений для второй версии API:

• Аутентификация на базе протокола OAUTH 2.0
• REST-архитектура поверх HTTP без дополнительных сложностей
• Полностью синхронная работа
• Формат JSON
• Опциональное применение электронной подписи — там, где это необходимо
• Тестовая песочница с развернутым SWAGGER. С помощью этой среды отладки разработчик партнера может смоделировать бизнес-процесс работы и получить результат без написания кода
• Применение используемого интернет-стартапами подхода Easy Steps при создании документации к API
• Agile-практики при разработке API — быстрый результат и сбор обратной связи

Что изменилось по факту

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

В первой версии API для авторизации партнеру требовались логин и пароль, сертификат и AccessToken, полученный в результате OAUTH-аутентификации обратившегося клиента:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:upg="http://upg.sbns.zzzzz.com/">    <soapenv:Header/>    <soapenv:Body>       <upg:preLogin>          <!--Optional:-->          <upg:userLogin>U1</upg:userLogin>          <!--Optional:-->          <upg:changePassword>!d63NvJ+Sa</upg:changePassword>       </upg:preLogin>    </soapenv:Body> </soapenv:Envelope>

В API 2.0 авторизация стала гораздо компактнее. Для доступа к сервисам нужен только AccessToken,  полученный при OAUTH-аутентификации клиента:

{ "access_token": "fdba5482-460c-4535-b829-9fd836fd01f0-1", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "7f545a14-ab7b-45ff-823a-0421e9f3b42e-1", }

В API 1.0 работа с рублевым платежным поручением также была основана на SOAP:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:upg="http://upg.sbns.zzzzz.com/">    <soapenv:Header/>    <soapenv:Body>       <upg:sendRequestsSRP>          <!--Zero or more repetitions:-->          <upg:requests><![CDATA[         <Request xmlns='http://zzzzz.com/upg/request' orgId='84b70f22-703f-bf04-db60-bd110572f40d' requestId='a81ddc6d-fb92-416d-83f9-6785a59a4b17' version='1.0' sender='PARTNER' clientOrgIdHash='ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5' clientAccessToken='ee0fb56b01a9d9b9648a2c60549b77702eb2a6de8f2189c4349447e43b250da5-1'> <PayDocRuInvoice docExtId='a81decfd-fb92-416d-83f9-6785a59abb65' orderNum='62' deadLine='2017-04-10T17:16:03'> <PersonalAcc>40802810000000000000</PersonalAcc> <AccDoc docDate='2017-02-15' docSum='777' transKind='01' paytKind='01' priority='1'> <Purpose>!!!!!НДС 18%</Purpose> </AccDoc> </PayDocRuInvoice> </Request>          ]]></upg:requests>          <!--Optional:-->          <upg:sessionId>5a869c00-e979-4280-b11a-6dbbb8a90214</upg:sessionId>       </upg:sendRequestsSRP>    </soapenv:Body> </soapenv:Envelope>

В API 2.0 аналогичным образом все стало гораздо проще и понятнее:

{     "amount": 12.01,      "date": "2018-06-22",      "deliveryKind": "электронно",      "expirationDate": "2018-06-23",      "externalId": "1516ec0c-761c-11e8-adc0-fa7ae01bbebc",     "operationCode": "01",     "orderNumber": "1237",      "payeeAccount": "40706810000000000000",      "paymentNumber": "1",     "priority": "5",      "purpose": "Оплата заказа №1237. НДС не облагается.",     "urgencyCode": "NORMAL",      "vat": {       "amount": 100.01,        "rate": "7",        "type": "NO_VAT"   }

Электронную подпись мы также облегчили. Вот как все было в API 1.0.

Так выглядел запрос

Вот список атрибутов

И вот готовая подпись

В версии API 2.0 через JSON реализовали все проще:

Сам запрос

Подпись в результате

Итоги

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

Материал подготовил Андрей Хохлов, руководитель проектов в блоке «Корпоративный бизнес» Сбербанка