Frog StudiosFrog Studios
Заявка
Разработка

API-интеграции: как сделать их надёжными и не терять заказы

23 октября 20266 мин
Разработка
Надёжные API

Почему интеграции ломаются чаще, чем кажется

Современный бизнес-сервис редко работает сам по себе: платёжная система, доставка, CRM, СМС, карты, учётная система. Каждая интеграция — зависимость от чужого сервиса, у которого свои сбои, лимиты, изменения и ошибки. Если относиться к API как к «функции, которая всегда отвечает», первый же сбой превращается в потерянные заказы и недовольных клиентов.

Хорошая новость: надёжность интеграции — это набор понятных инженерных приёмов, а не магия.

Основные приёмы надёжной интеграции

  1. Таймауты. Каждый внешний запрос ограничен по времени. Без этого один зависший сервис подвешивает весь ваш.
  2. Повторы с нарастающей паузой. Временные ошибки (недоступность, перегрузка) часто проходят при повторе, но повторять нужно с увеличением интервала и случайным разбросом, иначе вы добьёте и без того перегруженный сервис.
  3. Идемпотентность. Повторный запрос не должен приводить к повторному действию. Для платежей и создания заказов используйте уникальный ключ операции, чтобы повтор не создал второй заказ.
  4. Очереди. Не делайте тяжёлые или ненадёжные вызовы в момент, когда пользователь ждёт ответа. Положите задачу в очередь и обработайте в фоне, а пользователю покажите «заявка принята».
  5. Предохранитель (circuit breaker). Если сервис долго не отвечает, на время перестаём его вызывать и сразу отдаём запасной сценарий, чтобы не копить зависшие запросы.
  6. Запасной сценарий. Что увидит клиент, если доставка недоступна? Пример: показать фиксированный тариф и уточнить стоимость позже.
  7. Ограничение частоты. Соблюдайте лимиты внешнего API, иначе вас временно заблокируют.

Вебхуки: как не потерять события

Многие сервисы сообщают о событиях (оплата прошла, статус изменился) вебхуками. Правила работы с ними:

  • Отвечайте быстро кодом успеха, а обработку делайте в фоне.
  • Проверяйте подпись или секрет, чтобы никто не мог подделать уведомление. Данные из вебхука без проверки — недоверенные.
  • Учитывайте дубли и неправильный порядок: одно событие может прийти дважды, а событие «оплачено» раньше «создано».
  • Периодически сверяйтесь со справочником статусов через обычный запрос: вебхук может потеряться.

Версии и изменения чужого API

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

| Мера | Зачем | |---|---| | Фиксировать версию API в запросах | Не получать молча изменённое поведение | | Подписаться на рассылку об изменениях | Узнавать о закрытии версий заранее | | Тест-контракт на ключевые ответы | Автотест сигнализирует, когда формат изменился | | Слой-адаптер в коде | Менять только одно место при смене провайдера | | Не опираться на недокументированные поля | Они исчезают без предупреждения |

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

Безопасность интеграций

  • Ключи API хранятся в защищённом месте, а не в коде и не в публичном репозитории; у каждой среды свои ключи.
  • Выдавайте ключам минимально необходимые права.
  • Не логируйте полные запросы с персональными и платёжными данными.
  • Передавайте данные только по защищённому соединению и проверяйте сертификаты.
  • Периодически меняйте ключи и умейте отозвать скомпрометированный за минуты.
  • Передача персональных данных стороннему сервису — вопрос для юриста, проверяйте с юристом.

Мониторинг: что измерять

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

Как подготовиться к сбою: чек-лист

  1. Для каждой интеграции записано, что происходит при недоступности и кто об этом узнаёт.
  2. Заказы и заявки не теряются: они сохраняются у вас до подтверждённой передачи.
  3. Есть способ повторно обработать пропущенные события вручную или скриптом.
  4. Тесты имитируют ошибки: таймаут, неверный ответ, дубликат.
  5. Контакты технической поддержки партнёров и статус-страницы собраны в одном месте.
  6. Раз в квартал проводите учебное отключение одной интеграции в тестовой среде и смотрите, что получается.

Пример подхода: интеграция с платёжной системой

Разберём упрощённый сценарий. Покупатель оплачивает заказ, и платёжная система присылает вебхук. Ваш сервис проверяет подпись, находит заказ по уникальному идентификатору и меняет статус на «оплачен» только если он ещё не оплачен: повторный вебхук ничего не ломает. Если платёжная система недоступна в момент создания платежа, заказ остаётся в статусе «ожидает оплаты», а пользователь видит понятное сообщение и может повторить попытку. Раз в несколько минут фоновая задача сверяет статусы зависших платежей со справочником платёжной системы, чтобы вебхук, потерянный по дороге, не оставил заказ неоплаченным. Каждое из этих решений простое, но вместе они отличают надёжную интеграцию от хрупкой.

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

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

Итог

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

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


Frog Studios проектирует интеграции с платёжными, логистическими и учётными системами с обработкой сбоев и мониторингом.

Теги
APIИнтеграцииВебхукиНадёжность

Читайте также

Похожие статьи

Все статьи

Начать проект

Готовы обсудить проект?

Оставьте заявку — ответим в течение часа. На первой встрече разберём задачу и покажем релевантные кейсы.

✓ Ответ за 1 час в рабочие дни✓ NDA по запросу✓ Первая встреча — без предоплаты: рамка задачи, кейсы, ориентир по бюджету и сроку

Оставить заявку

Первая встреча — 30–45 минут, без предоплаты. Дальше — КП с ценой и сроком, которые фиксируем в договоре.