[Из песочницы] Как минимизировать ошибки при интеграции с внешними сервисами: опыт онлайн-брокера

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

В результате последнюю интеграцию мы сделали в четыре раза быстрее, чем первую. Но при каждой новой интеграции мы придумывали решения для повторяющихся проблем. Мы развиваем онлайн-брокера. Что теперь мы делаем иначе — читайте в статье.
Чтобы вы лучше понимали специфику наших интеграций, вкратце расскажем, чем мы занимаемся. Пользователь выбирает подходящее предложение и получает деньги. Принцип работы: на сайт приходит пользователь, заполняет анкету, мы передаем ее микрофинансовым организациям (МФО) и получаем от них одобрение или отказ по займу. Чтобы всё это работало онлайн, мы интегрируемся с МФО по API.

Оценка готовности партнера к интеграции с помощью чек-листа и спецификации

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

У партнера нет API — отправляем спецификацию

Раньше мы объясняли партнеру устно или в переписке, что нам нужно для интеграции, а партнер на основе этих объяснений делал API для приема заявок с Finspin. Мы не согласовывали требования к моделям, объектам, полям анкеты и правилам их валидации. Бегло описывали назначения методов и возможные ответы. Результат оказывался бесконечно далеким от ожидаемого, потому что наше понимание API сильно расходилось с партнерским. Приходилось все переделывать.

Мы написали свою спецификацию — YAML-файл, который можно открыть в Swagger. Сейчас. Зафиксировали статусы состояния заявки, которые планируем получать, например: «принято в обработку», «идет скоринг», «отказано в займе», «одобрение» и т. В спецификации мы описали самое подходящее API для интеграции Finspin с МФО: поля анкеты и правила их валидации, форматы и типы запросов c ответами, названия методов, возможные ошибки и статусы. д.

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

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

У партнера есть API — прогоняем по чек-листу

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

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

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

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

Фрагмент чек-листа для оценки API

Словарик терминов

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

Для нас первичный клиент — это клиент, анкета которого впервые попала в базу МФО через Finspin, а повторный клиент уже был в базе. Например, с одним МФО мы по-разному трактовали первичных и повторных клиентов. Такая терминологическая путаница могла привести к нестыковкам при финансовых сверках. Партнер считал повторными клиентов по количеству выданных займов: повторные получили два займа и пришли за третьим.

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

Наша трактовка «одобрения» сильно отличалась от партнерской. Однажды словарик терминов помог нам избежать невыгодной интеграции. Мы же стремимся к максимальной автоматизации, поэтому сразу отказались от сотрудничества. У партнера «одобрение» включало в себя много разных аспектов, требующих ручной обработки.

Уточняем термин “Одобрение”

Сначала бизнес, потом разработка

Раньше были случаи, когда мы начинали работу с потенциальным партнером со спецификации. Наш менеджер получал спецификацию, внимательно ее штудировал, уточнял у партнера детали для интеграции, обсуждали спорные моменты с разработчиками. А потом от руководства прилетало сообщение: «Отбой, интеграция отменяется, не договорились по условиям». Сотрудники впустую потратили время.

Когда передумали, а работа сделана

Сейчас действует железное правило: менеджер приступает к изучению спецификации только тогда, когда получает от руководства однозначное решение об интеграции.

Готовность к интеграции: урлы, реквизиты, окружение

Раньше первое обращение к API партнера происходило во время тестирования нашего приложения, с dev серверов. Часто первые запросы получали ошибки на этапе установки соединения: can not connect to server или просто таймаут. Самые популярные причины:

• неправильные названия методов (опечатались или перепутали),
• неверный домен,
• ошибочные реквизиты подключения,
• не добавили в white-лист IP наших серверов.

На исправление таких мелких ошибок уходили часы, потому что они шли друг за другом: пока не исправишь одну, не увидишь следующую.

В чек-листе перечислены пункты, которые нужно прояснить, например: Сейчас, перед тем как взять задачу в план разработки, мы уточняем все особенности обращения к API по небольшому чек-листу.

• ограничения по нагрузке на сервис,
• количество запросов в единицу времени,
• реквизиты подключения,
• white-list по ip-адресам,
• валидация SSL-сертификата,
• требования к шифрованию трафика,
• наличие особых заголовков в запросах,
• наличие тестового сервера с API или возможности отправлять тестовые запросы на боевой сервер

Если есть тестовое API, мы обязательно узнаем, в чем разница при обращении к боевому серверу и тестовому. Мы учитываем различия при построении запросов от нашего приложения к партнерам в dev и prod окружении. Такие меры помогают нам понять, готова ли системы к нашим запросам или нужны донастройки.

Отправка запросов в API вручную

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

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

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

Мы описываем ошибки и передаем партнеру. На этапе ручного прогона вскрывается 80% неточностей в документации. В результате к моменту старта работы над кодом разработчики получают рабочую документацию. Партнер либо устраняет неточности у себя, либо дорабатывает спецификацию.

Самые популярные расхождения:

• неверный формат запросов, обещают принимать json, оказалась нужна form-data;
• ошибки в названиях полей, которые надо передать в запросе;
• ошибки в форматах полей;
• не указаны или указаны ошибочно правила валидации полей;
• могут быть вообще забыты некоторые поля;
• отсутствуют или отличаются от фактических описания формата ответа метода;
• ошибочные отметки об обязательности полей — “звездочки” могут стоять там, где поле по факту не обязательное, и наоборот;
• часто не задокументированы все состояния и статусы, в которых может находиться объект;
• расхождения между ожидаемыми и получаемыми состояниями объектов. Например, в какой-то момент ждем, что заявка должна находиться в состоянии X — а по API по факту получаем Y.

Рецепт счастья: как избежать ошибок при интеграции по API

Напишите спецификацию по интеграции с вашим сервисом. Мы потратили на разработку спецификации в YAML два дня, зато сейчас экономим десятки часов на доработках и согласованиях.

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

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

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

д. Заведите чек-лист для уточнения особенностей обращения к API партнера: реквизиты подключения, white-list, валидация SSL-сертификата, требования к шифрованию трафика и т. Сверьтесь по чек-листу как можно раньше, чтобы избежать пробуксовок на финальных этапах.

Сперва вручную прогоните процесс через API-клиент, например через Postman. Получили спецификацию — не спешите сразу писать код. А они будут. Так вы на раннем этапе и небольшими ресурсами найдете ошибки в спецификации.