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

Что нужно, чтобы построить экосистему небанковских сервисов, да и вообще любую подобную экосистему? Мастер-система хранения и обработки данных, а также 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-аутентификации обратившегося клиента:

В 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:


   
   
      
         
         

40802810000000000000

!!!!!НДС 18%



         ]]>
         
         5a869c00-e979-4280-b11a-6dbbb8a90214

В 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. В общем, мы сделали это. Если есть вопросы — добро пожаловать в комментарии, с удовольствием расскажем подробности.

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