С недавнего времени пользователям Visa QIWI Кошелька доступны новые методы API. Под катом: что это за API, зачем мы его открыли и почему стоит начать им пользоваться уже сейчас.
Формально история нашего API началась в апреле этого года, хотя часть из входящих в него методов была доступна задолго до этого.
Массовый пользовательский сервис QIWI Кошелек постепенно переходит на архитектуру микросервисов, поэтому внутри нашей системы компоненты взаимодействуют друг с другом посредством некоего API. Любой пользователь может зайти на сайт, открыть дебаггер и просмотреть, какие запросы браузер отправляет на сервер. Минимальных навыков программиста достаточно, чтобы вытащить отправляемые запросы и использовать их в собственных решениях в обход сайта.
Желающих так схитрить оказалось довольно много. Это и студенты-энтузиасты, которым интересно поковыряться в деталях работы Кошелька, и профессиональные разработчики, желающие интегрировать отдельные функции сайта QIWI Кошелька в свои решения. В итоге параллельно с развитием сайта начала развиваться целая экосистема сторонних решений в «сером» режиме, не легализованном в пользовательском соглашении и не обеспеченным нашим саппортом.
Вот только скрипты, построенные на результатах самостоятельных исследований сайта, работают у пользователей нестабильно. Разработчики используют разные способы извлечения информации, в том числе откровенно устаревшие методы, создающие дополнительную нагрузку на наши сервера.
Чтобы упорядочить выгрузку данных с сайта, мы приняли решение легализовать ее, как это сделали в свое время в Citibank, Wargaming и Вконтакте. Мы описали наиболее современный и стабильный из существующих способов получения информации, сформировав первую версию пользовательского API.
С появлением документации для разработчиков пользователям больше не нужно разбирать наш сайт по кусочкам, рискуя наткнуться на старые протоколы. По посещаемости раздела документации мы отслеживали, насколько востребован API. Мы также разместили адрес электронной почты для обратной связи и вопросов и мониторили публикации по теме в социальных сетях и форумах. На тот момент перед нами не стояло задачи как-то продвигать API — мы хотели навести порядок и предложить сторонним разработчикам бесплатный, безопасный, проверенный способ доступа.
Публикация документации по API сама по себе никак не отразилась на работе сторонних инструментов доступа к функциям Кошелька. Мы не планировали регламентировать «самострой», но наблюдали за ситуацией, поскольку решения были построены разработчиками на свой страх и риск на основе недокументированных возможностей сервиса. И пока они не затрагивают данные наших пользователей, мы никак с ними не боремся, но стараемся выйти на контакт с их создателями и рекомендовать перейти на использование задокументированного API.
Поскольку запросы проходили через парсинг сайта, очевидно, что решения, использующие выходящие за рамки API методы, будут работать до тех пор, пока соответствующие схемы работают на сайте. Но мы надеемся, что после появления более качественного пути недокументированные решения начнут постепенно отмирать.
К сожалению, на момент создания первой версии API у нас еще не было отдельной системы аутентификации. Поэтому на том этапе мы использовали схему аутентификации с нашего сайта (CAS), она была разобрана по отдельным командам и опубликована на developer.qiwi.com.
Аутентификация стала ключевой проблемой первого API. Если с точки зрения сайта механизм был правильным (именно так организована аутентификация на большинстве веб-страниц, по принципу двух токенов с разным временем жизни), то пользователю пройти процедуру оказалось довольно сложно. Этот метод изначально не был ориентирован на пользователей, а служил внутренним задачам нашего сайта. В результате возникали различные сложности, к примеру, выскакивала капча «докажите, что вы не робот», что было неожиданностью для пользователей, поскольку API предполагает доступ именно при помощи автоматических систем.
Хотя публикацию открытого API мы никак не афишировали, в сети появилось несколько статей, в том числе с негативными отзывами. На адрес обратной связи api_help@qiwi.com мы получили более сотни писем, смысл которых сводился к тому, что сам по себе API хороший, но аутентификация никуда не годится. Не все пользователи понимали, почему для подключения к финансовому сервису надо проходить столь заковыристую процедуру, в то время как с Instagram или Вконтакте все намного проще. Мы разъясняли, что сложности были обусловлены именно финансовой составляющей, ведь используемый метод (как в аутентификации сайта, так и в API) не должен ставить под угрозу счета клиентов.
Анализируя обратную связь, мы увидели, что API востребован, а критика направлена в основном на систему аутентификации, и приняли решение развивать API дальше.
Разработка новых методов в рамках API была поручена команде специалистов, которые делают бекэнд для сайта и мобильного приложения QIWI Кошелька. API — их ключевая компетенция, именно эта команда переводит основной сайт на архитектуру микросервисов. И API тут служит для взаимодействия основного сайта и отдельных сущностей через запросы, которые мы передаем нашим пользователям.
Чтобы доработать существующий API и добавить в него новые методы, мы тщательно проанализировали обратную связь от пользователей.
Хотя среди наших клиентов довольно много любителей-энтузиастов, склонных пробовать что-то новое, основная часть пользователей API — профессиональные разработчики, интегрирующие QIWI Кошелек в свои бизнес-процессы (причем, это не интернет-магазины — для юридических лиц у нас предусмотрен отдельный API). В основном речь идет об оптимизации работы Кошелька под собственные нужды: настройке уведомлений, автоматизации оплаты услуг и обмена цифровыми товарами между пользователями, а также других задачах, не связанных с привычной электронной коммерцией.
Опираясь на отзывы, мы предложили новую аутентификацию пользователей через API, добавили новые функции для взаимодействия с Кошельком. В первой версии у нас были описаны запрос баланса, история платежей и отправка перевода. Сейчас их дополнили запрос профиля пользователя, оплата сотовой связи, переводы в банки и на карты по номерам карт, счетов и договоров вместо полных реквизитов.
Для построения системы аутентификации, ориентированной на API, мы использовали стандарт RFC 6749 по открытому протоколу OAuth 2.0. Чтобы аутентификация соответствовала требованиям финансового сервиса, мы обеспечили двухфакторный доступ — по паролю к Кошельку и SMS-коду. Для прохождения процедуры пользователю необходимо выпустить токен, действительный в течение одного месяца (выпуск подтверждается SMS-сообщением). По просьбе пользователей в новой версии OAuth 2.0 мы также открыли возможность выбора прав доступа для токена. К примеру, если требуется запросить баланс или получить историю платежей, токену даются права только на чтение. Всего доступно четыре группы прав доступа:
Функция оказалась весьма востребована, менее половины токенов выпускается с полными правами (осуществление платежей), многим нужно лишь получение информации.
Одна из новых функций, родившихся внутри нашей команды, а не из пожеланий клиентов — запрос профиля пользователя. Он позволяет получать различную информацию о Кошельке: дату регистрации, привязанный адрес электронной почты, уровень идентификации Кошелька. Последнее особенно важно для финансового сервиса, поскольку уровень идентификации определяет лимиты по операциям для кошелька. Ранее эту информацию можно было найти в настройках Кошелька на сайте qiwi.com, теперь она доступна и через API.
Отметим, что персональные данные пользователя через запрос профиля не доступны — таково требование безопасности.
Следуя пожеланиям пользователей, мы добавили в API возможность запрашивать размер комиссии при проведении операций по любому из доступных поставщиков услуг. Метод этот открыт и прохождения процедуры аутентификации не требует.
Еще одно нововведение, инициированное нашими пользователями, — инструмент автоматизации оплаты сотовой связи, например, для телефонов курьеров.
Фактически метод состоит из двух этапов:
По аналогии с оплатой сотовой связи эта группа методов API позволяет автоматизировать переводы на банковские карты систем VISA, MasterCard и национальной платежной системы МИР по России и СНГ. Перевод осуществляется по номеру карты, по нему же определяется платежная система.
Банковский перевод — это отдельный метод, используемый для отправки денег в некоторые банки, с которыми у нас реализован онлайн-протокол моментальных переводов. В отличие от обычных денежных переводов по банковским реквизитам, для этих банков можно использовать большее количество идентификаторов клиента (номер карты, договора, счета и т. п.).
До последнего времени доступ по API был формально запрещен. Все, что выполнялось при помощи API, делалось на свой страх и риск. Если пользователь распарсил сайт, достал из него какие-то команды, провел операции с кошельком, и у него пропали деньги, всю ответственность за последствия своих действий нес он сам. Техническая поддержка никак не участвовала в решении подобных проблем.
Чтобы таких ситуаций больше не возникало, мы внесли в пользовательское соглашение соответствующие изменения. Теперь API имеет официальный статус наравне с сайтом и мобильным приложением.
Перечисленные методы доступа к данным уже работают, а документация по ним опубликована на сайте developer.qiwi.com.
Завершено внутреннее тестирование, и, опубликовав API, мы перешли ко второму этапу — проверке работоспособности связки «пользователь + документация + API». Этот этап должен ответить на вопросы о том, насколько понятна документация, нужны ли какие-то дополнительные пояснения и т. п. Поэтому мы предлагаем пользователям направлять отзывы на наш адрес: api_help@qiwi.com.
В ближайшей перспективе мы планируем расширить возможности API, предоставив сторонним сервисам методы для регистрации новых и аутентификации существующих пользователей в системе, а также проведения от их имени финансовых операций. Это немного иная модель взаимодействия между нами, пользователем и третьей стороной — сторонним сервисом.
Если вам интересны детали разработки новой версии API, пишите и задавайте вопросы в комментариях — мы постараемся ответить на них в наших следующих публикациях.
Чтобы заинтересовать разработчиков в использовании нового API, мы проводим всероссийский QIWI API Contest. Это первый конкурс в рамках QIWI Open Platform, направленный на популяризацию API компании.
Для участия в конкурсе необходимо создать Mobile First решения — чат-боты, мобильные приложения и web-продукты c использованием API QIWI Кошелька. Наши эксперты отберут наиболее проработанные решения и пригласят до 15 участников в финал конкурса, который пройдет в Москве 23 сентября.
Конкурсанты из других городов могут принять участие дистанционно. Регистрация проектов открыта и продлится до 15 сентября. Заявку на участие можно отправить на почту apimarket@qiwi.com. Для всех вопросов мы создали специальный чат в Telegram.
История появления API
Формально история нашего API началась в апреле этого года, хотя часть из входящих в него методов была доступна задолго до этого.
Массовый пользовательский сервис QIWI Кошелек постепенно переходит на архитектуру микросервисов, поэтому внутри нашей системы компоненты взаимодействуют друг с другом посредством некоего API. Любой пользователь может зайти на сайт, открыть дебаггер и просмотреть, какие запросы браузер отправляет на сервер. Минимальных навыков программиста достаточно, чтобы вытащить отправляемые запросы и использовать их в собственных решениях в обход сайта.
Желающих так схитрить оказалось довольно много. Это и студенты-энтузиасты, которым интересно поковыряться в деталях работы Кошелька, и профессиональные разработчики, желающие интегрировать отдельные функции сайта QIWI Кошелька в свои решения. В итоге параллельно с развитием сайта начала развиваться целая экосистема сторонних решений в «сером» режиме, не легализованном в пользовательском соглашении и не обеспеченным нашим саппортом.
Вот только скрипты, построенные на результатах самостоятельных исследований сайта, работают у пользователей нестабильно. Разработчики используют разные способы извлечения информации, в том числе откровенно устаревшие методы, создающие дополнительную нагрузку на наши сервера.
Чтобы упорядочить выгрузку данных с сайта, мы приняли решение легализовать ее, как это сделали в свое время в Citibank, Wargaming и Вконтакте. Мы описали наиболее современный и стабильный из существующих способов получения информации, сформировав первую версию пользовательского API.
С появлением документации для разработчиков пользователям больше не нужно разбирать наш сайт по кусочкам, рискуя наткнуться на старые протоколы. По посещаемости раздела документации мы отслеживали, насколько востребован API. Мы также разместили адрес электронной почты для обратной связи и вопросов и мониторили публикации по теме в социальных сетях и форумах. На тот момент перед нами не стояло задачи как-то продвигать API — мы хотели навести порядок и предложить сторонним разработчикам бесплатный, безопасный, проверенный способ доступа.
Публикация документации по API сама по себе никак не отразилась на работе сторонних инструментов доступа к функциям Кошелька. Мы не планировали регламентировать «самострой», но наблюдали за ситуацией, поскольку решения были построены разработчиками на свой страх и риск на основе недокументированных возможностей сервиса. И пока они не затрагивают данные наших пользователей, мы никак с ними не боремся, но стараемся выйти на контакт с их создателями и рекомендовать перейти на использование задокументированного API.
Поскольку запросы проходили через парсинг сайта, очевидно, что решения, использующие выходящие за рамки API методы, будут работать до тех пор, пока соответствующие схемы работают на сайте. Но мы надеемся, что после появления более качественного пути недокументированные решения начнут постепенно отмирать.
Проблемы первой версии
К сожалению, на момент создания первой версии API у нас еще не было отдельной системы аутентификации. Поэтому на том этапе мы использовали схему аутентификации с нашего сайта (CAS), она была разобрана по отдельным командам и опубликована на developer.qiwi.com.
Аутентификация стала ключевой проблемой первого API. Если с точки зрения сайта механизм был правильным (именно так организована аутентификация на большинстве веб-страниц, по принципу двух токенов с разным временем жизни), то пользователю пройти процедуру оказалось довольно сложно. Этот метод изначально не был ориентирован на пользователей, а служил внутренним задачам нашего сайта. В результате возникали различные сложности, к примеру, выскакивала капча «докажите, что вы не робот», что было неожиданностью для пользователей, поскольку API предполагает доступ именно при помощи автоматических систем.
Хотя публикацию открытого API мы никак не афишировали, в сети появилось несколько статей, в том числе с негативными отзывами. На адрес обратной связи api_help@qiwi.com мы получили более сотни писем, смысл которых сводился к тому, что сам по себе API хороший, но аутентификация никуда не годится. Не все пользователи понимали, почему для подключения к финансовому сервису надо проходить столь заковыристую процедуру, в то время как с Instagram или Вконтакте все намного проще. Мы разъясняли, что сложности были обусловлены именно финансовой составляющей, ведь используемый метод (как в аутентификации сайта, так и в API) не должен ставить под угрозу счета клиентов.
Анализируя обратную связь, мы увидели, что API востребован, а критика направлена в основном на систему аутентификации, и приняли решение развивать API дальше.
Обновленный API
Разработка новых методов в рамках API была поручена команде специалистов, которые делают бекэнд для сайта и мобильного приложения QIWI Кошелька. API — их ключевая компетенция, именно эта команда переводит основной сайт на архитектуру микросервисов. И API тут служит для взаимодействия основного сайта и отдельных сущностей через запросы, которые мы передаем нашим пользователям.
Чтобы доработать существующий API и добавить в него новые методы, мы тщательно проанализировали обратную связь от пользователей.
Хотя среди наших клиентов довольно много любителей-энтузиастов, склонных пробовать что-то новое, основная часть пользователей API — профессиональные разработчики, интегрирующие QIWI Кошелек в свои бизнес-процессы (причем, это не интернет-магазины — для юридических лиц у нас предусмотрен отдельный API). В основном речь идет об оптимизации работы Кошелька под собственные нужды: настройке уведомлений, автоматизации оплаты услуг и обмена цифровыми товарами между пользователями, а также других задачах, не связанных с привычной электронной коммерцией.
Опираясь на отзывы, мы предложили новую аутентификацию пользователей через API, добавили новые функции для взаимодействия с Кошельком. В первой версии у нас были описаны запрос баланса, история платежей и отправка перевода. Сейчас их дополнили запрос профиля пользователя, оплата сотовой связи, переводы в банки и на карты по номерам карт, счетов и договоров вместо полных реквизитов.
Новая аутентификация
Для построения системы аутентификации, ориентированной на API, мы использовали стандарт RFC 6749 по открытому протоколу OAuth 2.0. Чтобы аутентификация соответствовала требованиям финансового сервиса, мы обеспечили двухфакторный доступ — по паролю к Кошельку и SMS-коду. Для прохождения процедуры пользователю необходимо выпустить токен, действительный в течение одного месяца (выпуск подтверждается SMS-сообщением). По просьбе пользователей в новой версии OAuth 2.0 мы также открыли возможность выбора прав доступа для токена. К примеру, если требуется запросить баланс или получить историю платежей, токену даются права только на чтение. Всего доступно четыре группы прав доступа:
- доступ к информации о профиле пользователя;
- доступ к балансу Кошелька;
- доступ к истории платежей;
- полный доступ к платежам.
Функция оказалась весьма востребована, менее половины токенов выпускается с полными правами (осуществление платежей), многим нужно лишь получение информации.
Профиль пользователя
Одна из новых функций, родившихся внутри нашей команды, а не из пожеланий клиентов — запрос профиля пользователя. Он позволяет получать различную информацию о Кошельке: дату регистрации, привязанный адрес электронной почты, уровень идентификации Кошелька. Последнее особенно важно для финансового сервиса, поскольку уровень идентификации определяет лимиты по операциям для кошелька. Ранее эту информацию можно было найти в настройках Кошелька на сайте qiwi.com, теперь она доступна и через API.
Отметим, что персональные данные пользователя через запрос профиля не доступны — таково требование безопасности.
Комиссионные тарифы
Следуя пожеланиям пользователей, мы добавили в API возможность запрашивать размер комиссии при проведении операций по любому из доступных поставщиков услуг. Метод этот открыт и прохождения процедуры аутентификации не требует.
Оплата сотовой связи
Еще одно нововведение, инициированное нашими пользователями, — инструмент автоматизации оплаты сотовой связи, например, для телефонов курьеров.
Фактически метод состоит из двух этапов:
- автоматическое определение оператора по номеру телефона и ID поставщика услуг в системе (работает даже для номеров, которые переносились от одного оператора к другому (MNP);
- перевод денег на счет оператора.
Переводы в банки и на банковские карты
По аналогии с оплатой сотовой связи эта группа методов API позволяет автоматизировать переводы на банковские карты систем VISA, MasterCard и национальной платежной системы МИР по России и СНГ. Перевод осуществляется по номеру карты, по нему же определяется платежная система.
Банковский перевод — это отдельный метод, используемый для отправки денег в некоторые банки, с которыми у нас реализован онлайн-протокол моментальных переводов. В отличие от обычных денежных переводов по банковским реквизитам, для этих банков можно использовать большее количество идентификаторов клиента (номер карты, договора, счета и т. п.).
Юридическая сторона вопроса
До последнего времени доступ по API был формально запрещен. Все, что выполнялось при помощи API, делалось на свой страх и риск. Если пользователь распарсил сайт, достал из него какие-то команды, провел операции с кошельком, и у него пропали деньги, всю ответственность за последствия своих действий нес он сам. Техническая поддержка никак не участвовала в решении подобных проблем.
Чтобы таких ситуаций больше не возникало, мы внесли в пользовательское соглашение соответствующие изменения. Теперь API имеет официальный статус наравне с сайтом и мобильным приложением.
Что будет дальше?
Перечисленные методы доступа к данным уже работают, а документация по ним опубликована на сайте developer.qiwi.com.
Завершено внутреннее тестирование, и, опубликовав API, мы перешли ко второму этапу — проверке работоспособности связки «пользователь + документация + API». Этот этап должен ответить на вопросы о том, насколько понятна документация, нужны ли какие-то дополнительные пояснения и т. п. Поэтому мы предлагаем пользователям направлять отзывы на наш адрес: api_help@qiwi.com.
В ближайшей перспективе мы планируем расширить возможности API, предоставив сторонним сервисам методы для регистрации новых и аутентификации существующих пользователей в системе, а также проведения от их имени финансовых операций. Это немного иная модель взаимодействия между нами, пользователем и третьей стороной — сторонним сервисом.
Если вам интересны детали разработки новой версии API, пишите и задавайте вопросы в комментариях — мы постараемся ответить на них в наших следующих публикациях.
Внимание, конкурс
Чтобы заинтересовать разработчиков в использовании нового API, мы проводим всероссийский QIWI API Contest. Это первый конкурс в рамках QIWI Open Platform, направленный на популяризацию API компании.
Для участия в конкурсе необходимо создать Mobile First решения — чат-боты, мобильные приложения и web-продукты c использованием API QIWI Кошелька. Наши эксперты отберут наиболее проработанные решения и пригласят до 15 участников в финал конкурса, который пройдет в Москве 23 сентября.
Конкурсанты из других городов могут принять участие дистанционно. Регистрация проектов открыта и продлится до 15 сентября. Заявку на участие можно отправить на почту apimarket@qiwi.com. Для всех вопросов мы создали специальный чат в Telegram.