За полтора года мы интегрировались по 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 вручную

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

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

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

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

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

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

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

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

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

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

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

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

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