Как реализовать интеграцию с внешним сервисом: гайд на примере ЮКаssы

На сегодняшний день существует огромное множество готовых решений под разные требования бизнеса, что позволяет разработчикам не “пилить” свое решение, а просто воспользоваться чужим, уже продуманным и протестированным сервисом. Динамические карты, платежные системы, системы складского учета, проверка корректности вводимых данных и многое-многое другое. Красота! Надо всего лишь взять их методы и адаптировать под свою систему. Но вот тут-то начинается самая веселая часть — разобраться с чужой API-документацией.

API-документация — это справочный материал, который описывает, как использовать определённый интерфейс программирования приложений (API). Она содержит информацию о доступных функциях, методах, параметрах, форматах запросов и ответов, а также примеры использования.

Именно она — ключ к чужому сервису, без нее ничего путного просто не получится, как минимум, с большим трудом. И задача по разбору и тестированию API чаще всего ложится на плечи системного аналитика. Как подступится? С чего начать? На эти другие основные вопросы постараемся дать ответ в этой статье. А работать будем на примере API-документации ЮКаssы.

План работ по реализации интеграции

Чтобы обрисовать, какие шаги необходимо пройти для достижения нашей цели, составим примерный план работ:

1. Поиск API-документации сервиса
2. Анализ содержания документации
3. Получение тестовых доступов для тестирования API
4. Составление требований по интеграции

1. Поиск API-документации сервиса

Итак, вариантов может быть несколько:

1. Документация есть в открытом доступе на сайте сервиса или в виде ссылки на Postman/Swagger или облачное хранилище.

Открывая официальный сайт сервиса, можно найти раздел “Для разработчиков” или “Как подключить” (в общем, ищите что-то на это похожее или просто в поисковике введите название сервиса + API). У крупных и популярных сервисов, как Юкаssa, найти документацию не составит труда — переходим по пункту в меню “Разработчикам” и попадаем на весьма аккуратную и структурированную по содержанию страницу с API.

2. Документацию нужно запрашивать по почте/другим источникам связи компании

Бывает так, что компания не публикует официально документацию, поэтому по указанным на сайте контактам придется обратиться к ним напрямую и запросить документы. Тут как повезет — могут прислать ссылку на оформленную документацию в том же Swagger, а могут написанную на коленке в Word.

3. Документации нет вовсе (в чем очень вам сочувствуем)

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

В любом случае, ситуация неприятная и придется пробовать несколько вариантов:

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

b. Самостоятельное изучение трафика при помощи инструментов разработчика (DevTools или другие дополнительные инструменты). Придется анализировать посылаемые запросы, их результаты и структуру ответов, пробовать отправлять запросы самостоятельно, подставлять в них разные данные и, таким образом, выделить для себя необходимые методы с их URL.

c. Использование кодовой базы или SDK: иногда, если документация отсутствует, можно исследовать кодовую базу сервиса или его SDK, если она доступна. Там можно найти полезные комментарии, примеры и структуры данных. Например, у ЮКаssы есть отдельный раздел с их SDK Использование SDK — Прием оплаты API ЮKassa, который можно использовать для интеграции со своим сервисом.

SDK (Software Development Kit) — это набор инструментов и библиотек, которые позволяют разработчикам легко интегрировать функциональность определённого сервиса или платформы в свои приложения.

SDK включает:

• библиотеки кода,
• примеры кода,
• документацию,
• инструменты для отладки и тестирования.

2. Анализ содержания документации

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

1. С какой целью мы делаем интеграцию?

Точное понимание, что мы хотим получить от чужого сервиса позволит верно определить состав необходимых для этого методов, которые наш сервис будет вызывать. Допустим, наша цель — добавление возможности оплаты заказов в нашем приложении через Юкаssу, а именно:

• совершение оплаты
• подтверждение платежа
• отмена платежа (при необходимости)

Для реализации этого функционала у ЮКаssы есть следующие методы:

• метод “Создание платежа”. Этот метод создаёт новый запрос на оплату. С его помощью вы инициируете платёж и указываете параметры, такие как сумма, валюта, описание и т.д. Также можно указать необходимость подтверждения платежа.

• метод “Подтверждение платежа”. Этот метод используется для подтверждения платежа, если у вас настроено ручное подтверждение (опция capture=false при создании платежа).

• метод “Отмена платежа”. Если платёж не был завершён или есть необходимость его отменить (до его подтверждения), этот метод позволяет отменить платёж.

2. Как обеспечить доступ к вызову методов?

Все платные сервисы предусматривают аутентификацию (будь то доступ по логину и паролю или получение токена) для получения возможности пользования их методами. У ЮКаssы есть два способа аутентификации: HTTP Basic Auth (основной) и OAuth (только для тех, кто использует API для партнеров). Во втором варианте мы получает токен сроком жизни 5 лет, который можем использовать как параметр заголовка во всех методах.

3. Как обрабатывать ошибки и исключения?

Успешная интеграция зависит от правильной обработки ошибок. Нужно внимательно изучить документацию о возможных ошибках, которые может возвращать API, и предусмотреть логику их обработки в вашем сервисе. Это включает в себя ошибки, связанные с аутентификацией, правами доступа, некорректными данными и сбоями на стороне стороннего сервиса. У ЮКаssы, например, есть целый раздел с толкованием всех кодов ошибок, а также конкретные значения для конкретных запросов Обработка ответов: коды ответа HTTP — Прием платежей по API ЮKassa. При обработке запроса ЮKassa возвращает в теле ответа созданный, измененный или запрошенный объект или список объектов. Формат тела ответа — JSON. Параметры тела ответа зависят от запроса. Более того, у ЮКаssы есть продуманные сценарии неуспешных платежей, что позволяет с точностью определить причины невыполненных операций Неуспешные платежи — Прием платежей по API ЮKassa.

4. Какие есть ограничения по использованию?

Важно учитывать ограничения стороннего сервиса — например, лимиты на количество запросов (rate limiting), ограничения на размер данных или специфику работы с API в рамках определенных временных интервалов. Это поможет избежать неожиданных проблем с доступностью сервиса. У ЮКаsss, например, есть ограничение на количество запросов в 1000 запросов в минуту на один ключ API. Если превышены лимиты, сервер ЮKassa может вернуть код ошибки 429 (Too Many Requests). В этом случае нужно либо снизить частоту запросов, либо ждать определённое время перед следующей попыткой.

5. Действительно ли все работает?

Важно протестировать запросы, которые планируются к использованию.

3. Получение тестовых доступов для тестирования API

Для этого многие сервисы предоставляют либо “песочницы” (например, ВКонтакте), либо тестовые среды, где можно наглядно проверить все возможные сценарии, либо, получив тестовые данные для аутентификации, можно протестировать самостоятельно (например, в Postman). Это необходимо, поскольку бывает так, что API меняется, но документацию не актуализируют или, наоборот, документация не соответствует тому, что есть в реальности. У ЮКаssы есть тестирование практически всех запросов через их веб-интерфейс, и даже представлены тестовые данные банковских карт Тестирование — Прием оплаты API ЮKassa.

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

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

Рассмотрим несколько примеров тестовых сценариев для интеграции с ЮКаssой:

Тестовый сценарий 1: Успешная оплата

Цель: Проверить, что система корректно обрабатывает успешную оплату через Юкассу.

Шаги:

• Пользователь выбирает оплату через Юкассу.
• На странице оплаты вводит некорректные данные карты (например, истекший срок действия).
• Юкасса возвращает ошибку с кодом card_expired или invalid_card.
• Система обрабатывает ответ и информирует пользователя об ошибке.

Ожидаемый результат:

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

Тестовый сценарий 2: Ошибка при вводе данных карты

Цель: Проверить обработку ошибки при вводе некорректных данных карты.

1. Шаги:
   • Пользователь выбирает оплату через Юкассу.
   • На странице оплаты вводит некорректные данные карты (например, истекший срок действия).
   • Юкасса возвращает ошибку с кодом card_expired или invalid_card.
   • Система обрабатывает ответ и информирует пользователя об ошибке.
2. Ожидаемый результат:
   • Пользователю показывается сообщение об ошибке с рекомендацией проверить данные карты или использовать другую карту.
   • Платеж не проходит, статус заказа остается без изменений.

Тестовый сценарий 3: Превышен лимит запросов к API

Цель: Проверить реакцию системы на превышение лимита запросов (rate limiting).

1. Шаги:
   • Система отправляет большое количество запросов к API Юкассы за короткий промежуток времени (более 1000 за 1 минуту).
   • API Юкассы возвращает ответ с кодом ошибки 429 Too Many Requests.
   • Система обрабатывает этот ответ и применяет логику задержки перед повторной отправкой запроса.
2. Ожидаемый результат:
   • Система корректно идентифицирует ошибку превышения лимита.
   • Происходит задержка перед повторной попыткой, и запросы больше не отправляются мгновенно.
   • Пользователю показывается сообщение о временной недоступности услуги или задержке обработки платежа.

4. Составление требований по интеграции

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

Кроме простого списка методов, которые ваш сервис будет вызывать, есть много моментов, на которые важно обратить внимание.

1. Описание процесса аутентификации — необходимо кратко описать тип аутентификации, способ и данные для нее (например, токен). Например, для ЮКаssы — данные для аутентификации запросов необходимо передавать в заголовке запроса в параметре Authorization.
2. Краткое описание метода — оставьте небольшое пояснение, понятное именно в контексте вашего сервиса и с какой целью этот запрос будет использоваться.
3. Описание входных данных — у запросов на вход может быть указано много различных параметров, как обязательных, так и необязательных. В документации важно отобразить, какие именно из всех параметров будет передавать именно ваш сервис, а также как и чем их заполнять, т.е. необходимо составить mapping.

Mapping — это процесс сопоставления полей данных (определенных элементов источника или всего источника) и связанных с ними полей данных в другом месте назначения. То есть это установление соотношения между моделями данных, которые находятся в разных источниках или системах.

Например, метод создания платежа на вход принимает объект amount — сумма платежа и валюта, который состоит соответственно из двух полей currency и value. Предположим, что в вашем сервисе в базе данных информация для этого параметра хранится в таблице Order в поле Sum, а валюта по-умолчанию рубли. Тогда mapping для этого параметра может выглядеть следующим образом:

Название параметра ЮКаssa	Название таблицы и поля в БД	Примечания
amount.value	Order.Sum	Сумма в выбранной валюте. Всегда дробное значение. Разделитель дробной части — точка, разделитель тысяч отсутствует. Количество знаков после точки зависит от выбранной валюты. Пример: 1000.00.
amount.currency	«RUB»

Кроме того, важно проверить соответствие типов данных у ЮКаssы и у вашего сервиса. Тот же параметр amount.value имеет строковый тип (string), а сумма заказа в вашей БД может храниться с типом NUMERIC. Несовпадение типов данных может привести к ошибкам в выполнении запросов.

Описание выходных данных — в результате успешного выполнения запрос также возвращает определенный набор данных, который нужно правильно обработать для дальнейшего использования.

Для них также необходимо составить mapping, но уже в обратную сторону — значение из каких полей ответа в какие поля вашей БД нужно сохранить или как их интерпретировать и где дальше использовать. Более того, возможно понадобится дополнить существующую модель базы данных новыми атрибутами и/или таблицами, в которые полученные данные будут записываться (это, кстати, касается и входных данных — убедитесь, что у вас есть все необходимые данные для заполнения параметров запроса).

Коды ответов — перечисление всех возможных кодов ответов HTTP и их толкование.

Некоторые сервисы указывают их для каждого запроса отдельно, некоторые, как ЮКаssа — делают общий список под все запросы.

Рассмотрим пример полного описания требований по интеграции для одного из методов ЮКаssы:

Требования по интеграции с ЮКасса: Метод создания платежа

1. Аутентификация

Для взаимодействия с API ЮКассы необходимо использовать OAuth 2.0. Аутентификация осуществляется с помощью токена доступа, который должен быть получен заранее.

• Endpoint для получения токена: POST /oauth/token
• Параметры:
  • client_id — Идентификатор клиента (string)
  • client_secret — Секрет клиента (string)
  • grant_type — Тип доступа (например, client_credentials)

2. Описание метода: Создание платежа

Метод: POST /v3/payments

Описание: Создает платеж для дальнейшей оплаты клиентом через Юкассу. При успешном создании возвращается ссылка для перенаправления клиента на платежную страницу.

3. Входные данные

Запрос должен содержать информацию о платеже, заказе и клиенте.

Пример тела запроса:

{
  "amount": {
    "value": "1500.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "return_url": "https://example.com/return_url"
  },
  "capture": true,
  "description": "Оплата заказа №12345",
  "metadata": {
    "order_id": "12345"
  }
}

Мэппинг входных данных:

Поле ЮКаssа	Источник данных	Описание	Обязательное
amount.value	Order.Sum	Сумма платежа	Да
amount.currency	Константа (RUB)	Валюта платежа (например, «RUB» для рубля)	Да
confirmation.type	Константа («redirect»)	Тип подтверждения (здесь — «redirect»)	Да
confirmation.return_url	Конфигурация сайта	URL для возврата после оплаты	Да
capture	По умолчанию true	Автоматическое подтверждение платежа (true/false)	Да
description	“Платеж № <Order.Order_id>”	Описание платежа, включая номер заказа	Да
metadata.order_id	Order.Order_id	ID заказа для связи с системой заказов	Да

4. Выходные данные

Ответ от API содержит информацию о созданном платеже, включая ссылку для перенаправления пользователя на страницу оплаты.

Пример тела успешного ответа:

{
  "id": "21b81356-000f-5000-9000-1bfb77c4b5c5",
  "status": "pending",
  "amount": {
    "value": "1500.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "confirmation_url": "https://yoomoney.ru/payments/confirm/abcdef123456"
  },
  "created_at": "2024-10-01T12:34:56.000Z",
  "description": "Оплата заказа №12345",
  "metadata": {
    "order_id": "12345"
  }
}

Мэппинг выходных данных:

Поле ЮКаssа	Путь сохранения в БД	Описание	Назначение
id	Payment.Id	Уникальный идентификатор платежа в системе Юкасса	Для хранения в системе
status	Payment.Status	Текущий статус платежа (pending, succeeded, etc.)	Для отслеживания статуса платежа
confirmation.confirmation_url	—	URL для перенаправления клиента	Для перенаправления клиента на страницу оплаты
created_at	Payment.Created_at	Дата и время создания платежа	Для логирования
metadata.order_id	Payment.Order_id	ID заказа, переданный в запросе	Для связи с внутренним заказом

5. Коды ответов

Код ответа	Описание
201	Платеж успешно создан. Возвращается ID платежа и URL для оплаты.
400	Ошибка в запросе (некорректные данные). Проверьте параметры.
401	Ошибка аутентификации (некорректный API-ключ).
403	Доступ к API запрещен (отсутствуют нужные права).
404	Ресурс не найден.
500	Внутренняя ошибка сервера Юкасса. Повторите запрос позже.

Вывод: чего делать не стоит, а о чем точно нельзя забыть

1. Неполное или неверное понимание бизнес-целей интеграции

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

Как избежать: Проводить тщательный анализ целей проекта с заказчиком, формулировать четкие и конкретные требования.

2. Ошибки в сборе требований

• Ошибка: Неполный или неточный сбор требований, отсутствие учета всех возможных сценариев использования (успешные, неуспешные, редкие случаи).
• Последствия: Неполная функциональность, недостаточная гибкость системы, проблемы при тестировании и эксплуатации.

Как избежать: Использовать разные техники сбора требований (интервью, воркшопы), документировать все возможные сценарии использования, активно взаимодействовать с заинтересованными сторонами.

3. Неправильная интерпретация API документации

• Ошибка: Неправильное понимание работы методов API, отсутствия у некоторых методов необходимых прав доступа или неправильное использование аутентификации.
• Последствия: Некорректная интеграция, ошибки в работе приложения, вызов не тех методов API.

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

4. Неправильная интерпретация API документации

• Ошибка: Неправильная настройка аутентификации (некорректный формат токена, неправильный API-ключ).
• Последствия: Система не сможет вызывать методы API, доступ будет запрещен.

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

5. Некорректный мэппинг данных

• Ошибка: Неверное сопоставление полей между внешним сервисом и внутренней базой данных.
• Последствия: Потеря или искажение данных, невозможность обработки ответов от API, ошибки в бизнес-логике.

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

6. Игнорирование кодов ошибок и обработка исключений

• Ошибка: Неучет возможных ошибок при вызове методов API и неправильная их обработка (например, игнорирование кодов ошибок HTTP, таких как 400, 401, 500).
• Последствия: Система не будет реагировать на ошибки должным образом, пользователь получит некорректную информацию или вообще не узнает о проблеме.

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

7. Ошибки в работе с лимитами запросов (Rate Limiting)

• Ошибка: Превышение лимита запросов к внешнему API.
• Последствия: Ограничение или временная блокировка доступа к сервису, проблемы с выполнением операций.

Как избежать: Проверить лимиты запросов и встроить механизм повторных попыток с задержкой, а также учесть эти лимиты в архитектуре системы.

8. Отсутствие тестирования крайних сценариев

• Ошибка: Тестирование только базовых (нормальных) сценариев, без учета ошибок, граничных значений и нестандартных ситуаций.
• Последствия: Невозможность обработки редких, но критичных ошибок в реальной эксплуатации.

Как избежать: Тестировать различные сценарии, включая неудачные оплаты, превышение лимитов, ошибки аутентификации и некорректные данные.

9. Отсутствие контроля версий API

• Ошибка: Игнорирование версий API при интеграции (например, использование устаревшей версии API).
• Последствия: Некорректная работа интеграции при изменениях в API, возможные сбои в работе сервиса.

Как избежать: Убедиться в использовании актуальной версии API и следить за обновлениями документации.

Таким образом, выполнив все указанные шаги, вы с большей долей вероятности составите действительно толковую документацию для интеграции, за которую разработчики будут говорить вам “спасибо” и только “спасибо”, без лишних дополнительных вопросов, уточнений и недопониманий. А если вдруг вам доведется составлять API-документацию вашего сервиса, то вспомните, как тяжело и грустно работать без нее или с ней, но составленной “на коленке” и никогда так не делайте. Делайте, как, например, ЮКаssа — подробно, понятно и информативно.